Intro to WordPress Plugin Development: Add a Menu to Dashboard

In this section of the Intro to WordPress Plugin Development series, we’re going to learn how to add a menu to the dashboard with our plugin. Menus in WordPress can be overused by plugins. Some plugin developers feel that their plugin should have its own top-level menu when it’s really a plugin that belongs nested under another existing menu. We’ll look at why you might want to create a top-level menu, and why you may consider putting your menu under another existing menu.

To top-level menu or not to top-level menu

In a default WordPress install, there are already a number of top-level menus including:

• Dashboard
• Posts
• Media
• Pages
• Comments
• Appearance
• Plugins
• Users
• Tools
• Settings

Now, imagine you have 10 plugins installed and each adds another top-level menu. You’ve just doubled the number of top-level menus that are showing on your site’s dashboard, making it much more difficult to find what you’re looking for.

Think about it. If you have an image optimizing plugin, wouldn’t it make sense for its settings menu to be under the Media top-level menu? I mean, that is what the settings are for, right? What about if you have another plugin that manages user roles on the site. Seems like that menu should fall somewhere under the Users menu.

Now, what about if you add an e-commerce plugin to the site? Well, there really isn’t a good spot for that to sit, as the e-commerce plugin likely has a ton of settings. We’re probably looking at shipping options, payment gateway options, purchase confirmation emails, taxes, account settings, and a whole host of other options. Stuffing all of these options under the Settings or Tools menu wouldn’t make much sense because there are so many options that likely need to be accessed on a regular basis. In this case, it makes sense for the e-commerce plugin to have its own top-level menu, which possibly even has some sub-menus.

How to add a top-level menu to the dashboard

Adding a menu consists of at least two functions. The first will display the menu in the sidebar, and the second will display the content of the page once the user clicks on the menu link.

First, let’s add a top-level menu.

<?php
function sd_register_top_level_menu(){
	add_menu_page(
		'My Menu Title',
		'My Menu',
		'manage_options',
		'mymenupage',
		'sd_display_top_level_menu_page',
		'',
		6
	);
}
add_action( 'admin_menu', 'sd_register_top_level_menu' );

OK, so let’s look at this line by line since there is a lot of information to digest here.

We’re using the WordPress function add_menu_page, which is what triggers WordPress to add a new menu. See how descriptive names really help?

Parameters

This function has several parameters that are passed to it.

• Page Title: This is what shows up in the title tags of the page when the user clicks on the menu link. In many browsers, this is the text that shows up in the tab at the top of the browser. In our example, we used “My Menu Title”.
• Menu Title: This is what shows up in the actual menu in the sidebar. It will be the link the user clicks to visit the page. In our example, we used “My Menu”.
• Capability: This is the capability that a user is required to have in order to view this menu. In our example, we used “manage_options”, which usually corresponds to an administrator. Our sites Editors, Contributors, Subscribers, etc. would not be able to view this menu.
• Menu Slug: This is the slug that shows up in the URL for this menu. It should be unique for this menu so that it doesn’t conflict with other menus. In our example, we (poorly) chose to use “mymenupage”. It’s a poor choice because it could be used by any other plugin, and could cause conflicts. It’s a good idea to use a more descriptive slug here in actual practice.
• Function: This is the function that will output the content of the page once we click on the menu. In our example, we used “sd_display_top_level_menu_page”, which is a function that currently does not exist. If we click on this menu, we will end up with an error. We’ll work on creating this function next.
• Icon URL: You can specify an icon to be displayed next to the menu link. If none is specified (as we did here), the default icon will be used (it looks like gear ).
• Position: Finally, we can adjust the default position of the menu in the sidebar. A lower value would bring the menu higher up in the sidebar. A higher value would bring the menu lower in the sidebar. The default menus have a position assigned to them, which you can find here. Using the default menu positions, you can adjust where your menu appears in relation to other default menus.

Add content to your top-level menu

In our previous funciton, we included the function sd_display_top_level_menu_page, which will display the content of the page after clicking the menu. We haven’t created this function yet, so let’s do that now.

<?php
function sd_display_top_level_menu_page(){
	echo 'This is my page content';
}

This function simply displays the message “This is my page content”. While this isn’t particularly useful, you can certainly expand upon it to add additional content, and even a settings page if desired. We’ll look at how to add settings in the next part of the Intro to WordPress Plugin Development series.

Add a submenu page

Now that you have the basics of adding a menu, adding a submenu will be pretty easy. With a submenu page, we can hook into any of the existing top-level menus, or even menus added by other plugins/themes. All we need is the menu slug for the top-level menu that we want our submenu to sit under.

Finding the top-level menu slug

If you created the top-level menu like in the example above, it’s pretty easy to find that menu’s slug. Simply copy the fourth parameter passed to add_menu_page, which in our previous example was “mymenupage”.

If you want to hook into one of the default top-level menus, you would use the file name of the page you are linked to when clicking on the top-level menu.

• 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’

Now, what about a top-level menu added by another plugin? In many cases, we can click on the plugin’s menu page, and copy everything after wp-admin/ in the URL. For example, edit.php?post_type=some_post_type could work. If that doesn’t work, you may need to dig into the code a bit to find what their slug is.

For example, WooCommerce uses the slug “woocommerce” on their top-level menu, which is what you would need to create a sub-menu under that menu. You can find this by opening the /includes/admin/class-wc-admin-menus.php file in the WooCommerce plugin. Search for add_menu_page, which is around line 60 to see the ‘wooocommerce’ slug.

Adding the submenu page

In this example, we’ll add a submenu to the top-level menu we added earlier.

<?php
add_action( 'admin_menu', 'sd_register_sub_menu' );
 
function sd_register_sub_menu() {
	add_submenu_page(
		'mymenupage',
		'Custom Submenu Page Title',
		'Custom Submenu Page',
		'manage_options',
		'mymenusubpage',
		'sd_display_sub_menu_page'
	);
}

The only differences in the add_submenu_page parameters and the add_menu_page parameters, are:

• Parent slug: We’re adding the parent menu’s slug as the first parameter here.
• No icon URL: The submenus don’t get their own icons, so this parameter is left off.
• Position: The submenus can’t be positioned the same way that top-level menus can. Therefore we don’t add a position parameter here either.

The function to add content to the submenu page would work the same way as the function that adds content to the top-level menu page. Simply create the function and then have it display whatever content you need it to display.