add_submenu_page

Добавляет дочернюю страницу (подраздел) указанного главного меню в админ-панели.

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

Нужно вызывать через один из хуков:
user_admin_menu — админ-меню пользователя;
network_admin_menu — админ-меню сети;
admin_menu — обычное административное меню.

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

Если у вас появляется ошибка “You do not have sufficient permissions to access this page.” при попытке зайти на страницу, это значит, что вы подключаете функцию слишком рано, вешаете функцию не на тот хук. Нужно использовать хук admin_menu.

Хуков нет.

Возвращает

Строку. Название хука, результирующей страницы меню или false, если пользователь не имеет прав доступа к меню.

Использование

add_submenu_page( $parent_slug, $page_title, $menu_title, $capability, $menu_slug, $function );
$parent_slug(строка) (обязательный)

Название (slug) родительского меню в которое будет добавлен пункт или название файла админ-страницы WordPress. Используйте NULL или укажите “options.php”, чтобы создать страницу, которая не будет появляться ни в каком пункте меню.
Примеры:

  • index.php – Консоль (Dashboard). Или спец. функция: add_dashboard_page();

  • edit.php – Посты (Posts). Или спец. функция: add_posts_page();

  • upload.php – Медиафайлы (Media). Или спец. функция: add_media_page();

  • link-manager.php – Ссылки (Links). Или спец. функция: add_links_page();

  • edit.php?post_type=page – Страницы (Pages). Или спец. функция: add_pages_page();

  • edit-comments.php – Комментарии (Comments). Или спец. функция: add_comments_page();

  • edit.php?post_type=your_post_type – Произвольные типы записей.

  • themes.php – Внешний вид (Appearance). Или спец. функция: add_theme_page();

  • plugins.php – Плагины (Plugins). Или спец. функция: add_plugins_page();

  • users.php – Пользователи (Users). Или спец. функция: add_users_page();

  • tools.php – Инструменты (Tools). Или спец. функция: add_management_page();

  • options-general.php – Настройки (Settings). Или спец. функция: add_options_page()
    По умолчанию: нет
$page_title(строка) (обязательный)
Текст, который будет использован в теге title на странице.
По умолчанию: нет
$menu_title(строка) (обязательный)
Текст, который будет использован как называние пункта меню.
По умолчанию: нет
$capability(строка) (обязательный)
Возможность пользователя, чтобы иметь доступ к меню. Таблицу возможностей смотрите здесь. Этот параметр отвечает и за доступ к странице этого пункта меню.
По умолчанию: нет
$menu_slug(строка) (обязательный)

Уникальное название (slug), по которому затем можно обращаться к этому меню. Если нужно дублировать родительское меню, укажите $menu_slug такой же как у родительского меню.

Это название будет использоваться в качестве значение параметра запроса page в ссылке на страницу: ?page=название. Это уникальное название будет как бы привязано к функции указанной в следующем параметре $function.

По неофициальной информации, в этот параметр можно добавить путь до файла отвечающего за страницу этого пункта меню. Путь должен быть от каталога плагинов: допустим папка плагина называетсяmy-plugin и файл страницы настроек  options.php, тогда путь до файла будет такой: my-plugin/options.php.

По умолчанию: нет

$function(строка/массив)

Название функции которая будет вызваться, чтобы вывести контент создаваемой страницы.
Два варианта установки параметра:

  1. Если функция является методом класса, она вызывается по ссылке: array( $this, ‘function_name’ ) или статически: array( __CLASS__, ‘function_name’ ).

  2. Во всех остальных случаях указываем название функции в виде строки.
    По умолчанию: нет

Примеры

#1 Добавим подменю в меню админ-панели “Инструменты” (tools):

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() {
	// контент страницы
	echo '<div class="wrap">';
		echo '<h2>Моя страница подменю</h2>';
	echo '</div>';

}

#2 Прячем страницу из меню, но она все равно будет рабочей

Чтобы спрятать ссылку пункта подменю из основного меню админ-панели, используйте первый параметр null или ‘options.php’:

add_action('admin_menu', 'register_my_custom_submenu_page');

function register_my_custom_submenu_page() {
	add_submenu_page( 
			  null   //or 'options.php' 
			, 'Произвольная страница подменю' 
			, 'Произвольная страница подменю'
			, 'manage_options'
			, 'my-custom-submenu-page'
			, 'my_custom_submenu_page_callback'
	);
}

#3 Подменю для произвольно-созданного меню

Если вы пытаетесь добавить пункт меню в основной раздел, который вы создали самостоятельно с помощью add_menu_page(), то первый пункт будет копией созданного пункта add_menu_page(). Это видно во всем меню WordPress.

Если вам нужен пункт подменю по такому сценарию, то для начала вам нужно создать дубль основного меню, а затем добавить подменю:

<?php
function add_submenu_page( $parent_slug, $page_title, $menu_title, $capability, $menu_slug, $function = '' ) {
	global $submenu, $menu, $_wp_real_parent_file, $_wp_submenu_nopriv,
		$_registered_pages, $_parent_pages;

	$menu_slug = plugin_basename( $menu_slug );
	$parent_slug = plugin_basename( $parent_slug);

	if ( isset( $_wp_real_parent_file[$parent_slug] ) )
		$parent_slug = $_wp_real_parent_file[$parent_slug];

	if ( !current_user_can( $capability ) ) {
		$_wp_submenu_nopriv[$parent_slug][$menu_slug] = true;
		return false;
	}

	/*
	 * If the parent doesn't already have a submenu, add a link to the parent
	 * as the first item in the submenu. If the submenu file is the same as the
	 * parent file someone is trying to link back to the parent manually. In
	 * this case, don't automatically add a link back to avoid duplication.
	 */
	if (!isset( $submenu[$parent_slug] ) && $menu_slug != $parent_slug ) {
		foreach ( (array)$menu as $parent_menu ) {
			if ( $parent_menu[2] == $parent_slug && current_user_can( $parent_menu[1] ) )
				$submenu[$parent_slug][] = array_slice( $parent_menu, 0, 4 );
		}
	}

	$submenu[$parent_slug][] = array ( $menu_title, $capability, $menu_slug, $page_title );

	$hookname = get_plugin_page_hookname( $menu_slug, $parent_slug);
	if (!empty ( $function ) && !empty ( $hookname ))
		add_action( $hookname, $function );

	$_registered_pages[$hookname] = true;

	/*
	 * Backward-compatibility for plugins using add_management page.
	 * See wp-admin/admin.php for redirect from edit.php to tools.php
	 */
	if ( 'tools.php' == $parent_slug )
		$_registered_pages[get_plugin_page_hookname( $menu_slug, 'edit.php')] = true;

	// No parent as top level.
	$_parent_pages[$menu_slug] = $parent_slug;

	return $hookname;
}