Як додати спеціальні налаштування до наявного віджета в WordPress

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

Частина перша; Додавання та збереження власних налаштувань досить просте. Друга частина залежить від того, що саме ви хочете зробити, і від того, яким віджетом ви керуєте. У цій публікації я включив два приклади; пропускання віджета залежно від налаштувань (для додавання налаштувань для керування видимістю віджета в певних випадках) і маніпулювання аргументами меню віджета WordPress Navigation. Приклад, наведений для другої частини, повинен дати вам гарну підказку про те, як ви можете впоратися з тим, що хочете зробити.

Додавання власних налаштувань до будь-якого віджета

Для додавання спеціальних налаштувань до існуючих віджетів ми використовуємо дію під назвою [in_widget_form](https://developer.wordpress.org/reference/hooks/in_widget_form/). Ця дія застосовується до form()функції всіх віджетів, яка відповідає за рендеринг адміністративної частини віджета.

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

Наведений нижче код додасть прапорець із назвою налаштування " awp-custom-setting". Налаштуйте ім’я та HTML відповідно до того, що вам потрібно. Важливо використовувати $widget->get_field_name()для додавання належних ідентифікаторів і nameатрибутів до всіх ваших введених даних. Значення ваших введених даних має бути заповнене тим, що було збережено раніше, і це те, що ви знайдете в параметрі $instance. Для прапорців ви можете використовувати функцію WordPress [checked](https://developer.wordpress.org/reference/functions/checked/)()для виведення атрибута checked.

add_action('in_widget_form', function($widget, $return, $instance) {
    ?>
    <p>
        <input type="checkbox" class="checkbox" name="<?php echo $widget->get_field_name('awp-custom-setting'); ?>" id="<?php echo $widget->get_field_name('awp-custom-setting'); ?>" <?php checked(isset($instance['awp-custom-setting'])? $instance['awp-custom-setting']: 0); ?> />
        <label for="<?php echo $widget->get_field_name('awp-custom-setting'); ?>"><?php __('Activate something', 'txtdomain'); ?></label>
    </p>
    <?php
}, 10, 3);

Після додавання цього до коду вашої теми functions.phpабо плагіна всі віджети тепер мають мати прапорець у кінці форми в адміністраторі.

Націлюйтеся на конкретні віджети

Якщо ви хочете застосувати свої параметри лише до одного або кількох конкретних віджетів, ви можете порівняти властивість id_baseв $widgetоб’єкті. Вам потрібно буде знати базовий ідентифікатор – якщо ви не впевнені, просто виконайте var_dump($widget->id_base)всередині гака, збережіть і перевірте вихід для кожного віджета в admin. Наприклад, віджет Навігація має базу ідентифікаторів nav_menu, а віджет Архів має archives.

У прикладі нижче ми перевіряємо, чи є віджет віджетом навігації. Якщо ні, функція скасовується за допомогою return. Лише навігаційні віджети отримають спеціальний прапорець:

add_action('in_widget_form', function($widget, $return, $instance) {
    if ($widget->id_base != 'nav_menu') {
        return;
    }
 
    ?>
    <p>
    ...

Ви повинні отримати налаштування в адміністраторі так:

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

Збереження власних налаштувань

Нам потрібно підключитися до функції віджета, update()щоб оновити власні налаштування.

Для цього використовуємо фільтр [widget_update_callback](https://developer.wordpress.org/reference/hooks/widget_update_callback/). Процес збереження наших налаштувань точно такий же, як і під час написання класу віджетів. Фільтр забезпечує три параметри; перший — це масив екземплярів, який буде збережено. Другий параметр — це стан, опублікований після збереження віджета, а третій — старий стан. Нам потрібно переконатися, що ми отримуємо нові значення з другого параметра та додаємо їх до першого.

Ось як ми оновлюємо стан нашого прапорця; оскільки ми хочемо зберегти trueабо falseзначення:

add_filter('widget_update_callback', function($instance, $new_instance, $old_instance) {
    $instance['awp-custom-setting'] = isset($new_instance['awp-custom-setting']);
    return $instance;
}, 10, 3);

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

Тепер ви повинні побачити, що ваші спеціальні налаштування зберігаються в адміністраторі!

Використання збережених власних налаштувань віджетів

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

Заборонити візуалізацію віджета залежно від власних налаштувань

Скажімо, ви додаєте налаштування, коли віджет має бути видимим; наприклад, приховати його в певних шаблонах (сховати в шаблоні результатів пошуку, але показати на головній сторінці та окремо) або реагувати на інші стани WordPress.

Для цього ми можемо використовувати фільтр [widget_display_callback](https://developer.wordpress.org/reference/hooks/widget_display_callback/). Все, що нам потрібно зробити, це перевірити наданий параметр екземпляра для нашого налаштування та повернутися, falseякщо ми не хочемо відтворювати віджет.

Цей простий код дозволить уникнути рендерингу віджета, якщо встановлено прапорець, який ми додали вище:

add_filter('widget_display_callback', function($instance, $widget, $args) {
    if ($instance['awp-custom-setting']) {
        return false;
    }
    return $instance;
}, 10, 3);

Можливо, ви хочете порівняти інші штати. Це простий приклад, де наш прапорець є прапорцем для «Сховати в переглядах окремих публікацій». Ми просто перевіряємо, чи ми зараз перебуваємо в будь-якому перегляді окремої публікації за допомогою [is_singular](https://developer.wordpress.org/reference/functions/is_singular/)(), і якщо прапорець позначено, ми повертаємо false.

add_filter('widget_display_callback', function($instance, $widget, $args) {
    if (is_singular() && $instance['awp-custom-setting']) {
        return false;
    }
    return $instance;
}, 10, 3);

Зміна налаштувань або вихідних даних існуючого віджета

Потужним фільтром для використання існуючих віджетів є [dynamic_sidebar_params](https://developer.wordpress.org/reference/hooks/dynamic_sidebar_params/). Перегляньте сторінку документації, щоб дізнатися, які параметри можна змінити. Наприклад, ви можете додати власні класи, ви можете змінити рядки before_widget, after_widgetабо before_titleта after_titleHTML. Однак це стосується всіх віджетів, а також адміністратора та інтерфейсу. І з цим фільтром ви не маєте доступу до екземпляра віджета (збережених налаштувань) або налаштувань віджета (наприклад, типу віджета).

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

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

add_filter('dynamic_sidebar_params', function($params) {
    global $wp_registered_widgets;
 
    $this_widget_id = $params[0]['widget_id'];  // Current widget ID
    $this_widget = $wp_registered_widgets[$this_widget_id];
    $widget_object = $this_widget['callback'][0];  // Current widget object
 
    // With $widget_object we have access to e.g. id_base for checking type of widget
    if ($widget_object->id_base != 'nav_menu') {
        return $params;
    }
 
    return $params;
});

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

Отримання збережених налаштувань віджета

Але нам також потрібно отримати збережені налаштування для кожного віджета (включно з нашими спеціальними налаштуваннями). Усі збережені параметри віджетів зберігаються в базі даних параметрів, згрупованих за типом віджетів. За допомогою властивості в реєстрі віджетів ми можемо використовувати [get_option](https://developer.wordpress.org/reference/functions/get_option/)()для отримання збережених налаштувань для поточного типу віджетів. Поверненням буде індексований масив, де нам потрібно буде використати ще один параметр із фільтра, щоб знайти поточний індекс (оскільки ви можете додати кілька віджетів одного типу на одній або різних бічних панелях). Простіше показати за допомогою коду, ніж пояснити:

    ...
    if ($widget_object->id_base != 'nav_menu') {
        return $params;
    }
 
    $all_settings = get_option($widget_object->option_name);
    $saved_settings = $all_settings[$params[1]['number']];
    if ($saved_settings['my-custom-thing']) {
        // Do your thing
    }
 
    return $params;
});

Нарешті ми отримали збережені налаштування віджета! У наведеному вище прикладі коду, у рядку #9, ми перевіряємо, чи позначено наш настроюваний прапорець.

Приклади

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

    ...
    if ($saved_settings['my-custom-thing']) {
        $params[0]['after_title'] .= '<div>This appears before widget content</div>';
    }
    ...

Для більш реальних випадків використання ви зазвичай вирішуєте більшість, додаючи певні фільтри на цьому етапі, викликаючи add_filter()на цьому етапі.

Нижче наведено приклад зміни аргументів навігаційного меню шляхом додавання фільтра, якщо наше налаштування було позначено. Якщо галочку не було, ми переконаємося, що фільтр видалено. Фільтр для зміни аргументів для відтворення навігаційного меню є widget_nav_menu_args. У наведеному нижче коді я визначив функцію для застосування до цього фільтра, яка додає новий аргумент до аргументів меню; ходок:

    ...
    if ($saved_settings['my-custom-thing']) {
        add_filter('widget_nav_menu_args', 'awp_add_menu_walker', 10, 3);
    } else {
        remove_filter('widget_nav_menu_args', 'awp_add_menu_walker', 10);
    }
    return $params;
});
function awp_add_menu_walker($nav_menu_args, $nav_menu, $args) {
    $nav_menu_args['walker'] = new AWP_Custom_Walker();
    return $nav_menu_args;
}

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

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

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

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

Ось повний код для додавання користувацького прапорця до всіх віджетів навігаційного меню WordPress для використання зареєстрованого засобу переміщення по меню. (Код Walker не входить)

// Add custom setting to menu widgets
add_action('in_widget_form', function($widget, $return, $instance) {
    // Add setting only to menu widgets
    if ($widget->id_base != 'nav_menu') {
        return;
    }
 
    ?>
    <p>
        <input type="checkbox" class="checkbox" name="<?php echo $widget->get_field_name('activate-walker'); ?>" id="<?php echo $widget->get_field_name('activate-walker'); ?>" <?php checked(isset($instance['activate-walker'])? $instance['activate-walker']: 0); ?> />
        <label for="<?php echo $widget->get_field_name('activate-walker'); ?>"><?php __('Activate walker', 'txtdomain'); ?></label>
    </p>
    <?php
}, 10, 3);
 
 
// Update custom setting
add_filter('widget_update_callback', function($instance, $new_instance, $old_instance) {
    $instance['activate-walker'] = isset($new_instance['activate-walker']);
    return $instance;
}, 10, 3);
 
 
// Filter sidebar params to add filter if custom setting was activated
add_filter('dynamic_sidebar_params', function($params) {
    global $wp_registered_widgets;
 
    $this_widget_id = $params[0]['widget_id'];
    $this_widget = $wp_registered_widgets[$this_widget_id];
    $widget_object = $this_widget['callback'][0];
 
    // Bail if not a menu widget
    if ($widget_object->id_base != 'nav_menu') {
        return $params;
    }
 
    $all_settings = get_option($widget_object->option_name);
    $saved_settings = $all_settings[$params[1]['number']];
 
    if ($saved_settings['activate-walker']) {
        add_filter('widget_nav_menu_args', 'awp_add_menu_walker', 10, 3);
    } else {
        remove_filter('widget_nav_menu_args', 'awp_add_menu_walker', 10);
    }
 
    return $params;
});
 
 
// Filter nav menu arguments to add walker
function awp_add_menu_walker($nav_menu_args, $nav_menu, $args) {
    $nav_menu_args['walker'] = new AWP_Custom_Walker();
    return $nav_menu_args;
}

Висновок

Сподіваюся, ця публікація допомогла вирішити ваші потреби або дала підказки щодо того, як ви можете робити те, що вам потрібно!