Добавление виджета на панель управления в WordPress: WP_ADD_DASHBOARD_WIDGET()

## Функция WP_ADD_DASHBOARD_WIDGET()

Функция wp_add_dashboard_widget() добавляет новый виджет (метабокс) на панель управления WordPress (основную страницу административной панели).

### Когда использовать эту функцию

Эту функцию следует вызывать во время определенных действий:

- **wp_dashboard_setup** — для добавления виджета на панель управления сайта.
- **wp_network_dashboard_setup** (в мультисайте) — для добавления виджета на панель управления сети сайтов.
- **wp_user_dashboard_widgets** (в мультисайте) — для добавления виджета на панель управления пользователя. Смотрите функцию is_user_admin() для проверки.

Это значит, что WordPress использует следующие события для работы с виджетами, созданными этой функцией:

```php
do_action( 'wp_dashboard_setup' );         // консоль
do_action( 'wp_network_dashboard_setup' ); // консоль сети сайтов
do_action( 'wp_user_dashboard_widgets' );  // консоль пользователя

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

• null — ничего не возвращается.

Использование функции

Вот как выглядит синтаксис функции:

wp_add_dashboard_widget( $widget_id, $widget_name, $callback, $control_callback, $callback_args );

Где параметры:

• $widget_id (string, обязательный) — идентификатор виджета. Используется в CSS-классе HTML-блока виджета, это также ключ виджета в массиве виджетов.
• $widget_name (string, обязательный) — заголовок виджета. Будет отображаться в верхней части виджета, например, "Последние комментарии".
• $callback (callable, обязательный) — функция, которая будет заполнять виджет нужным содержимым. Эта функция должна выводить своё содержимое с помощью echo.
• $control_callback (callable) — функция для сохранения данных виджета: отвечает за обработку формы виджета, а также отображает HTML-форму виджета. По умолчанию: null.
• $callback_args (array) — данные, которые будут переданы в функцию $callback. Таким образом, функция $callback получит объект поста и данные, указанные в этом параметре. По умолчанию: null.

Примеры использования

Пример 1: Добавление виджета на панель управления

// Регистрируем виджет при выполнении действия
add_action( 'wp_dashboard_setup', 'add_dashboard_widgets' );

// Функция для регистрации виджета
function add_dashboard_widgets() {
    wp_add_dashboard_widget( 'my_dashboard_widget', 'Метабокс на панели', 'my_dashboard_widget_function' );
}

// Содержимое виджета
function my_dashboard_widget_function() {
    echo 'Привет, мир! Это мой первый виджет!';
}

Пример 2: Добавление виджета на панель мультисайта

// Добавляем виджет с использованием анонимной функции
add_action( 'wp_network_dashboard_setup', function() {
    wp_add_dashboard_widget( 'my_dashboard_widget', 'Метабокс на панели мультисайта', 'my_dashboard_widget_function' );
} );

function my_dashboard_widget_function() {
    echo 'Привет! Это виджет на панели мультисайта!';
}

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

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

add_meta_box( 'id', 'Заголовок виджета панели', 'dash_widget', 'dashboard', 'side', 'high' );

Для мультисайта четвертым параметром должно быть dashboard-network:

add_meta_box( 'id', 'Заголовок виджета сети', 'widget_output_func', 'dashboard-network', 'normal', 'high' );

Пример 4: Используем параметр $control_callback

С помощью параметра $control_callback мы можем добавить секцию настроек к виджету. В следующем коде мы регистрируем виджет с конфигурацией:

add_action( 'wp_dashboard_setup', 'prefix_add_dashboard_widget' );

function prefix_add_dashboard_widget(){
    wp_add_dashboard_widget(
        'my_dashboard_widget',
        'Особая панель',
        'prefix_dashboard_widget',
        'prefix_dashboard_widget_handle'
    );
}

function prefix_dashboard_widget() {
    // получаем сохраненные данные
    $widget_options = get_option( 'my_dashboard_widget_options', array() );
    $output = '
' . __( 'Пожалуйста, настройте виджет ☝' ) . '
';

    // проверяем, сохранены ли данные
    if (isset($widget_options['feature_post'])) {
        $post = get_post($widget_options['feature_post']);
        if ($post) {
            $content = do_shortcode(html_entity_decode($post->post_content));
            $output = "
{$post->post_title}
{$content}
";
        }
    }

    echo '
'. $output .'
';
}

function prefix_dashboard_widget_handle() {
    $widget_options = get_option( 'my_dashboard_widget_options', array() );

    if ('POST' == $_SERVER['REQUEST_METHOD'] && isset($_POST['my_dashboard_widget_options'])) {
        $widget_options['feature_post'] = absint($_POST['my_dashboard_widget_options']['feature_post']);
        update_option('my_dashboard_widget_options', $widget_options);
    }

    if (!isset($widget_options['feature_post'])) {
        $widget_options['feature_post'] = '';
    }

    $dropdown = wp_dropdown_pages([
        'post_type'        => 'page',
        'selected'         => $widget_options['feature_post'],
        'name'             => 'my_dashboard_widget_options[feature_post]',
        'id'               => 'feature_post',
        'show_option_none' => '- Выберите -',
        'echo'             => 0,
    ]);

    echo '
Доступные страницы
Заголовок'. $dropdown .'
';
}

Пример 5: Виджет для заметок на панели

Вот пример создания виджета для заметок. Он сохраняет содержимое заметок в настройках WordPress с помощью AJAX.

Этот виджет может быть полезен, когда вам нужно быстро записать что-то, чтобы помнить об этом, когда вы находитесь в панели управления.

/**
 * Plugin Name: Ajax WordPress Lessons
 * Description: Отображает виджет с заметками на панели.
 */

// Регистрируем виджет "Мои заметки"
add_action( 'wp_dashboard_setup', 'my_notes_dashboard_widget' );
function my_notes_dashboard_widget() {
    // Регистрируем виджет только для администраторов
    if (current_user_can( 'activate_plugins' )) {
        wp_add_dashboard_widget( 'my_notes', 'Мои заметки', 'my_notes_form' );
    }
}

// Отображаем содержимое виджета
function my_notes_form() {
    ?>
    

        <?php echo esc_textarea(get_option('my_notes_content')); ?>
        Очистить
        
    
     'Заметка сохранена']);
    } else {
        wp_send_json_error(['message' => 'Заметка не сохранена']);
    }
}

// Кастомные стили и JS для сохранения содержимого заметки через AJAX
add_action('admin_print_scripts', 'my_notes_scripts', 999);
function my_notes_scripts() {
    if ('dashboard' != get_current_screen()->base) {
        return;
    }
    ?>
    

    
    

function wp_add_dashboard_widget( $widget_id, $widget_name, $callback, $control_callback = null, $callback_args = null, $context = 'normal', $priority = 'core' ) {
    global $wp_dashboard_control_callbacks;

    $screen = get_current_screen();

    $private_callback_args = array( '__widget_basename' => $widget_name );

    if (is_null($callback_args)) {
        $callback_args = $private_callback_args;
    } elseif (is_array($callback_args)) {
        $callback_args = array_merge($callback_args, $private_callback_args);
    }

    if ($control_callback && is_callable($control_callback) && current_user_can('edit_dashboard')) {
        $wp_dashboard_control_callbacks[$widget_id] = $control_callback;

        if (isset($_GET['edit']) && $widget_id === $_GET['edit']) {
            list($url) = explode('#', add_query_arg('edit', false), 2);
            $widget_name .= ' ' . __('Отмена') . '';
            $callback = '_wp_dashboard_control_callback';
        } else {
            list($url) = explode('#', add_query_arg('edit', $widget_id), 2);
            $widget_name .= ' ' . __('Настроить') . '';
        }
    }

    $side_widgets = array('dashboard_quick_press', 'dashboard_primary');

    if (in_array($widget_id, $side_widgets, true)) {
        $context = 'side';
    }

    $high_priority_widgets = array('dashboard_browser_nag', 'dashboard_php_nag');

    if (in_array($widget_id, $high_priority_widgets, true)) {
        $priority = 'high';
    }

    if (empty($context)) {
        $context = 'normal';
    }

    if (empty($priority)) {
        $priority = 'core';
    }

    add_meta_box($widget_id, $widget_name, $callback, $screen, $context, $priority, $callback_args);
}