In our last lesson, we discussed how to create top-level menus. We’ll now learn how to create WordPress admin submenus. We’ll be working with the same plugin we created in our previous lesson.
Let’s update our menus.inc.php file to this.
add_menu_page( 'Top-level Menu Example' , 'Top-level Menu' , 'manage_options' , __FILE__ , 'jk_display_main_options');
add_submenu_page( __FILE__ , 'Submenu', 'Submenu' , 'manage_options' , __FILE__ . '_submenu' , 'jk_display_submenu_main_options');
WordPress Admin Submenus
As you can see we used the add_submenu_page() function to add a submenu. It takes in 6 parameters which are the following.
- Parent Slug – This defines which top-level menu our WordPress admin submenus should appear in. In our case, we gave our top-level menu the slug of __FILE__ which would correspond to the 4th parameter in the add_menu_page() function.
- Page Title – This is the page title you see at the top of your browser.
- Menu Title – This is the name for your submenu.
- Capability – This is the same definition I gave for when I was explaining top-level menus. This is what the user must be permitted to do in order to see this submenu.
- Menu Slug – This is the URL for our submenu. In our case we once again use the magic constant __FILE__ plus we append _submenu because our top-level menu is already using the magic constant __FILE__.
- Function – This parameter is the only optional parameter. This is the function we call when someone clicks on this menu item.
As you can see, we aren’t allowed to define an icon or a position. WordPress doesn’t use icons for submenus and submenus are ordered according to the order they’re defined.
Before we go any further, we must update our display-options.inc.php file.
echo 'This our options page';
echo 'This our submenu options page';
We defined the function we called in our add_submenu_page() function. Now we can refresh the dashboard and if you hover your mouse over our newly created top-level menu, we can see the submenu we created. You can also click it and you should see the message “This is our submenu options page”.
You will also notice WordPress automatically makes your top-level menu item into a submenu as well.
Creating A Submenu for WordPress defined Menus
Sometimes you don’t need your own top-level menu. You may want to just have a submenu because your plugin is so simple and has few settings. I highly suggest you put your submenu in an already defined top-level menu because only plugins that absolutely have a variety of options should have a top-level menu. If you really need it, then create a top-level menu, otherwise use a WordPress defined top-level menu.
Change your add_submenu_page in your menus.inc.php file to this.
add_submenu_page( 'options-general.php' , 'Submenu', 'Submenu' , 'manage_options' , __FILE__ . '_submenu' , 'jk_display_submenu_main_options');
We simply changed the first parameter to options-general.php. This is the name for the settings top-level menu. WordPress has a list of Menu slugs for the admin menus here. Take a look at the menu slugs you can use in order to add your submenu to them. This is how you create WordPress admin submenus.