Додавання кастомних хуків до WordPress: Custom Filters

Сьогодні ми поговоримо про систему хуків у WordPress. Ми розглянемо хуки дій та фільтри, та їх роль у розвитку WordPress.

Ці обидва види хуків відіграють особливу роль у розвитку WordPress. Якщо ви хочете стати досвідченим розробником WordPress, потрібно не тільки розуміти різницю між цими хуками, але і вміти їх застосовувати.

Ми вже розповідали вам про те, що таке хуки та як їх можна використовувати. Але перед тим, як ми розпочнемо нашу сьогоднішню тему, давайте згадаємо, що ми обговорювали у минулій статті.

Дивіться також:

• Додавання кастомних хуків до WordPress: Custom Actions
• Поради для початківців розробку сайту на WordPress
• Посібник з кастомних типів записів WordPress
• Custom Post Types: таксономії, фільтри та архіви в WordPress
• Що таке Формати постів у WordPress і для чого вони потрібні
• Що слід знати про формати постів у WordPress

Приступимо!

Освіжимо у пам'яті

В попередній статті на цю тему ми побачили, як хуки є використанням подієво-орієнтованої архітектури. Ми виділили кілька моментів:

• У програмного забезпечення є кілька моментів, коли воно передає повідомлення, що щось сталося.
• Ми, як розробники, можемо написати код, який прийматиме ці повідомлення і відповідатиме на них з кодом користувача.

І потім на прикладі контенту ми побачили, як саме це діє WordPress. Ми розповіли про його переваги та про впровадження власних хуків дії.

До того ж, ми дізналися про тонку відмінність:

Хуки дій призначені до роботи з функціональністю, а фільтри – з даними.

У той час, як дії дозволяють нам змінювати чиюсь поведінку, фільтри дозволяють нам змінювати дані до їх збереження, перевірки або відображення на екрані. У цій статті ми розглянемо, як працювати з фільтрами до виведення даних на екран, наприклад, написання тексту малими літерами або видалення голосних тексту.

До того, як ми почнемо, потрібно переконатися, що наше середовище розробки налаштоване та готове до роботи.

Приступимо

Згадаймо з нашої попередньої статті, що наше середовище розробки повинно мати у складі:

• WordPress
• Веб-сервер
• Копія PHP
• База даних

В основному Apache, PHP та MySQL можна встановити легко. Якщо ви вже досвідчений користувач, можете використовувати щось типу Nginx і альтернативну базу даних. Якщо це так – чудово, але в цьому посібнику ми будемо використовувати наш початковий список.

Розуміння фільтрів у WordPress

WordPress Codex надає повний набір ресурсів для тих, хто хоче дізнатися про фільтри. Як ми вже говорили, він дає таке визначення фільтрів:

Фільтри користувача відрізняються від користувацьких Дій, оскільки користувацькі Дії дозволяють вам додати або видалити код з існуючих Дій. А користувацькі Фільтри дозволяють вам замінити конкретні дані (наприклад, змінну), що знаходяться в існуючій Дії.

Але якщо вам цікавий весь список доступних фільтрів на WordPress, то обов'язково відвідайте цю сторінку Codex. Багато фільтрів мають посилання на власну сторінку з документацією.

Це означає, що якщо ви шукаєте фільтр із якимись конкретними функціями, то вам варто зайти на цю сторінку. А щоб дізнатися про приклади застосування фільтра, варто зайти до його документації.

Трохи про пріоритети та параметри

Перед тим, як ми підемо далі, ми хочемо переконатися, що всі ми знаходимося на одній сторінці, з однаковим пріоритетом і кількістю аргументів, коли ми говоримо про них у контексті хуків WordPress.

Як приклад можна використовувати наступний рядок коду:

add_filter( 'author_edit_pre', 'filter_function_name', 10, 2 );

Це говорить нам про 4 речі:

1. Ім'я фільтра – це те, до чого ми приєднуємося
2. Ім'я функції – те, що має бути викликане
3. Пріоритет, коли функція має бути викликана
4. Кількість параметрів, які має прийняти функція

Перші два пункти цілком зрозумілі, а два останніх можуть збити з пантелику розробників-початківців, але насправді, це не так вже й складно.

По-першедумайте про пріоритет, як про час, коли потрібно викликати функцію. Пам'ятайте, що у хука може бути кілька функцій, а пріоритет дозволяє визначити час для виклику кожної функції. Чим менше, тим швидше їх запустять, чим більше кількість, там пізніше їх запустять.

По-друге, Число вказує на кількість параметрів, які повинен прийняти аргумент. Якщо ви не вкажете число, він не прийме жодного параметра, або використовує число за замовчуванням. Якщо ви хочете передати іншу кількість параметрів, ви повинні це вказати. Ми розглянемо більш детально трохи пізніше.

Робота з фільтрами

Перед початком роботи з фільтрами, давайте створимо власний файл у корені директорії теми двадцять Шістнадцять. Ми назвемо файл tutsplus-filters.php. А у файл functions.php ми додамо наступний рядок коду:

include_once( get_template_directory() . '/tutsplus-filters.php' );

Це дозволить переконатися, що весь наш код користувача буде знаходитися в одному файлі, який ми можемо видалити.

Фільтрування контенту посту

Перед початком створення власних фільтрів, важливо зрозуміти, як вони працюють. Оскільки фільтри призначені для зміни даних, а записи є єдиними будівельними блоками блогу, то давайте спочатку подивимося, як ми можемо фільтрувати вміст запису блогу до його відображення на екрані.

Це схоже на принцип роботи хуків процесів WordPress, але тут змінюються дані, а не поведінка.

1. Реєстрація нашого фільтра

Для реєстрації нашого фільтра необхідно знати 2 речі:

1. Назва фільтра, до якого ми приєднаємо нашу дію
2. Функцію, яка буде відповідати за фільтр даних

Оскільки ми збираємося змінити контент запису, ми можемо використовувати фільтр the_content. Суть функції полягає в наступному - Вона приймає один аргумент, контент запису, дозволяє нам змінити його, а потім повертає його відвідувачу.

У цьому випадку WordPress передає контент запису функції, а потім функція поверне дані після завершення своєї роботи.

Давайте назвемо нашу функцію користувача tutsplus_the_contentа потім зареєструємо її на WordPress.

add_filter( 'the_content', 'tutsplus_the_content' );
function tutsplus_the_content( $content ) {
    return $content;
}

Приблизно так має виглядати функція. Звісно, ​​вона робить дуже багато. Просто повертає контент, що передається на неї.

2. Зміна контенту

Давайте змусимо функцію трохи змінити дані. Для цього потрібно:

1. Переконайтеся, що запис можна переглянути в окремому вікні
2. Додати повідомлення вгору запису, де повідомляється, що контент запису було змінено

Це не найкращий спосіб використовувати фільтр, але ви зрозумієте, як ви можете змінювати функцію.

Ось так має виглядати код. Зверніть увагу на коментарі у коді:

add_filter( 'the_content', 'tutsplus_the_content' );
function tutsplus_the_content( $content ) {
 
    // Don't proceed with this function if we're not viewing a single post.
    if ( ! is_single() ) {
        return $content;
    }
 
    // First, define the message to be displayed.
    $html .= '<p>';
        $html .= 'This is a custom message created by a hooked function.';
    $html .= '</p>';
 
    // Now prepend it to the content.
    $content = $html .= $content;
 
    return $content;
}

Якщо ви подивіться на основну сторінку блогу, всі пости будуть виглядати стандартно, без змін. Але якщо ви зайдете окремо на сторінку запису, то побачите, що угорі з'явилася нова фраза:

Це custom message created by a hooked function.

А тепер давайте зробимо щось просунуте. Давайте видалимо всі голосні з контенту посту. Перш ніж повернути його на WordPress.

Для цього використовуємо наступний код:

add_filter( 'the_content', 'tutsplus_the_content' );
function tutsplus_the_content( $content ) {
 
    // Don't proceed with this function if we're not viewing a single post.
    if ( ! is_single() ) {
        return $content;
    }
 
    // First, remove all of the vowels from the content using a regular expression.
    $content = preg_replace( '$[aeiou]$i', '', $content );
 
    // Then, define the message to be displayed.
    $html .= '<p>';
        $html .= 'This is a custom message created by a hooked function.';
    $html .= '</p>';
 
    // And now prepend it to the content.
    $content = $html .= $content;
 
    return $content;
}

Вставивши код, збережіть зміни та зайдіть на будь-який запис у WordPress.

Технічно, функція зверху виконує 2 речі, тому для покращення коду ми рекомендуємо розділити її на 2 окремі функції, а наша головна функція фільтра буде викликати їх.

Ось так виглядатиме фінальний результат:

add_filter( 'the_content', 'tutsplus_the_content' );
function tutsplus_the_content( $content ) {
 
    // Don't proceed with this function if we're not viewing a single post.
    if ( ! is_single() ) {
        return $content;
    }
 
    $content = _tutsplus_strip_vowels( $content );
    $content = _tutsplus_add_message( $content );
 
    return $content;
}
 
function _tutsplus_strip_vowels( $content ) {
    return preg_replace( '$[aeiou]$i', '', $content );
}
 
function _tutsplus_add_message( $content ) {
 
    $html .= '<p>';
        $html .= 'This is a custom message created by a hooked function.';
    $html .= '</p>';
 
    return ( $html . $content );
}

І знову, впровадження фільтра – це не найпрактичніше і найкорисніше, що ви можете зробити, але це показує, що ми можемо робити, коли налаштовуємо наші власні функції.

Визначення фільтрів користувача

Легко використовувати існуючі фільтри. Як ми вже говорили раніше, дуже легко викликати add_filter, вказавши назву фільтра, а потім назву функції, яку хочемо викликати для фільтра даних.

Але що, якщо ми хочемо створити наш власний фільтр? Напевно, ми хочемо створити фільтр, який зробить усі літери у нашому пості малими? Чи фільтр, який видаляє всі голосні із запису?

Розуміння apply_filters

І ось тут ми починаємо цікавитись apply_filters. Ця конкретна функція приймає 2 аргументи:

1. тег, який визначає назву хука фільтра
2. значення, яке відноситься до значення застосування фільтра

Прикладом може послужити get_the_content в ядрі WordPress, ви можете помітити, що він передає особливе значення the_content_more_link через apply_filters.

Це корисно знати, але як же нам визначити наш власний фільтр, який всі зможуть застосувати через apply_filters?

Додавання наших власних фільтрів

Додати наші власні фільтри легко. Нам потрібно визначити ті ж 4 речі, які ми описали вище:

1. Назва фільтра
2. Функцію, яку має викликати фільтр
3. Пріоритет функції
4. Кількість аргументів, які він має прийняти

Почнемо з простого прикладу.

Зробити всі літери малими

По-перше, ми хочемо дати фільтру пріоритет 10. Ми знаємо, що він прийме лише один аргумент, контент, тому ми пропустимо номер 1 при додаванні фільтра:

add_filter( 'tutsplus_lowercase_all', 'tutsplus_lowercase_all_callback', 10, 1 );

Далі ми визначимо тіло простої функції, яка використовує PHP strtolower для зниження регістру, байдуже у своїй, яке значення було передано, і повертаємо її.

function tutsplus_lowercase_all_callback( $content ) {
    return strtolower( $content );
}

Кінцева версія коду виглядатиме так:

add_filter( 'tutsplus_lowercase_all', 'tutsplus_lowercase_all_callback', 10, 1 );
function tutsplus_lowercase_all_callback( $content ) {
    return strtolower( $content );
}
 
add_filter( 'the_content', 'tutsplus_the_content' );
function tutsplus_the_content( $content ) {
 
    // Don't proceed with this function if we're not viewing a single post.
    if ( ! is_single() ) {
        return $content;
    }
 
    return apply_filters( 'tutsplus_lowercase_all', $content );
}

Досить просто, правда? Давайте тепер поглянемо ще один приклад, який базується на функціоналі, який ми вже описали.

Видалення всіх голосних

Для видалення всіх голосних ми можемо використовувати ту саму функцію, яку ми вже визначили. Однак, нам потрібно змінити спосіб реєстрації фільтра на WordPress, а потім переконатися, що функція, зареєстрована на WordPress, правильно викликає apply_filters.

Тепер ми знаємо, як додавати власний фільтр, визначати пріоритет, називати кількість аргументів, які він має прийняти, і застосовувати функцію.

Ось фільтр, який викликається сам собою:

add_filter( 'tutsplus_remove_vowels', 'tutsplus_remove_vowels_callback', 10, 1 );
function tutsplus_remove_vowels_callback( $content ) {
    return preg_replace( '$[aeiou]$i', '', $content );
}
 
add_filter( 'the_content', 'tutsplus_the_content' );
function tutsplus_the_content( $content ) {
 
    // Don't proceed with this function if we're not viewing a single post.
    if ( ! is_single() ) {
        return $content;
    }
 
    return apply_filters( 'tutsplus_remove_vowels', $content );
}

Виклик усіх фільтрів разом

Зрештою, можна викликати apply_filters багато разів:

add_filter( 'tutsplus_remove_vowels', 'tutsplus_remove_vowels_callback', 10, 1 );
function tutsplus_remove_vowels_callback( $content ) {
    return preg_replace( '$[aeiou]$i', '', $content );
}
 
add_filter( 'tutsplus_lowercase_all', 'tutsplus_lowercase_all_callback', 10, 1 );
function tutsplus_lowercase_all_callback( $content ) {
    return strtolower( $content );
}
 
add_filter( 'the_content', 'tutsplus_the_content' );
function tutsplus_the_content( $content ) {
 
    // Don't proceed with this function if we're not viewing a single post.
    if ( ! is_single() ) {
        return $content;
    }
 
    return apply_filters( 'tutsplus_lowercase_all',
                    apply_filters( 'tutsplus_remove_vowels', $content )
                 );
}

Зауважте, що це досягає тих самих результатів, що й попередній приклад. Є ще й інші способи, але метою цього посібника було навчити вас, як написати власний фільтр і як застосувати apply_filters у вашій роботі.

Підсумки

Система хуків – це один із найпотужніших аспектів WordPress для розробників. Ви тепер можете не тільки керувати поведінкою та даними WordPress, але й в змозі самостійно визначити хуки, які потім зможуть використати інші розробники.

Не бійтеся експериментувати з кодом, який ми надали.

Джерело: code.tutsplus.com

Олексій Шевченко

редактор wpcafe

Вивчає сайтобудування з 2008 року. Практикуючий вебмайстер, що спеціалізується на створенні сайтів WordPress. Задати питання Олексію можна на https://profiles.wordpress.org/wpthemeus/