Розробка кастомних віджетів WordPress

Розробка користувацьких віджетів WordPress

Віджети WordPress — блоки контенту, розташовані в зареєстрованих областях сайдбарів і футерів через інтерфейс "Зовнішний вигляд → Віджети". Користувацький віджет потребується, коли стандартні віджети (текст, категорії, меню) не охоплюють завдання: вивести останні проекти з фільтрацією, показати форму підписки з конкретною логікою або відрендерити віджет із зовнішнього API.

Розробка одного віджета займає 4–8 годин.

Базова структура класу віджета

Будь-який користувацький віджет розширює WP_Widget:

class My_Projects_Widget extends WP_Widget {

    public function __construct() {
        parent::__construct(
            'my_projects_widget',             // ID віджета
            'Останні проекти',                // Назва в інтерфейсі
            [
                'description'                 => 'Виводить останні проекти з фільтром за категорією',
                'customize_selective_refresh' => true,
            ]
        );
    }

    // Фронтенд: що бачать відвідувачі
    public function widget(array $args, array $instance): void {
        $count    = absint($instance['count'] ?? 3);
        $category = sanitize_title($instance['category'] ?? '');

        echo $args['before_widget'];

        if (!empty($instance['title'])) {
            echo $args['before_title'] . apply_filters('widget_title', esc_html($instance['title'])) . $args['after_title'];
        }

        $query_args = [
            'post_type'      => 'project',
            'posts_per_page' => $count,
            'post_status'    => 'publish',
        ];

        if ($category) {
            $query_args['tax_query'] = [[
                'taxonomy' => 'project_category',
                'field'    => 'slug',
                'terms'    => $category,
            ]];
        }

        $projects = new WP_Query($query_args);

        if ($projects->have_posts()) {
            echo '<ul class="projects-widget">';
            while ($projects->have_posts()) {
                $projects->the_post();
                printf(
                    '<li><a href="%s">%s</a></li>',
                    esc_url(get_permalink()),
                    esc_html(get_the_title())
                );
            }
            wp_reset_postdata();
            echo '</ul>';
        }

        echo $args['after_widget'];
    }

    // Форма налаштувань у /wp-admin
    public function form(array $instance): void {
        $title    = esc_attr($instance['title'] ?? 'Проекти');
        $count    = absint($instance['count'] ?? 3);
        $category = esc_attr($instance['category'] ?? '');

        printf(
            '<p><label for="%1$s">Заголовок:</label>
             <input class="widefat" id="%1$s" name="%2$s" type="text" value="%3$s"></p>',
            $this->get_field_id('title'),
            $this->get_field_name('title'),
            $title
        );

        printf(
            '<p><label for="%1$s">Кількість:</label>
             <input class="tiny-text" id="%1$s" name="%2$s" type="number" min="1" max="20" value="%3$d"></p>',
            $this->get_field_id('count'),
            $this->get_field_name('count'),
            $count
        );

        // Випадаючий список категорій проектів
        $categories = get_terms(['taxonomy' => 'project_category', 'hide_empty' => false]);
        echo '<p><label for="' . $this->get_field_id('category') . '">Категорія:</label>';
        echo '<select class="widefat" id="' . $this->get_field_id('category') . '" name="' . $this->get_field_name('category') . '">';
        echo '<option value="">Всі</option>';
        foreach ($categories as $cat) {
            printf(
                '<option value="%s"%s>%s</option>',
                esc_attr($cat->slug),
                selected($category, $cat->slug, false),
                esc_html($cat->name)
            );
        }
        echo '</select></p>';
    }

    // Збереження налаштувань
    public function update(array $new_instance, array $old_instance): array {
        return [
            'title'    => sanitize_text_field($new_instance['title']),
            'count'    => absint($new_instance['count']),
            'category' => sanitize_title($new_instance['category']),
        ];
    }
}

Реєстрація віджета

add_action('widgets_init', function () {
    register_widget('My_Projects_Widget');
});

Реєстрація області для віджетів (sidebar)

Якщо тема не має потрібної області, додайте через register_sidebar():

add_action('widgets_init', function () {
    register_sidebar([
        'name'          => 'Сайдбар блога',
        'id'            => 'blog-sidebar',
        'description'   => 'Віджети в сайдбарах сторінок блога',
        'before_widget' => '<section id="%1$s" class="widget %2$s">',
        'after_widget'  => '</section>',
        'before_title'  => '<h3 class="widget-title">',
        'after_title'   => '</h3>',
    ]);
});

before_widget і after_widget — обгортки, які отримує віджет у $args. Тема контролює HTML-структуру, не віджет.

Віджет з AJAX-оновленням

Для віджетів, які мають оновлюватися без перезавантаження (лічильник або живий пошук):

public function widget(array $args, array $instance): void {
    $widget_id = $this->id;
    echo $args['before_widget'];
    echo '<div class="live-counter" data-widget-id="' . esc_attr($widget_id) . '">';
    echo $this->render_counter(); // початковий рендер
    echo '</div>';
    echo $args['after_widget'];
}

document.querySelectorAll('.live-counter').forEach(el => {
  setInterval(() => {
    fetch(wpData.ajaxUrl + '?action=refresh_counter&widget=' + el.dataset.widgetId)
      .then(r => r.json())
      .then(data => { el.innerHTML = data.html; });
  }, 30000);
});

Віджети в блочному редакторі

WordPress 5.8+ дозволяє керувати віджетами через блочний інтерфейс. Класичні екземпляри WP_Widget з'являються як "Legacy Widgets". Для повноцінної підтримки редактора Gutenberg для віджетів потрібно зареєструвати блок, який використовує одні й ті ж дані — це окрема задача (див. послугу "Розробка користувацьких блоків Gutenberg").

Якщо сайт використовує Classic Widgets (плагін), описаний підхід працює без обмежень.