Adding Main Menu and Submenu Items to WordPress Admin

This tutorial expands on a previous tutorial I wrote about Adding a Custom WordPress Admin Page and Menu Item. In this tutorial however, I will show you how to add both a main manu item and a submenu item because there is a trick to it that is very difficult to figure out just from reading the WordPress codex. That's why I figured I'd write this quick tutorial to help others.

Here's an image of a client of mine's WordPress admin where I added both a top level menu to the WordPress admin and a submenu item under it or beside it on hover:

menu example

The image above has the area we are working on with a red border added around it to make it easy to see for this tutorial.

Adding Your Action

First, you have to add an action to your functions.php file. I did this wrong the first time because I tried to add one action for the main menu item and another for the sub menu item. It turns out that is incorrect. You need to add both your main menu item and sub menu item in a single action. Your action and call back function should something look like:

add_action( 'admin_menu', 'addAdminMenu' );

function addAdminMenu(){
add_menu_page('GEE Admin Settings', 'GEE Admin', 'manage_options', 'gee_admin_settings_page', 'admin_pg_function', '', 3);
add_submenu_page('gee_admin_settings_page','User Role Editor', 'Edit User Roles','manage_options', 'user_role_editor_slug', 'edit_user_roles_function');
}

addAdminMenu Function Explained

In the above function we call both the add_menu_page and add_submenu_page functions. First lets look at the seven parameters for the add_menu_page function:

  1. 'Gee Admin Settings' - This is what shows up in the page tab of the browser. It is the title attribute for the admin page you are creating.
  2. 'GEE Admin' - This is what shows up in the left nav of the wp-admin page as the main menu item's text. You can see this in the image provided above outlined in red.
  3. 'manage_options' - This is the capability required for users to be able to access this menu item. Use manage_options here unless you know what you are doing and have reason to use another capability here. The manage_options capability is usually set aside for admin users so other roles will not have access to your admin menu items.
  4. 'gee_admin_settings_page' - This is your menu item's slug used to identify the menu item and should be unique. You will need this later to use with your submenu item.
  5. 'admin_pg_function' - This is the call back function. The call back function is the function that creates your actual admin page linked to the main menu item. It's the page that opens when you click on the main menu item.
  6. '' - You'll notice I left the sixth parameter blank by simply using two single quotes. This is because I am using the default menu icon which is the image of a gear. To use a custom icon for your menu item, include the image path and name here. This parameter is optional, but I had to include the single quotes to mark it's place due to the fact that I also included the optional seventh parameter.
  7. 3 - finally, the seventh parameter here is optional and determines the menu order. Using "3" here causes the menu item to appear directly under the "Dashboard" menu item. make the number higher to make it appear further down in the navigation bar.

Now let's look at the add_submenu_page function's parameters:

  1. 'gee_admin_settings_page' - this has to be the exact same as your main menu item's menu slug so notice how the same text is used in the add_menu_page function above it inside the AddAdminMenu function above.
  2. 'User Role Editor' - This is what shows up in the browser tab when the submenu item page is open. It is the title element for the submenu item's page.
  3. 'Edit User Roles' - This is the text for the submenu item that shows up in the left navigation bar directly under the main menu item's text.
  4. 'manage_options'  - Just like in the previous function, this is the capability the user role must have to access these menu items.
  5. 'user_role_editor_slug' - This is the menu slug for this sub menu item.
  6. 'edit_user_roles_function' - This is the call back function that creates the page linked to from the submenu item. We will discuss these functons and give examples next.

The call back functions

Now we will discuss the call back functions called within the AddAdminMenu function's inner functions of add_menu_page and add_submenu_page. The functions in this case were named admin_pg_function and edit_user_roles_function, but could be named anything, just make sure they are unique function names and that they are called inside of the add_menu_page and add_submenu_page functions respectively. Here are both function for creating the admin menu pages for the AddAdminMenu function:

function admin_pg_function(){
if(!current_user_can('manage_options')){
wp_die( __( 'You do not have sufficient permissions to access this page.' ) );
}
/*add any form processing code here in PHP:*/
?>
<div style="width:750px;">
<h1><span style="position:relative;top:-7px">GoldEagleXpress.com Custom Admin Settings</span></h1>

<?php
/*add the rest of your page content above here if it's HTML and below here if it's PHP!*/
}/*end admin_pg_function function.*/
/*end cody by Ian L. to add custom menu item to wp-admin...*/

function edit_user_roles_function(){
if(!current_user_can('manage_options')){
wp_die( __( 'You do not have sufficient permissions to access this page.' ) );
}
/*add any form processing code here in PHP:*/
?>
<div style="width:750px;">
<h1><span style="position:relative;top:-7px">GoldEagleXpress.com Custom User Role Settings</span></h1>

<?php
/*add the rest of your page content above here if it's HTML and below here if it's PHP!*/
}//end edit_user_roles_function function.
//############### end add main menu item to wp-admin ############

Summary

You will see if you cut and paste the code above, that it will simply create two menu items added to your navigation bar in your WordPress admin and two basically blank pages that you can go to by clicking on the new menu items. You will of course need to add some content in the last two functions here to add content to your admin pages. Good luck and happy coding!

2 thoughts on “Adding Main Menu and Submenu Items to WordPress Admin

Leave a Reply

Your email address will not be published. Required fields are marked *