Функция wp_register_widget_control() в WordPress

Функция wp_register_widget_control() используется для регистрации функции, которая отвечает за вывод настроек виджета в административной панели WordPress. Эта функция позволяет разработчикам создавать настраиваемые виджеты с интерфейсом для управления их параметрами.

wp_register_widget_control( int|string $id, string $name, callable $control_callback, array $options = array(), mixed $params = null );

Параметры

• $id (int|string, обязательный): Уникальный идентификатор виджета, который совпадает с ID, указанным при регистрации виджета с помощью wp_register_sidebar_widget().
• $name (string, обязательный): Отображаемое название виджета в боковой панели админ-панели.
• $control_callback (callable, обязательный): Функция обратного вызова, которая будет вызываться для отображения настроек виджета.
• $options (array, необязательный): Массив опций управления. Может включать параметры height, width и id_base.
  • height: Этот параметр не используется и по умолчанию равен 200.
  • width: Ширина полностью развернутой формы управления виджетом. По умолчанию равна 250.
  • id_base: Уникальный идентификатор для многоразовых виджетов (например, виджетов, позволяющих несколько экземпляров, таких как текстовый виджет).
• $params (mixed, необязательный): Дополнительные параметры, которые передаются в функцию обратного вызова при её вызове.

Возвращаемое значение

• null: Функция не возвращает значений.

Пример 1: Регистрация настроек виджета

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

// Регистрация виджета
function my_custom_widget() {
    // Код для отображения виджета
    echo '<div>' . esc_html(get_option('my_widget_title')) . '</div>';
}

wp_register_sidebar_widget(
    'my_custom_widget',      // ID виджета
    'Мой пользовательский виджет', // Заголовок виджета
    'my_custom_widget'       // Функция для вывода содержимого виджета
);

Теперь добавим код для регистрации настроек виджета с помощью wp_register_widget_control():

<?php
// Регистрация настроек виджета
wp_register_widget_control(
    'my_custom_widget',      // ID
    'Настройки виджета',     // Название
    'my_custom_widget_control', // Функция обратного вызова для настроек
    array('width' => 400)    // Ширина блока настроек
);

// Функция для управления настройками виджета
function my_custom_widget_control() {
    // Сохраняем данные, если отправлены
    if (isset($_POST['submitted'])) {
        update_option('my_widget_title', sanitize_text_field($_POST['widget_title']));
    }

    // Загружаем текущие опции
    $widget_title = get_option('my_widget_title', 'По умолчанию');

    // HTML для формы настроек
    ?>
    <p>
        <label for="widget_title">Заголовок виджета:</label><br />
        <input type="text" class="widefat" name="widget_title" value="<?php echo esc_attr($widget_title); ?>" />
    </p>
    <input type="hidden" name="submitted" value="1" />
    <?php
}

Пример 2: Многоразовый виджет

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

<?php
// Регистрация многоразового виджета
function my_multi_widget() {
    // Код для вывода виджета
    echo '<div>' . esc_html(get_option('widget_title_' . $params['id'])) . '</div>';
}

wp_register_sidebar_widget(
    'my_multi_widget',      // ID виджета
    'Мой многоразовый виджет', // Заголовок виджета
    'my_multi_widget'       // Функция для вывода содержимого виджета
);

// Регистрация настроек виджета
wp_register_widget_control(
    'my_multi_widget',      // ID
    'Настройки многоразового виджета', // Название
    'my_multi_widget_control', // Функция для настроек
    array('width' => 400)    // Ширина блока настроек
);

// Функция для управления настройками многоразового виджета
function my_multi_widget_control($params) {
    // Сохраняем данные, если отправлены
    if (isset($_POST['submitted'])) {
        update_option('widget_title_' . $params['id'], sanitize_text_field($_POST['widget_title']));
    }

    // Загружаем текущие опции
    $widget_title = get_option('widget_title_' . $params['id'], 'По умолчанию');

    // HTML для формы настроек
    ?>
    <p>
        <label for="widget_title">Заголовок виджета:</label><br />
        <input type="text" class="widefat" name="widget_title" value="<?php echo esc_attr($widget_title); ?>" />
    </p>
    <input type="hidden" name="submitted" value="1" />
    <?php
}

Пример 3: Регистрация нескольких виджетов

Вы также можете зарегистрировать несколько виджетов с помощью циклов. Например, если у вас есть массив настроек для нескольких виджетов:

$widgets = array(
    array('id' => 'widget_one', 'name' => 'Первый виджет'),
    array('id' => 'widget_two', 'name' => 'Второй виджет')
);

foreach ($widgets as $widget) {
    // Регистрация виджета
    wp_register_sidebar_widget(
        $widget['id'], 
        $widget['name'], 
        'my_custom_widget'
    );

    // Регистрация управления виджетом
    wp_register_widget_control(
        $widget['id'], 
        'Настройки ' . $widget['name'], 
        'my_custom_widget_control',
        array('width' => 400)
    );
}

Заключение

Функция wp_register_widget_control() предоставляет разработчикам гибкость в создании виджетов с настраиваемыми параметрами в административной панели WordPress. С её помощью можно создать пользовательский интерфейс для управления параметрами виджета, что делает вашу тему или плагин более удобными для пользователей.