Как добавить пользовательские настройки к существующему виджету в WordPress

В этом посте мы узнаем, как добавить свой собственный HTML и настройки в любой из стандартных виджетов WordPress или других. Используя эти настройки, мы научимся различным приемам манипулирования поведением виджетов.

Первая часть; добавление и сохранение ваших пользовательских настроек довольно просто. Вторая часть зависит от того, что конкретно вы хотите сделать, и от того, каким виджетом вы манипулируете. В этот пост я включил два примера; пропуск виджета в зависимости от настройки (для добавления настроек для управления видимостью виджета в определенных случаях) и управление аргументами меню виджета навигации WordPress. Пример, приведенный для второй части, должен дать вам хорошее представление о том, как вы можете справиться с тем, что хотите сделать.

Добавление пользовательских настроек к любому виджету

Для добавления пользовательских настроек к существующим виджетам мы используем действие под названием [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/)()для вывода проверенного атрибута.

После добавления этого в functions.phpкод вашей темы или плагина все виджеты теперь должны получить флажок в конце своей формы в админке.

Таргетинг на определенные виджеты

Если вы хотите применить свои настройки только к одному или нескольким определенным виджетам, вы можете сравнить свойство id_baseв $widgetобъекте. Вам нужно знать базовый идентификатор — если вы не уверены, просто сделайте var_dump($widget->id_base)внутри хука, сохраните и проверьте вывод для каждого виджета в админке. Например, у виджета «Навигация» есть база идентификаторов nav_menu, а у виджета «Архивы» — archives.

В приведенном ниже примере мы проверяем, является ли виджет виджетом навигации. Если это не так, функция отменяется с помощью return. Только виджеты навигации получат настраиваемый флажок:

Вы должны получить настройку в админке так:

Итак, настройка добавлена, однако на данный момент ваши настройки не сохраняются. Давайте исправим это.

Сохранение пользовательских настроек

Нам нужно подключиться к 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– который, как мы видели ранее, сообщает нам тип виджета.

Как вы можете видеть в строке #9, мы можем, наконец, проверить, какой тип виджета мы сейчас используем. В приведенном выше коде я возвращаюсь, если тип виджета не является виджетом навигации, поскольку наша пользовательская настройка была добавлена ​​​​только для этих виджетов.

Получение сохраненных настроек виджета

Но нам также нужно получить сохраненные настройки для каждого виджета (включая наши пользовательские настройки). Все сохраненные настройки виджетов хранятся в базе данных настроек, сгруппированных по типу виджета. Используя свойство в реестре виджетов, мы можем использовать [get_option](https://developer.wordpress.org/reference/functions/get_option/)()его для получения сохраненных настроек для текущего типа виджета. Возврат будет индексированным массивом, где нам нужно использовать еще один параметр из фильтра, чтобы найти текущий индекс (поскольку вы можете добавить несколько виджетов одного и того же типа в одну или разные боковые панели). Легче показать кодом, чем объяснять:

Наконец-то мы получили сохраненные настройки виджета! В приведенном выше примере кода в строке #9мы проверяем, установлен ли наш пользовательский флажок.

Примеры

На данный момент это зависит от вас, что вы хотите сделать. Например, вы можете отобразить вывод после заголовка виджета, но перед содержимым виджета:

Для более реальных случаев использования вы обычно решаете большинство, добавляя определенные фильтры в этот момент, вызывая 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 для использования зарегистрированного обходчика меню. (Код Уокера не включен)

Вывод

Надеюсь, этот пост был полезен либо для решения ваших потребностей, либо для того, чтобы дать вам несколько советов о том, как вы можете делать то, что вам нужно делать!