Функция wp_add_dashboard_widget() в WordPress с примерами.

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

wp_add_dashboard_widget(
    $widget_id,
    $widget_name,
    $widget_function,
    $control_function = null,
    $callback_args = null,
    $context = 'normal',
    $priority = 'core'
);

Параметры

• $widget_id (string) (обязательный): Уникальный идентификатор для виджета. Этот идентификатор используется как класс CSS для блока виджета и как ключ в массиве виджетов.
• $widget_name (string) (обязательный): Название виджета, которое будет отображаться в заголовке виджета на панели управления.
• $widget_function (callable) (обязательный): Функция, которая выводит содержимое виджета. Эта функция должна генерировать HTML-код для отображения.
• $control_function (callable) (необязательный): Функция для обработки формы настроек виджета. В этой функции происходит вывод HTML формы настроек и сохранение их значений. Если настройки не требуются, параметр можно установить в null.
• $callback_args (array) (необязательный): Массив аргументов, передаваемых функции отображения виджета. Этот параметр позволяет передавать дополнительные данные в функцию обратного вызова.
• $context (string) (необязательный, начиная с WP 5.6): Контекст экрана, где виджет должен отображаться. Возможные значения: ‘normal’, ‘side’, ‘column3’, ‘column4’. По умолчанию установлено ‘normal’.
• $priority (string) (необязательный, начиная с WP 5.6): Приоритет отображения виджета в указанном контексте. Возможные значения: ‘high’, ‘core’, ‘default’, ‘low’. По умолчанию установлено ‘core’.

Как это работает

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

Хуки для добавления виджетов

Чтобы виджеты работали корректно, их нужно добавлять в соответствующие события:

• wp_dashboard_setup — для добавления виджетов в консоль сайта (блога).
• wp_network_dashboard_setup — для добавления виджетов в консоль сети сайтов в режиме мультисайта.
• wp_user_dashboard_widgets — для добавления виджетов в личные панели пользователей.

Эти хуки используются для регистрации виджетов и должны быть добавлены в функции, которые вызывают wp_add_dashboard_widget().

Пример 1: Добавление виджета в консоль

/ Регистрация виджета для консоли
add_action('wp_dashboard_setup', 'add_custom_dashboard_widget');

function add_custom_dashboard_widget() {
    wp_add_dashboard_widget(
        'custom_dashboard_widget_id', // Уникальный идентификатор виджета
        'Мой Кастомный Виджет', // Название виджета
        'display_custom_dashboard_widget' // Функция для отображения содержимого виджета
    );
}

function display_custom_dashboard_widget() {
    echo '<h3>Привет, мир!</h3>';
    echo '<p>Добро пожаловать в мой кастомный виджет на панели управления!</p>';
}

Пример 2: Добавление виджета в консоль сети сайтов (multisite)

// Регистрация виджета для консоли сети сайтов
add_action('wp_network_dashboard_setup', function() {
    wp_add_dashboard_widget(
        'network_dashboard_widget_id', // Уникальный идентификатор виджета
        'Виджет Сети Сайтов', // Название виджета
        'display_network_dashboard_widget' // Функция для отображения содержимого виджета
    );
});

function display_network_dashboard_widget() {
    echo '<h3>Привет из сети сайтов!</h3>';
    echo '<p>Этот виджет отображается на панели управления сети сайтов.</p>';
}

Пример 3: Изменение расположения виджета

Функция wp_add_dashboard_widget() по умолчанию размещает виджеты в конце первого столбика (слева). Чтобы изменить расположение виджета, можно использовать функцию add_meta_box(), которая предоставляет возможность указать контекст и приоритет размещения виджета.

Для размещения виджета в правом столбце:

add_action('wp_dashboard_setup', function() {
    add_meta_box(
        'custom_meta_box_id', // Уникальный идентификатор метабокса
        'Название Метабокса', // Название метабокса
        'display_custom_meta_box', // Функция для отображения содержимого метабокса
        'dashboard', // Контекст (основная панель)
        'side', // Местоположение (правый столбец)
        'high' // Приоритет отображения
    );
});

function display_custom_meta_box() {
    echo '<p>Этот метабокс размещен в правом столбце.</p>';
}

Для сети сайтов (multisite) в параметре контекста указывайте 'dashboard-network':

add_action('wp_network_dashboard_setup', function() {
    add_meta_box(
        'network_meta_box_id',
        'Название Метабокса Сети Сайтов',
        'display_network_meta_box',
        'dashboard-network',
        'normal',
        'high'
    );
});

function display_network_meta_box() {
    echo '<p>Этот метабокс отображается на панели управления сети сайтов.</p>';
}

Заключение

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