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

Функция add_menu_page() в WordPress позволяет добавлять новые пункты верхнего уровня в меню админ-панели. Эти пункты могут быть использованы для создания главных страниц управления или настроек для плагинов и тем. Каждый созданный пункт меню отображается в одном ряду с другими стандартными пунктами, такими как «Записи», «Страницы», «Пользователи» и т.д.

add_menu_page(
    string $page_title,
    string $menu_title,
    string $capability,
    string $menu_slug,
    callable $function = '',
    string $icon_url = '',
    int $position = 0
);

Параметры

• $page_title (string) — Название страницы, отображаемое в заголовке браузера. Этот текст будет использоваться в теге <title> на странице, относящейся к пункту меню.
• $menu_title (string) — Название пункта меню, которое отображается в боковой панели админ-панели. Это название будет видно пользователям.
• $capability (string) — Способности пользователя, которые необходимы для доступа к этому пункту меню. Например, manage_options позволяет доступ только администраторам.
• $menu_slug (string) — Уникальный идентификатор (slug) для пункта меню, который также используется в URL для доступа к странице.
• $function (callable) — Функция, которая будет выводить содержимое страницы меню. Если этот параметр не указан, WordPress будет ожидать, что текущий PHP файл генерирует код страницы админ-меню без вызова функции.
• $icon_url (string) — URL иконки, которая будет отображаться рядом с пунктом меню. Можно использовать как URL изображения, так и стандартные иконки Dashicons. Поддерживаются также SVG и base64-кодированные иконки.
• $position (int) — Позиция пункта меню в списке. Меньшее число означает более высокое положение в меню.

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

В этом примере создается пользовательский пункт меню, который будет отображать страницу с заголовком «Мои настройки».

<?php
// Функция для отображения содержимого страницы настроек
function my_custom_settings_page() {
    ?>
    <div class="wrap">
        <h1>Мои настройки</h1>
        <p>Добро пожаловать на страницу настроек вашего плагина.</p>
    </div>
    <?php
}

// Функция для добавления пункта меню
function my_custom_menu() {
    add_menu_page(
        'Мои настройки',        // Заголовок страницы
        'Мои настройки',        // Название меню
        'manage_options',       // Способности пользователя
        'my-custom-settings',  // Уникальный идентификатор
        'my_custom_settings_page', // Функция для отображения содержимого
        'dashicons-admin-generic', // Иконка меню
        20                      // Позиция меню
    );
}

// Хук для добавления меню при инициализации
add_action('admin_menu', 'my_custom_menu');

Пояснения и замечания

1. Параметр $function — Это функция, которая выводит контент страницы. Если вы используете метод класса, укажите его как массив с двумя элементами: [ $this, 'method_name' ] для нестатического метода или [ __CLASS__, 'method_name' ] для статического метода. Для обычных функций укажите их имя в виде строки.
2. Хуки для добавления меню:
   • admin_menu — Используется для добавления пунктов меню в стандартную админ-панель WordPress.
   • network_admin_menu — Используется для добавления пунктов меню в мультисайт админ-панель.
3. Добавление дочерних пунктов меню:
   • Для создания дочерних пунктов меню используйте функцию add_submenu_page(). Это позволяет создавать иерархию страниц в админ-панели.
4. Ошибка прав доступа:
   • Если при попытке доступа к странице вы видите сообщение «You do not have sufficient permissions to access this page.», это может означать, что функция была подключена слишком рано. Убедитесь, что функция добавляется в хук admin_menu, чтобы избежать проблем с правами доступа.
5. Изменение прав доступа:
   • Если вам нужно предоставить доступ к странице для пользователей с правами ниже администратора, используйте хук option_page_capability_{$menu_slug}, где $menu_slug — это уникальный идентификатор меню. Например, для предоставления права редактирования другим ролям, используйте фильтр:

add_action( 'admin_menu', 'register_my_page' );
add_filter( 'option_page_capability_'.'my_page_slug', 'my_page_capability' );

function register_my_page(){
    add_menu_page( 'My Page Title', 'My Page', 'edit_others_posts', 'my_page_slug', 'my_page_function', plugins_url( 'myplugin/images/icon.png' ), 6 );
}

function my_page_capability( $capability ) {
    return 'edit_others_posts';
}

6. Параметр $icon_url:
   • Вы можете указать произвольную иконку для пункта меню, используя URL изображения или одну из стандартных иконок Dashicons. Иконка также может быть предоставлена в формате base64 или просто указана как none для применения кастомных стилей через CSS.
7. Параметр $position:
   • Определяет порядок расположения пункта меню в списке. Избегайте использования одинаковых значений для нескольких пунктов меню, так как это может привести к перезаписи. Используйте дробные значения для предотвращения конфликтов.

Заключение

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