Question

add_submenu_page( string $parent_slug,  string $page_title,  string $menu_title,  string $capability,  string $menu_slug,  callable $function = '' )

Add a submenu page.

---

description

This function takes a capability which will be used to determine whether or not a page is included in the menu.

The function which is hooked in to handle the output of the page must check that the user has the required capability as well.

---

参数

$parent_slug

(string) (Required) The slug name for the parent menu (or the file name of a standard WordPress admin page).

$page_title

(string) (Required) The text to be displayed in the title tags of the page when the menu is selected.

$menu_title

(string) (Required) The text to be used for the menu.

$capability

(string) (Required) The capability required for this menu to be displayed to the user.

$menu_slug

(string) (Required) The slug name to refer to this menu by (should be unique for this menu).

$function

(callable) (Optional) The function to be called to output the content for this page.

Default value: ''

---

返回值

(false|string) The resulting page's hook_suffix, or false if the user does not have the capability required.

---

源代码

File: wp-admin/includes/plugin.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;
}

Collapse full 源代码 code View on Trac

---

More Information

Notes

• NOTE:If you’re running into the “You do not have sufficient permissions to access this page.” message in a wp_die() screen, then you’ve hooked too early. The hook you should use is admin_menu.
• For $menu_slug please don’t use __FILE__ it makes for an ugly URL, and is a minor security nuisance.
• Within the rendering function $function you may want to access parameters you used in add_submenu_page(), such as the $page_title. Typically, these will work:
  • $parent_slug: get_admin_page_parent()
  • $page_title: get_admin_page_title(), or simply global $title
  • $menu_slug: global $plugin_page.
• This function should normally be hooked in with one of the the admin_menu actions depending on the menu where the sub menu is to appear:
  

  admin_menu	The normal, or site, administration menu
  user_admin_menu	The user administration menu
  network_admin_menu	The network administration menu

---

相关函数

Uses

• wp-admin/includes/plugin.php: get_plugin_page_hookname()
• wp-includes/capabilities.php: current_user_can()
• wp-includes/plugin.php: plugin_basename()
• wp-includes/plugin.php: add_action()

---

Used By

• wp-admin/includes/plugin.php: add_management_page()
• wp-admin/includes/plugin.php: add_options_page()
• wp-admin/includes/plugin.php: add_theme_page()
• wp-admin/includes/plugin.php: add_plugins_page()
• wp-admin/includes/plugin.php: add_users_page()
• wp-admin/includes/plugin.php: add_dashboard_page()
• wp-admin/includes/plugin.php: add_posts_page()
• wp-admin/includes/plugin.php: add_media_page()
• wp-admin/includes/plugin.php: add_links_page()
• wp-admin/includes/plugin.php: add_pages_page()
• wp-admin/includes/plugin.php: add_comments_page()
• wp-admin/menu.php: _add_themes_utility_last()
• wp-includes/post.php: _add_post_type_submenus()
Show 8 more used by Hide more used by

---

User Contributed Notes

1. Skip to note content You must log in to vote on the helpfulness of this noteVote results for this note: 25You must log in to vote on the helpfulness of this note Contributed by jakeparis

   Slugs for $parent_slug (first parameter)

   Dashboard: ‘index.php’
   Posts: ‘edit.php’
   Media: ‘upload.php’
   Pages: ‘edit.php?post_type=page’
   Comments: ‘edit-comments.php’
   Custom Post Types: ‘edit.php?post_type=your_post_type’
   Appearance: ‘themes.php’
   Plugins: ‘plugins.php’
   Users: ‘users.php’
   Tools: ‘tools.php’
   Settings: ‘options-general.php’
   Network Settings: ‘settings.php’

Inside menu created with add_menu_page()
If you are attempting to add a submenu page to a menu page created via add_menu_page() the first submenu page will be a duplicate of the parent add_menu_page().

If you want a submenu page in this scenario, you should first create a duplicate of your add_menu_page() and then add your add_submenu_page():

add_menu_page('My Custom Page', 'My Custom Page', 'manage_options', 'my-top-level-slug');
add_submenu_page( 'my-top-level-slug', 'My Custom Page', 'My Custom Page',
	'manage_options', 'my-top-level-slug');
add_submenu_page( 'my-top-level-slug', 'My Custom Submenu Page', 'My Custom Submenu Page',
	'manage_options', 'my-secondary-slug');

Example

add_action('admin_menu', 'wpdocs_register_my_custom_submenu_page');

function wpdocs_register_my_custom_submenu_page() {
	add_submenu_page(
		'tools.php',
		'My Custom Submenu Page',
		'My Custom Submenu Page',
		'manage_options',
		'my-custom-submenu-page',
		'wpdocs_my_custom_submenu_page_callback' );
}

function wpdocs_my_custom_submenu_page_callback() {
	echo '<div class="wrap"><div id="icon-tools" class="icon32"></div>';
		echo '<h2>My Custom Submenu Page</h2>';
	echo '</div>';
}

To hide your submenu link from a top level menu item to which it belongs you would instead do

add_action('admin_menu', 'wpdocs_register_my_custom_submenu_page');

function wpdocs_register_my_custom_submenu_page() {
	add_submenu_page( 
		null,   //or 'options.php'
		'My Custom Submenu Page',
		'My Custom Submenu Page',
		'manage_options',
		'my-custom-submenu-page',
		'my_custom_submenu_page_callback',
	);
}

Adding a submenu page to a custom post type
If you want to add a submenu type to a custom post type, such as a reference page for a custom post type created by a plugin, you can use for the $parent_slug parameter whatever you see up top on the “All Posts” view for that post type. For instance, for a custom post type “Book,” the $parent_slug could be 'edit.php?post_type=book'.

Example:

/**
 * Adds a submenu page under a custom post type parent.
 */
function books_register_ref_page() {
    add_submenu_page(
        'edit.php?post_type=book',
        __( 'Books Shortcode Reference', 'textdomain' ),
        __( 'Shortcode Reference', 'textdomain' ),
        'manage_options',
        'books-shortcode-ref',
        'books_ref_page_callback'
    );
}

/**
 * Display callback for the submenu page.
 */
function books_ref_page_callback() { 
    ?>
    <div class="wrap">
        <h1><?php _e( 'Books Shortcode Reference', 'textdomain' ); ?></h1>
        <p><?php _e( 'Helpful stuff here', 'textdomain' ); ?></p>
    </div>
    <?php
}

Example submenu with php class

/**
 * Sub menu class
 *
 * @author Mostafa <mostafa.soufi@hotmail.com>
 */
class Sub_menu {

	/**
	 * Autoload method
	 * @return void
	 */
	public function __construct() {
		add_action( 'admin_menu', array(&$this, 'register_sub_menu') );
	}

	/**
	 * Register submenu
	 * @return void
	 */
	public function register_sub_menu() {
		add_submenu_page( 
			'options-general.php', 'Submenu title', 'Submenu title', 'manage_options', 'submenu-page', array(&$this, 'submenu_page_callback')
		);
	}

	/**
	 * Render submenu
	 * @return void
	 */
	public function submenu_page_callback() {
		echo '<div class="wrap">';
		echo '<h2>Submenu title</h2>';
		echo '</div>';
	}

}

new Sub_menu();

To anyone else troubleshooting an unexpected issue with this function, please PAY ATTENTION to the final argument, specifically the $function, it has to be a STRING, the name of the function, not a call to the function itself. Amateur mistake, I know, but sometimes you just make the simplest of errors.

Bad:

add_menu_page('My Custom Page', 'My Custom Page', 'manage_options', 'my-top-level-slug', my-output-function());

Good:

add_menu_page('My Custom Page', 'My Custom Page', 'manage_options', 'my-top-level-slug', 'my-output-function');

When working with the Classes, You can add_submenu_page by following Make sure the callable is static function.

add_submenu_page( 'admin_menu', 'Custom Menu', 'My Custom Menu', 'manage_options', 'my-custom-menu', __CLASS__ .'::menu_page_output' );

public menu_page_output() {
	//Menu Page output code
}

Parent slugs like ‘tools.php’ can be found in the old doc https://codex.wordpress.org/Function_Reference/add_submenu_page#Parameters