WordPress Theme Developers Tip – Adding Theme Menu

I’ve already discussed how to add an theme options page. Sometimes, as my theme has, a theme just outgrows having one menu page for everything. Instead of adding a second page under the Appearance Menu a separate menu might be best. The below code is an example of the functions required to use a separate menu.

 
function mytheme_admin_page() {
	add_menu_page("Theme Options", "Top Level Menu Name", 'edit_themes', 'menu_display_function','','',61);
	add_submenu_page('menu_display_function' ,"Sub Page Title 1", "Sub Page Menu Text", 'edit_themes', 'menu_display_function', 'sub_men_display_function');
	add_submenu_page('menu_display_function' ,"Sub Page Title 2", "Sub Page Menu Text 2", 'edit_themes', 'menu_display_function', 'sub_men_display_function_2');
}
menu_display_function(){
echo "Top Level Menu Page";
}
sub_menu_display_function(){
echo "Sub Page Level Page";
}
sub_menu_display_function_2(){
echo "Sub Page Level Page 2";
}
add_action('admin_menu', 'mytheme_admin_page'); 

So what does this code do the add_menu_page function adds the top level container, this is like the Appearance, Plugins, Users … menu that already exist.

add_menu_page(page_title, menu_title, capability, handle, [function], [icon_url],menu_order);

The parameters are

page_title
Text that will go into the HTML page title for the page when the menu is active.
menu_title
The on-screen name text for the menu.
capability
The minimum capability required to display and use this menu page. Whilst for legacy reasons, you may also use user level – the usage of user level is discouraged for future compatibility and has been deprecated since WordPress 1.5.
handle/file
If the function parameter is omitted, this should be the PHP file that handles the display of the menu page content. Otherwise, and more commonly, it will be a unique “handle” for the page. e.g. “my-awesome-plugin-settings”
function
The function that displays the page content for the menu page.
icon_url
The path to the icon for the menu, if not given default to a gear icon.
menu_order
A number for where the new menu should be inserted, defaults to below all other menus. The 61 in the example code will place the menu right below the Appearance menu, which should work nicely for a theme admin menu.

To add the sub pages to the menu you call the add_submenu_page function.

add_submenu_page(parent, page_title, menu_title, capability required, file/handle, [function]);

Parameters:

parent
The filename of the core WordPress admin file that supplies the top-level menu in which you want to insert your submenu, or your plugin file if this submenu is going into a custom top-level menu.
page_title
Text that will go into the HTML page title for the page when the submenu is active.
menu_title
The on-screen name text for the submenu.
capability
The minimum capability required to display and use this menu page. Whilst for legacy reasons, you may also use user level the usage of user level is discouraged for future compatibility and has been deprecated since WordPress 1.5.
file
For existing WordPress menus, the PHP file that handles the display of the menu page content. For submenus of a custom top-level menu, a unique identifier for this sub-menu page.

In situations where a plugin is creating its own top-level menu, the first submenu will normally have the same link title as the top-level menu and hence the link will be duplicated. The duplicate link title can be avoided by calling the add_submenu_page function the first time with the parent and file parameters being given the same value.

function
The function that displays the page content for the menu page.

This is a very quick example of how this is done. I will be updating my Theme Options Framework to include this as an option and to show how this is used in practice. I’ve also done this for my Techozoic Fluid 1.8.6 theme which should be available soon.

Resources:

About Jeremy Clark

Small town IT worker with interests in all things technological and technical. Biggest interests are in web development especially the WordPress publishing platform and the community supporting it. Currently developing and maintain the free WordPress theme Techozoic. I'm also always available for hire.
This entry was posted in tips, wordpress and tagged , , . Bookmark the permalink.

2 Responses to "WordPress Theme Developers Tip – Adding Theme Menu"

Leave a reply

Comments will be sent to the moderation queue.