6.1 Меню верхнего уровня

Для добавления нового меню верхнего уровня в WordPress Administration используйте функцию add_menu_page().

<?php
add_menu_page(
string $page_title,
string $menu_title,
string $capability,
string $menu_slug,
callable $function = '',
string $icon_url = '',
int $position = null
);

Пример

Допустим, мы хотим добавить новое меню верхнего уровня под названием «WPOrg».

Первым шагом будет создание функции, которая будет выводить HTML. В этой функции мы выполним необходимые проверки безопасности и отобразим зарегистрированные нами опции с помощью Settings API (Настройки API).

Мы рекомендуем обернуть ваш HTML с помощью <div> с классом wrap.
<?php
function wporg_options_page_html() {
?>
<div class="wrap">
<h1><?php echo esc_html( get_admin_page_title() ); ?></h1>
<form action="options.php" method="post">
<?php
// output security fields for the registered setting "wporg_options"
settings_fields( 'wporg_options' );
// output setting sections and their fields
// (sections are registered for "wporg", each field is registered to a specific section)
do_settings_sections( 'wporg' );
// output save settings button
submit_button( __( 'Save Settings', 'textdomain' ) );
?>
</form>
</div>
<?php
}
?>

Вторым шагом будет регистрация нашего меню WPOrg. Регистрация должна произойти во время перехвата ([erf) действия admin_menu.

<?php
add_action( 'admin_menu', 'wporg_options_page' );
function wporg_options_page() {
add_menu_page(
'WPOrg',
'WPOrg Options',
'manage_options',
'wporg',
'wporg_options_page_html',
plugin_dir_url(__FILE__) . 'images/icon_wporg.png',
20
);
}
?>

Список параметров и то, что каждый из них делает, смотрите в справке add_menu_page().

Использование PHP-файла для HTML

Лучшей практикой для переносимого кода было бы создание функции обратного вызова (Callback), которая требует/включает в себя ваш PHP-файл.

Для полноты и облегчения понимания унаследованного кода мы покажем другой способ: передача пути к PHP-файлу в виде параметра $menu_slug с параметром null $function.

<?php
add_action( 'admin_menu', 'wporg_options_page' );
function wporg_options_page() {
add_menu_page(
'WPOrg',
'WPOrg Options',
'manage_options',
plugin_dir_path(__FILE__) . 'admin/view.php',
null,
plugin_dir_url(__FILE__) . 'images/icon_wporg.png',
20
);
}
?>

Удаление меню верхнего уровня

Чтобы удалить зарегистрированное меню из администрирования WordPress, используйте функцию remove_menu_page().

<?php
remove_menu_page(
string $menu_slug
);
?>

Удаление меню не помешает пользователям получить к ним прямой доступ. Это никогда не должно использоваться как способ ограничить возможности пользователей.

Пример

Допустим, мы хотим убрать меню «Инструменты» (Tools).

<?php
add_action( 'admin_menu', 'wporg_remove_options_page', 99 );
function wporg_remove_options_page() {
remove_menu_page( 'tools.php' );
}
?>

Убедитесь, что меню было зарегистрировано с помощью хука admin_menu, прежде чем пытаться удалить, укажите номер с более высоким приоритетом для функции add_action().

Отправка форм

Чтобы обработать отправку форм на страницах параметров, вам понадобятся две вещи:

  1. Используйте URL-адрес страницы в качестве атрибута действия формы.
  2. Добавьте хук со слагом (slug), возвращаемый add_menu_page.

Вам нужно следовать этим шагам только в том случае, если вы вручную создаете формы в бэкэнде. Рекомендуется использовать API Settings.

Атрибут действия формы

Используйте параметр $menu_slug страницы параметров в качестве первого параметра menu_page_url(). Функция автоматически экранирует URL и выводит его по умолчанию, поэтому вы можете напрямую использовать его в теге <form>:

<form action="<?php menu_page_url( 'wporg' ) ?>" method="post">

Обработка формы

$function, указанная вами при добавлении страницы, будет вызываться только тогда, когда пришло время отобразить страницу, что делает ее неуместной, если вам нужно отправить заголовки (например, перенаправления) обратно в браузер.

add_menu_page возвращает $hookname, а WordPress запускает действие «load-$hookname» перед любым выводом HTML. Вы можете использовать это, чтобы назначить функцию, которая может обрабатывать форму.

«load-$hookname» будет выполняться каждый раз перед отображением страницы параметров, даже если форма не отправляется.

Учитывая возвращаемый параметр и действие, приведенный выше пример будет выглядеть так:

add_action( 'admin_menu', 'wporg_options_page' );
function wporg_options_page() {
$hookname = add_menu_page(
'WPOrg',
'WPOrg Options',
'manage_options',
'wporg',
'wporg_options_page_html',
plugin_dir_url(__FILE__) . 'images/icon_wporg.png',
20
);

add_action( 'load-' . $hookname, 'wporg_options_page_submit' );
}

Вы можете запрограммировать wporg_options_page_submit в соответствии с вашими потребностями, но имейте в виду, что вы должны вручную выполнить все необходимые проверки, включая:

  1. Отправляется ли форма ('POST' === $_SERVER['REQUEST_METHOD']).
  2. Проверка CSRF
  3. Валидация (Validation)
  4. Очистка (Sanitization)

Была ли эта страница полезной?