Полный обзор функции add_submenu_page() в WordPress

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

add_submenu_page( 
    string $parent_slug, 
    string $page_title, 
    string $menu_title, 
    string $capability, 
    string $menu_slug, 
    callable $function = '', 
    int $position = null 
);

Параметры

• $parent_slug (string) — Указывает идентификатор родительского меню, к которому добавляется подменю. Примеры включают options-general.php для меню «Настройки» или tools.php для меню «Инструменты». Для скрытых страниц можно использовать пустую строку или options.php.
• $page_title (string) — Текст, который будет отображаться в заголовке страницы при посещении этого подменю.
• $menu_title (string) — Название, отображаемое в списке меню админ-панели.
• $capability (string) — Способность пользователя, необходимая для доступа к этому меню, например manage_options.
• $menu_slug (string) — Уникальный идентификатор для этого подменю. Этот параметр используется в URL-адресе страницы и при регистрации страницы в WordPress.
• $function (callable) — Функция, которая выводит содержимое страницы подменю. Этот параметр опционален.
• $position (int) — Позиция подменю относительно других подпунктов меню. Появился в WP 5.3.0.

Важные замечания

• Хуки для использования: Функцию add_submenu_page() следует вызывать через один из следующих хуков:
  • admin_menu — для обычного административного меню.
  • user_admin_menu — для меню пользовательских админ-панелей.
  • network_admin_menu — для мультисайт админ-панелей.
• Проверка прав доступа: Функция, указанная в параметре $function, должна проверять права доступа пользователя отдельно и блокировать доступ к контенту при необходимости.
• Ошибка прав доступа: Если вы получаете ошибку «You do not have sufficient permissions to access this page,» убедитесь, что функция подключается через хук admin_menu и не используется раньше времени.
• Безопасность: Не используйте __FILE__ для параметра $menu_slug. Это может привести к нерабочим URL и уязвимостям в безопасности.
• Получение параметров: В функции, указанной в параметре $function, вам могут понадобиться параметры, используемые в add_submenu_page(). Их можно получить следующим образом:
  • $parent_slug — через get_admin_page_parent().
  • $page_title — через get_admin_page_title() или глобальную переменную $title.
  • $menu_slug — глобальная переменная $plugin_page.
• Добавление верхнего уровня меню: Для добавления пунктов верхнего уровня используйте функцию add_menu_page().

Пример 1: Добавление подменю к существующему меню

Этот пример добавляет подменю к созданному ранее основному меню плагина:

add_menu_page( 'Основное меню', 'Мое меню', 'manage_options', 'my-top-level-slug' );

add_submenu_page(
    'my-top-level-slug',
    'Подменю',
    'Страница настроек',
    'manage_options',
    'my-secondary-slug',
    'my_secondary_submenu_page_callback'
);

Пример 2: Проверка наличия подменю

Проверьте наличие пункта подменю перед его добавлением:

add_action('admin_menu', 'check_and_add_submenu_page');

function check_and_add_submenu_page() {
    if (!get_plugin_page_hookname('my-top-level-slug', 'my-secondary-slug')) {
        add_submenu_page(
            'my-top-level-slug',
            'Подменю',
            'Страница настроек',
            'manage_options',
            'my-secondary-slug',
            'my_secondary_submenu_page_callback'
        );
    }
}

Пример 3: Добавление подменю в меню «Инструменты»

<?php
add_action('admin_menu', 'register_my_custom_submenu_page');

function register_my_custom_submenu_page() {
    add_submenu_page(
        'tools.php',
        'Дополнительная страница инструментов',
        'Название инструмента',
        'manage_options',
        'my-custom-submenu-page',
        'my_custom_submenu_page_callback'
    );
}

function my_custom_submenu_page_callback() {
    ?>
    <div class="wrap">
        <h2><?php echo get_admin_page_title(); ?></h2>
    </div>
    <?php
}

Пример 4: Скрытая страница

Чтобы скрыть ссылку подменю, используйте параметр options.php:

add_action('admin_menu', 'register_my_hidden_submenu_page');

function register_my_hidden_submenu_page() {
    add_submenu_page(
        'options.php',
        'Скрытая страница',
        'Скрытая страница',
        'manage_options',
        'my-hidden-submenu-page',
        'my_hidden_submenu_page_callback'
    );
}

Пример 5: Использование пути до файла

Для страницы настроек, которая находится в папке плагина:

add_action('admin_menu', 'add_options_page');

function add_options_page() {
    add_submenu_page(
        'options-general.php',
        'Заголовок страницы',
        'Название пункта меню',
        'manage_options',
        basename(dirname(__FILE__)) . '/options.php'
    );
}

Заключение

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