Полное руководство по функции add_meta_box() в WordPress

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

add_meta_box( string $id, string $title, callable $callback, string|array $screen = null, string $context = 'advanced', string $priority = 'default', array $args = null )

Параметры

1. $id (string) (Обязательный)
   • Уникальный идентификатор для мета-бокса. Он должен быть уникальным для каждого мета-бокса на экране редактирования.
2. $title (string) (Обязательный)
   • Заголовок мета-бокса, который будет отображаться в админ-панели.
3. $callback (callable) (Обязательный)
   • Функция обратного вызова, которая будет использоваться для вывода содержимого мета-бокса. Эта функция должна принимать один параметр: объект $post.
4. $screen (string|array) (Необязательный)
   • Экран(ы), на которых будет отображаться мета-бокс. Это может быть строка (например, post, page) или массив экранов (например, array('post', 'page')). Если параметр не указан, мета-бокс будет добавлен ко всем экранам.
5. $context (string) (Необязательный)
   • Контекст, в котором будет отображаться мета-бокс. Возможные значения: normal, side, advanced. По умолчанию advanced.
6. $priority (string) (Необязательный)
   • Приоритет отображения мета-бокса в контексте. Возможные значения: default, high, low. По умолчанию default.
7. $args (array) (Необязательный)
   • Массив дополнительных аргументов, которые могут быть переданы в функцию обратного вызова.

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

Функция add_meta_box() не возвращает значения.

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

Допустим, вы хотите добавить мета-бокс на экран редактирования постов, который позволяет вводить дополнительную информацию. Для этого вы можете использовать следующий пример кода:

Шаг 1: Регистрация мета-бокса

// Функция для добавления мета-бокса
function my_custom_meta_box() {
    add_meta_box(
        'my_meta_box_id',                // ID мета-бокса
        'Мой Метабокс',                  // Заголовок мета-бокса
        'my_meta_box_callback',          // Функция обратного вызова
        'post',                          // Экран, на котором будет отображаться мета-бокс (например, 'post' для постов)
        'side',                          // Контекст (положение на экране редактирования)
        'default'                        // Приоритет
    );
}
add_action('add_meta_boxes', 'my_custom_meta_box');

Шаг 2: Создание функции обратного вызова

// Функция обратного вызова для отображения содержимого мета-бокса
function my_meta_box_callback($post) {
    // Используем nonce для проверки безопасности
    wp_nonce_field('my_meta_box_nonce_action', 'my_meta_box_nonce_field');

    // Получаем текущее значение мета-поля
    $value = get_post_meta($post->ID, '_my_meta_key', true);

    // Выводим HTML для мета-бокса
    echo '<label for="my_meta_field">Мое поле:</label>';
    echo '<input type="text" id="my_meta_field" name="my_meta_field" value="' . esc_attr($value) . '" size="25" />';
}

Шаг 3: Сохранение данных мета-бокса

// Функция для сохранения данных мета-бокса
function save_my_meta_box_data($post_id) {
    // Проверка nonce для безопасности
    if (!isset($_POST['my_meta_box_nonce_field']) || !wp_verify_nonce($_POST['my_meta_box_nonce_field'], 'my_meta_box_nonce_action')) {
        return;
    }

    // Проверка прав пользователя
    if (defined('DOING_AUTOSAVE') && DOING_AUTOSAVE) {
        return;
    }

    if (!current_user_can('edit_post', $post_id)) {
        return;
    }

    // Сохранение или удаление значения мета-поля
    if (isset($_POST['my_meta_field'])) {
        $my_data = sanitize_text_field($_POST['my_meta_field']);
        update_post_meta($post_id, '_my_meta_key', $my_data);
    } else {
        delete_post_meta($post_id, '_my_meta_key');
    }
}
add_action('save_post', 'save_my_meta_box_data');

Дополнительная информация

Глобальный массив $wp_meta_boxes:

Все зарегистрированные метабоксы хранятся в глобальном массиве $wp_meta_boxes, который содержит многомерный массив всех метабоксов, включая их ID, параметры, функции обратного вызова и заголовки для всех типов записей.

Использование wp_add_dashboard_widget():

Чтобы добавить метабокс на страницу админ-панели «Консоль» или «Консоль мультисайта», используйте функцию wp_add_dashboard_widget(). Это позволяет добавить виджеты на страницу дашборда, которые могут содержать статистику, отчеты или другую важную информацию.

Поддержка Gutenberg:

• Если метабокс не совместим с Gutenberg, можно отключить редактор блоков, установив аргумент __block_editor_compatible_meta_box в значение false. Это вернет пользователя к классическому редактору.

add_meta_box('my-meta-box', 'My Meta Box', 'my_meta_box_callback', null, 'normal', 'high', array(
    '__block_editor_compatible_meta_box' => false,
));

• Если метабокс полностью поддерживает Gutenberg, установите аргумент __back_compat_meta_box в значение false, чтобы метабокс не отображался в классическом редакторе, но оставался видимым в Gutenberg.

add_meta_box('my-meta-box', 'My Meta Box', 'my_meta_box_callback', null, 'normal', 'high', array(
    '__back_compat_meta_box' => false,
));

Дополнительные примеры:

Метабокс для постов и страниц

Добавление произвольного блока на страницы редактирования и создания постов и страниц.

add_action('add_meta_boxes', 'myplugin_add_custom_box');
function myplugin_add_custom_box() {
    $screens = array('post', 'page');
    add_meta_box('myplugin_sectionid', 'Название мета блока', 'myplugin_meta_box_callback', $screens);
}

Новая вкладка аккордеона на странице Меню

Пример добавления блока в меню аккордеона на странице настроек меню. Данный тип меню отображается только при использовании классических тем, для блочных тем меню перенесено в Editor.

<?php
add_action('admin_head-nav-menus.php', 'register_my_meta_box_accordion_nav_menus');
function register_my_meta_box_accordion_nav_menus() {
    add_meta_box('my-custom-meta-box', 'Мой метабокс', 'render_my_meta_box_accordion_nav_menus', 'nav-menus', 'side');
}

function render_my_meta_box_accordion_nav_menus() {
    ?>
    <div class="my-custom-meta-box" id="my-custom-meta-box">
        Контент метабокса
    </div>
    <?php
}

Пример реализации на ООП

ООП подход для добавления метабокса.

function call_someClass() {
    new someClass();
}

if (is_admin()) {
    add_action('load-post.php', 'call_someClass');
    add_action('load-post-new.php', 'call_someClass');
}

class someClass {
    public function __construct() {
        add_action('add_meta_boxes', array($this, 'add_meta_box'));
        add_action('save_post', array($this, 'save'));
    }

    public function add_meta_box($post_type) {
        if (in_array($post_type, array('post', 'page'))) {
            add_meta_box(
                'some_meta_box_name',
                __('Some Meta Box Headline', 'myplugin_textdomain'),
                array($this, 'render_meta_box_content'),
                $post_type,
                'advanced',
                'high'
            );
        }
    }

    public function save($post_id) {
        if (!isset($_POST['myplugin_inner_custom_box_nonce'])) return $post_id;
        $nonce = $_POST['myplugin_inner_custom_box_nonce'];
        if (!wp_verify_nonce($nonce, 'myplugin_inner_custom_box')) return $post_id;
        if (defined('DOING_AUTOSAVE') && DOING_AUTOSAVE) return $post_id;
        if ('page' == $_POST['post_type']) {
            if (!current_user_can('edit_page', $post_id)) return $post_id;
        } else {
            if (!current_user_can('edit_post', $post_id)) return $post_id;
        }
        $mydata = sanitize_text_field($_POST['myplugin_new_field']);
        update_post_meta($post_id, '_my_meta_value_key', $mydata);
    }

    public function render_meta_box_content($post) {
        wp_nonce_field('myplugin_inner_custom_box', 'myplugin_inner_custom_box_nonce');
        $value = get_post_meta($post->ID, '_my_meta_value_key', true);
        echo '<label for="myplugin_new_field">';
        echo __('Description for this field', 'myplugin_textdomain');
        echo '</label> ';
        echo '<input type="text" id="myplugin_new_field" name="myplugin_new_field"';
        echo ' value="' . esc_attr($value) . '" size="25" />';
    }
}

Использование параметра $callback_args

Пример использования дополнительных аргументов в функции обратного вызова метабокса.

function add_my_meta_box() {
    $var1 = "this";
    $var2 = "that";
    $callback_args = array('foo' => $var1, 'bar' => $var2);
    add_meta_box('metabox_id', 'Metabox Title', 'my_metabox_callback', 'page', 'normal', 'low', $callback_args);
}

function my_metabox_callback($post, $metabox) {
    echo 'Last Modified: ' . $post->post_modified;
    echo $metabox['args']['foo'];
    echo $metabox['args']['bar'];
    echo get_post_meta($post->ID, 'my_custom_field', true);
}

Советы и рекомендации

• Стилизация и скрипты: Если метабокс требует дополнительных стилей или скриптов, подключайте их через хук admin_enqueue_scripts, чтобы гарантировать правильную загрузку на страницах админ-панели.

add_action('admin_enqueue_scripts', 'enqueue_my_meta_box_scripts');
function enqueue_my_meta_box_scripts() {
    wp_enqueue_style('my_meta_box_style', plugins_url('css/my-meta-box.css', __FILE__));
    wp_enqueue_script('my_meta_box_script', plugins_url('js/my-meta-box.js', __FILE__), array('jquery'), null, true);
}

• Валидация и безопасность: Всегда используйте функции wp_nonce_field() и wp_verify_nonce() для защиты от CSRF атак. Убедитесь, что данные, сохраняемые в метаполях, валидируются и очищаются с помощью sanitize_* функций.

• Совместимость с Gutenberg: Поскольку Gutenberg является основным редактором в последних версиях WordPress, рекомендуется создавать метабоксы, которые поддерживают как классический, так и блоковый редакторы.

Заключение

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