05 Ноя
Создание собственных виджетов — это один из ключевых навыков разработчика WordPress. Виджеты позволяют добавлять динамические элементы в боковые панели, футеры или другие области темы. В этом руководстве рассмотрим, как с нуля реализовать собственный класс виджета на основе WP_Widget и подключить его к плагину.
Зачем нужен кастомный виджет
Стандартные виджеты WordPress подходят не всегда. В eCommerce-проектах, каталогах или сайтах с фильтрацией контента часто требуется выводить динамические фильтры, формы поиска или персонализированные данные. Кастомный виджет позволяет:
- Добавить пользовательский интерфейс для вывода нужных данных;
- Передавать параметры в шорткод или класс плагина;
- Управлять отображением элементов (включать или скрывать поля);
- Сохранять настройки для каждого экземпляра виджета через админку.
Шаг 1. Создание файла класса виджета
Перейдите в директорию своего плагина (например, /includes/) и создайте файл:
class-ali-property-filter-widget.php
Внутри объявляем класс, который расширяет WP_Widget:
class Ali_Property_Filter_Widget extends WP_Widget {
public function __construct() {
parent::__construct(
'ali_property_filter_widget',
__('Фильтр недвижимости', 'textdomain'),
['description' => __('Выводит форму фильтра', 'textdomain')]
);
}
}
Этот конструктор сообщает WordPress, что у нас есть новый виджет с ID, заголовком и описанием.
Шаг 2. Реализация методов widget, form и update
Класс WP_Widget требует обязательной реализации трёх методов:
widget()— отвечает за фронтенд (то, что видит пользователь);form()— за интерфейс настройки виджета в админке;update()— за сохранение данных при изменении настроек.
Пример метода widget()
public function widget($args, $instance) {
extract($args);
$title = apply_filters('widget_title', $instance['title'] ?? '');
echo $before_widget;
if (!empty($title)) {
echo $before_title . esc_html($title) . $after_title;
}
// Вызываем шорткод фильтра (который уже реализован ранее)
echo do_shortcode('[property_filter location="1"]');
echo $after_widget;
}
Здесь виджет выводит заголовок и результат шорткода [property_filter], который отрисовывает форму фильтра.
Пример метода form()
public function form($instance) {
$title = $instance['title'] ?? '';
$location = !empty($instance['location']) ? 1 : 0;
?>
<p>
<label for="<?= $this->get_field_id('title'); ?>">Заголовок:</label>
<input class="widefat"
id="<?= $this->get_field_id('title'); ?>"
name="<?= $this->get_field_name('title'); ?>"
type="text"
value="<?= esc_attr($title); ?>" />
</p>
<p>
<input class="checkbox"
type="checkbox"
<?= checked($location, 1, false); ?>
id="<?= $this->get_field_id('location'); ?>"
name="<?= $this->get_field_name('location'); ?>" />
<label for="<?= $this->get_field_id('location'); ?>">Показывать поле "Локация"</label>
</p>
<?php
}
Форма позволяет задавать заголовок и выбирать, показывать ли поле «Локация». При необходимости добавляются чекбоксы для других полей — например, «Тип», «Цена», «Агент» и т.д.
Пример метода update()
public function update($new_instance, $old_instance) {
$instance = [];
$instance['title'] = sanitize_text_field($new_instance['title']);
$instance['location'] = !empty($new_instance['location']) ? 1 : 0;
return $instance;
}
Этот метод обрабатывает ввод пользователя, очищает данные и сохраняет их в базе.
Шаг 3. Регистрация виджета в плагине
Чтобы WordPress знал о нашем виджете, нужно зарегистрировать его через хук widgets_init:
function register_ali_property_filter_widget() {
register_widget('Ali_Property_Filter_Widget');
}
add_action('widgets_init', 'register_ali_property_filter_widget');
После этого в админке появится новый виджет «Фильтр недвижимости».
Шаг 4. Добавление логики фильтрации
Внутри widget() вы можете вызывать не только шорткод, но и напрямую функции из вашего плагина. Например, можно динамически собирать параметры фильтра из настроек виджета:
$shortcode = '[property_filter';
if ($instance['location']) $shortcode .= ' location="1"';
$shortcode .= ']';
echo do_shortcode($shortcode);
Так пользователь в админке управляет, какие поля отображать, а логика фильтрации остаётся в основном классе плагина.
Шаг 5. Проверка работы
- Перейдите в Внешний вид → Виджеты;
- Найдите свой виджет «Фильтр недвижимости»;
- Перетащите его в нужную область (например, Sidebar);
- Настройте поля и сохраните;
- Проверьте отображение на фронтенде.
Если всё сделано правильно, виджет выведет фильтр с нужными параметрами, а изменения настроек будут сохраняться и влиять на отображение.
Заключение
Кастомный виджет — это удобный способ встроить интерфейс фильтра или другого интерактивного элемента в любую часть темы. Реализация на базе WP_Widget обеспечивает полную интеграцию с ядром WordPress, поддержку мультисайта и возможность повторного использования кода в разных проектах.
Если вы уже создали собственный шорткод для фильтрации, обернуть его в виджет — логичный следующий шаг, который улучшит UX и упростит работу контент-менеджерам.
