add_submenu_page() │ WP 1.5.0

Adds a child page (subsection) of the specified main menu in the admin panel.

By specifying the minimum user rights, access to the menu can be restricted.

It needs to be called through one of the hooks:

• user_admin_menu — user admin menu.
• network_admin_menu — to add to the multisite menu.
• admin_menu — regular administrative menu.

The function (parameter $function) responsible for displaying content on the page must check user rights separately and block access to the content if necessary.

If you encounter the error "You do not have sufficient permissions to access this page." when trying to access the page, it means that you are hooking the function too early, attaching the function to the wrong hook. You need to use the admin_menu hook.

Do not use __FILE__ for the $menu_slug parameter. This will give you a non-working URL and a security hole.

When writing the code for the function specified in the $function parameter, you may need the parameters specified for add_submenu_page(), such as $page_title. You can get them like this:

• $parent_slug - get_admin_page_parent()
• $page_title - get_admin_page_title() or simply use the global variable $title;
• $menu_slug - global variable $plugin_page

If you need to add a top-level menu item, use add_menu_page().

Also read: Settings (Options) API

Used By: add_options_page(), add_theme_page()

No Hooks.

Returns

String|false. The name of the hook, the resulting menu page, or false if the user does not have access rights to the menu.

Usage

add_submenu_page( $parent_slug, $page_title, $menu_title, $capability, $menu_slug, $callback, $position );

$parent_slug(string) (required)

The name (slug) of the parent menu to which the item will be added or the name of the WordPress admin page file.

Use an empty string options.php to create a page that will not appear in the admin menu. Works for multisite as well.

Examples:

• options.php - hidden page.
• index.php - Dashboard. Or the function add_dashboard_page();
• edit.php - Posts. Or the function add_posts_page();
• upload.php - Media. Or the function add_media_page();
• link-manager.php - Links. Or the function add_links_page();
• edit.php?post_type=page - Pages. Or the function add_pages_page();
• edit-comments.php - Comments. Or the function add_comments_page();
• edit.php?post_type=your_post_type - Custom post types.
• themes.php - Appearance. Or the function add_theme_page();
• plugins.php - Plugins. Or the function add_plugins_page();
• users.php - Users. Or the function add_users_page();
• tools.php - Tools. Or the function add_management_page();
• options-general.php - Settings. Or the function: add_options_page()
• settings.php - Network settings (Settings) in MU mode.

$page_title(string) (required)

The text that will be used in the title tag on the page.

Then, when generating the admin page, this value can be obtained using the function get_admin_page_title().

$menu_title(string) (required)

The text that will be used as the menu item title.

$capability(string) (required)

The capability of the user to access the menu. See the capabilities table here. This parameter also controls access to the page of this menu item.

$menu_slug(string) (required)

A unique name (slug) that can be used to refer to this menu later. If you need to duplicate the parent menu, specify the $menu_slug the same as the parent menu.

This name will be used as the value of the page query parameter in the link to the page: ?page=name. This unique name will be tied to the function specified in the next parameter $function.

According to unofficial information, you can add the path to the file responsible for the page of this menu item to this parameter. The path should be from the plugins directory: suppose the plugin folder is called my-plugin and the settings page file is options.php, then the path to the file would be: my-plugin/options.php.

$function(string/array)

The name of the function that will be called to output the content of the created page.
Two options for setting the parameter:

1. If the function is a method of a class, it is called by reference: array( $this, 'function_name' ) or statically: array( __CLASS__, 'function_name' ).
2. In all other cases, specify the function name as a string.

Default: ''

$position(number)

The position of the submenu item relative to other sub-items. Added in WP 5.3.0.
Default: null

Examples

2

#1 Let's add a submenu to the "Tools" menu of the admin panel:

// Let's add a submenu to the "Tools" menu of the admin panel:
add_action( 'admin_menu', 'register_my_custom_submenu_page' );

function register_my_custom_submenu_page() {

	add_submenu_page(
		'tools.php',
		'Additional Tool Page',
		'Tool Name',
		'manage_options',
		'my-custom-submenu-page',
		'my_custom_submenu_page_callback'
	);
}

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

0

#2 Hide the page from the menu, but it will still be working

To hide a submenu item link from the main admin menu, set null or 'options.php' to the first parameter:

<?php
// Hide the page from the menu, but it will still be working
add_action( 'admin_menu', 'register_my_custom_submenu_page' );

function register_my_custom_submenu_page() {

	add_submenu_page(
		'options.php',
		'Arbitrary submenu page',
		'Arbitrary submenu page',
		'manage_options',
		'my-custom-submenu-page',
		'my_custom_submenu_page_callback'
	);
}

// page content
function my_custom_submenu_page_callback() {
	?>
	<div class="wrap">
		<h2>Hidden Page Title</h2>
	</div>
	<?php
}

Now going to the /wp-admin/tools.php?page=my-custom-submenu-page page, we will see the page, but it will not be visible in the admin menu:

0

#3 Without the function of the settings page (unofficially)

The official documentation does not have this.

In the $menu_slug parameter, you can specify the path to the options page, from the plugins directory. In this case, we do not need to specify the function which is responsible for the code of the options page. For options pages we will have a separate file.

Suppose our settings page file is in the root of the plugin folder and called options.php, then the plugin settings page is registered as follows:

add_action( 'admin_menu', 'add_options_page' );

function add_options_page(){

	add_submenu_page( 
		'options-general.php', 
		'Page title', 
		'Menu item name', 
		'manage_options', 
		basename( __DIR__ ) . '/options.php'
	);
}

Here basename( __DIR__ ) . '/options.php' equals to `plugin_folder_name/options.php'.

0

#4 Checking the presence of a submenu item

See add_menu_page() for examples

0

#5 Using a returned hook-suffix

The function returns a page hook suffix that can be used in the load-(page_hook) hook:

$hookname = add_submenu_page( 
	'options-general.php', 
	$page_title, 
	$menu_title, 
	$capability, 
	$menu_slug, 
	$callback, 
	$position 
);

add_action( "load-{$hookname}", 'my_admin_load' );

function my_admin_load(){
	// do staff
}

-1

#6 A submenu for the custom-created menu

If you try to add a menu item to the main section that you created yourself using add_menu_page(), the first item will be a copy of the created item add_menu_page(). This can be seen throughout the entire WordPress menu.

If you need a submenu item in this scenario, you first need to create a take of the main menu and then add a submenu:

add_action( 'admin_menu', function(){

	add_menu_page( 'Main additional menu', 'My main menu', 'manage_options', 'my-top-level-slug' );

	add_submenu_page( 'my-top-level-slug', 'main additional menu', 'my main menu', 'manage_options', 'my-top-level-slug' );

	add_submenu_page( 'my-top-level-slug', 'my-submenu', 'my-submenu settings page', 'manage_options', 'my-secondary-slug', 'page_callback_function' );

} );

Add Your Own Example

Notes

• Global. Array. $submenu
• Global. Array. $menu
• Global. Array. $_wp_real_parent_file
• Global. true|false. $_wp_submenu_nopriv
• Global. Array. $_registered_pages
• Global. Array. $_parent_pages

Changelog

add_submenu_page() add submenu page code ^{WP 7.0}

function add_submenu_page( $parent_slug, $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
	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 );
			}
		}
	}

	$new_sub_menu = array( $menu_title, $capability, $menu_slug, $page_title );

	if ( null !== $position && ! is_numeric( $position ) ) {
		_doing_it_wrong(
			__FUNCTION__,
			sprintf(
				/* translators: %s: add_submenu_page() */
				__( 'The seventh parameter passed to %s should be numeric representing menu position.' ),
				'<code>add_submenu_page()</code>'
			),
			'5.3.0'
		);
		$position = null;
	}

	if (
		null === $position ||
		( ! isset( $submenu[ $parent_slug ] ) || $position >= count( $submenu[ $parent_slug ] ) )
	) {
		$submenu[ $parent_slug ][] = $new_sub_menu;
	} else {
		// Test for a negative position.
		$position = max( $position, 0 );
		if ( 0 === $position ) {
			// For negative or `0` positions, prepend the submenu.
			array_unshift( $submenu[ $parent_slug ], $new_sub_menu );
		} else {
			$position = absint( $position );
			// Grab all of the items before the insertion point.
			$before_items = array_slice( $submenu[ $parent_slug ], 0, $position, true );
			// Grab all of the items after the insertion point.
			$after_items = array_slice( $submenu[ $parent_slug ], $position, null, true );
			// Add the new item.
			$before_items[] = $new_sub_menu;
			// Merge the items.
			$submenu[ $parent_slug ] = array_merge( $before_items, $after_items );
		}
	}

	// Sort the parent array.
	ksort( $submenu[ $parent_slug ] );

	$hookname = get_plugin_page_hookname( $menu_slug, $parent_slug );
	if ( ! empty( $callback ) && ! empty( $hookname ) ) {
		add_action( $hookname, $callback );
	}

	$_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;
}

Related Functions

Admin menu (admin panel)