The add_menu_page and add_submenu_page functions are used to add menu and submenu items to our WordPress dashboard.

For example, in the screen-shot below, we have added a new Shiba Themes menu. It contains the submenus Shiba Themes, Add New, and Theme Options. Here we consider some common tasks that we may want to perform using add_menu_page and add_submenu_page including -

• Add a new custom post type submenu.
• Add new menus and modify its default submenu name.
• Delete submenus from existing menus.

1. Add a Custom Post Type SubMenu

WordPress Dashboard Menus.

Custom post types was introduced in WordPress 3.0 and it provides us with an easy way to create our own post-like objects.

After we create a custom post type, a new menu will be added to our dashboard allowing us to manage and edit our custom objects.

For example, in the screen-shot to the right we have created a new custom post type called theme, and a new menu (called Shiba Themes) has been added to manipulate these theme objects.

The menu panel starts off with two default submenu pages –

• The Shiba Themes submenu page shows us a list of our theme objects and their attributes. We can search for, delete, copy, and perform other actions on our themes here.
• The Add New submenu page allows us to create new theme objects and edit existing theme objects.

To add a new submenu page to our custom post type menu, we can use the add_submenu_page function.

// Add to admin_menu function
$page = add_submenu_page( 'edit.php?post_type=theme', __('Theme Page Options'), __('Theme Menu Options'), 'edit_themes', 'theme_options', theme_options);
 
function theme_options() {
        // Render our theme options page here ...
}

Custom Post Type SubMenu.

The add_submenu_page function accepts 6 arguments -

1. Menu ID – Defines the unique id of the menu that we want to link our submenu to. To link our submenu to a custom post type page we must specify -

edit.php?post_type=my_post_type

2. Page title – Title of the page or screen that the submenu links to. If you are rendering your own page, then the page title value is stored in the global $title.
3. Menu title – Title of the submenu.
4. Capability – Defines what permissions a user must have in order to access this submenu. Here are a list of capabilities.
5. Submenu ID – Unique id of the submenu.
6. Submenu display function – Function containing HTML and PHP code on how to display the page or screen that the submenu is linked to. In the example above, our theme_options function contains HTML code to render the different drop-down menus appearing in our Theme Page Options page.

Note – The menu id can be either a file name as with the example above or it can be a unique menu id (defined in add_menu page). If it is a file name, it can only be a file name from one of the native WordPress menus.

As such it MUST be a file in the WordPress wp-admin menu and CANNOT be one of your own files.

To specify our own submenu rendering function we must pass it through as the last argument of our add_submenu_page function call.

2. Add New Menus and SubMenus

In the example above, a dashboard menu was automatically added for us as part of our custom post type. If we want to manually add our own menu, then we must use the add_menu_page function.

// Add to admin_menu function
add_menu_page(__('My Menu Page'), __('My Menu'), 'edit_themes', 'my_new_menu', 'my_menu_render', '', 7); 
 
function my_menu_render() {
	global $title;
	?>
        <h2><?php echo $title;?></h2>
        My New Menu Page!!
        <?php
}

Add a new menu page with add_menu_page.

The add_menu_page function accepts 7 arguments -

1. Page title – Title of the page or screen that the menu links to. If you are rendering your own page, then the page title value is stored in the global $title.
2. Menu title – Title of the menu.
3. Capability – Defines what permissions a user must have in order to access this menu. Here are a list of capabilities.
4. Menu ID – Unique id of the menu.
5. Menu display function – Function containing HTML and PHP code on how to display the page or screen that the menu is linked to.
6. Menu icon – (optional) URL of the icon to use for this menu. Here is a tutorial on how to flexibly customize your menu icons.
7. Menu position – (optional) If left unspecified, new menu will appear at the bottom. Otherwise, standard WordPress menus are specified in positions of 5s. For example Dashboard = 0, Post = 5, Media = 10, and so on. Since we want our menu to appear after post, we set its position to 7. If we set it to 5 it will replace the Post menu.

Notice though, that when we add a new sub-menu to our menu area, the first sub-menu that appears is actually our menu page. Furthermore, the name of that first sub-menu is exactly the name of our menu (e.g. My Menu).

// Add to admin_menu
add_submenu_page('my_new_menu', __('My SubMenu Page'), __('My SubMenu'), 'edit_themes', 'my_new_submenu', 'my_submenu_render');

First sub-menu is actually our menu page.

The first sub-menu entry automatically gets added by the WordPress system. If we want to customize the name of our first sub-menu, we must specify our own replacement sub-menu.

add_submenu_page('my_new_menu', __('Manage Menu Page'), __('Manage New Menu'), 'edit_themes', 'my_new_menu', 'my_menu_render');

Note – Argument 5 must contain our menu ID (my_new_menu) rather than a new sub-menu id. In addition, it must be the FIRST sub-menu added.

As we can see below, we have changed the menu name and page name of our first sub-menu.

Customize the first sub-menu name.

Unfortunately, this technique does not work on custom post type menus. To change the first sub-menu name in our custom post type menu we must do the following -

1
2
3
4
5

// Add to end of admin_menu action function
global $submenu;
$submenu['edit.php?post_type=theme'][5][0] = __('Manage Themes');
$post_type_object = get_post_type_object('theme');
$post_type_object->labels->name = "Manage Shiba Themes";

Lines 1-2 – Change the first sub-menu name. For example, we have changed our Shiba Themes first sub-menu to show the name Manage Themes instead of Shiba Themes.

Lines 3-4 -Change the first sub-menu page name. For example, we have changed our Shiba Themes first sub-menu page to show the title Manage Shiba Themes instead of Shiba Themes.

Modify Custom Post Type First Sub-Menu.

3. Delete an Existing Sub-Menu

Finally, we may want to remove certain sub-menu elements. This may occur when we want to add a page but do not want it to be directly accessible from the main dashboard.

The function below allows us to remove a sub-menu based its unique menu-id and the unique submenu-id.

function remove_submenu($menu_name, $submenu_name) {
	global $submenu;
	$menu = $submenu[$menu_name];
	if (!is_array($menu)) return;
	foreach ($menu as $submenu_key => $submenu_object) {
		if (in_array($submenu_name, $submenu_object)) {// remove menu object
			unset($submenu[$menu_name][$submenu_key]);
			return;
		}
	}			
}

For example we could do -

// Add to end of admin_menu function		
remove_submenu('edit.php?post_type=theme', 'theme_options');

Related Articles

<< Previous Next >>

Modify Custom Post Type Icons

After we create a custom post type, we get a new menu item on our dashboard with the default post icon. We also get that same default icon when we go into the Edit and Add New screens of our new custom post type. Here, we consider how to set our custom post type icons to our own image, or to another existing WordPress icon. 1. Register Post Type The easiest way to define our own menu icon is to specify it within our register_post_type function call, while we are creating our new custom post type....

<< Previous Next >>

Obscure WordPress Errors - Why? Where? and How?

WordPress Error 1 You do not have sufficient permissions to access this page. This error is activated within the file wp-admin/menu.php which in turn gets included by wp-admin/admin.php which gets called by almost every WordPress administration page. Here is a code snippet from wp-admin/menu.php where the error message is reported - As you can see from the code snippet above, a good way to debug this error is by hooking into the admin_page_access_denied action in your plugin or your theme...

<< Previous Next >>

Add Custom Post Type Columns

One of the exciting new features in WordPress 3.0 is custom post types. We can create our own post types by using the register_post_type function. If we enable UIs for our custom post type, we will get additional menu items on our WordPress dashboard similar to the Edit and Add New options for standard posts. Here, we consider how to add new columns to the Edit custom post type screen. 1. Create a Custom Post Type Creating a custom post type is surprisingly straight-forward and well documented...

<Playback Stop Play >

Modify Custom Post Type Icons

Obscure WordPress Errors - Why? Where? and How?

Add Custom Post Type Columns