The path to admin menu enlightenment

Posted on February 25, 2011

We’ve all seen this menu a million times. It’s our friendly neighborhood WordPress admin nav menu. If your’re the kind of person who enjoys making plugins you’re probably on the following path.

Level 1

Q) My plugin is simple and all my options fit on a single page. How do I add an option page for my plugin?
A) Let add_options_page() be your guide.

add_options_page('Simple Options','Simple','activate_plugins','simple-admin-settings',array('tutorial','controlForm'));

Level 2

Q) My plugin is not that simple anymore and I’m going to need more than one page to control all this awesome. How do I make a whole new top level nav container like Users, Tools or Settings?
A) add_menu_page() with a couple add_submenu_page() calls will solve this problem lickety split.

add_menu_page('Complicated Options', 'Complicated', 'activate_plugins', 'complicated', array("tutorial", "controlForm"));
add_submenu_page('complicated', 'Reporting', 'Reporting', 'activate_plugins', 'reporting', array('tutorial', 'reporting'));
add_submenu_page('complicated', 'More Options', 'More', 'activate_plugins', 'moreoptions', array('tutorial', 'moreControl'));

Level 3

Q) My awesome is contained in a box but I don’t want the first link to match the name of the nav container. I want reporting to be first and I don’t want that first link to say Complicated. How do I change the name in that first link?
A) add_menu_page() with a couple add_submenu_page() still but we have to do something a little weird.

What you have to do is make the first submenu page have the same slug as the top level menu page and have them both point at the same callback.

add_menu_page('Complicated Options', 'Complicated', 'activate_plugins', 'complicated', array("tutorial", "reporting"));
add_submenu_page('complicated', 'Reporting', 'Reporting', 'activate_plugins', 'complicated', array('tutorial', 'reporting'));
add_submenu_page('complicated', 'Options', 'Options', 'activate_plugins', 'control', array('tutorial', 'controlForm'));
add_submenu_page('complicated', 'More Options', 'More', 'activate_plugins', 'moreoptions', array('tutorial', 'moreControl'));

Level 4 – Menu Nirvana

Q) My menu link is perfect in every way but for UI purposes I want the menu page to show up somewhere else in the nav menu, not at the bottom. How do I place it somewhere else?
A) add_menu_page() and its siblings add_object_page() and add_utility_page() help you out here.

First, a brief description of the “priority” argument to add_menu_page(). You can forcibly put your menu page wherever you want in the nav menu. If you ever programmed BASIC in the days you had to type line numbers this will seem familiar. Each menu has a position, illustrated here

So if you wanted to drop your menu right after comments you could do the following (but don’t, I’ll explain why in a second)

add_menu_page('Tickets', 'Tickets', 'activate_plugins', 'eventticketing', array("eventTicketingSystem", "ticketReporting"),'',30);

It looks good but there is a fatal flaw in this method and that is that there is no internal check to make sure that 2 plugins aren’t picking the same position in the menu. In this case what happens is whichever plugin gets loaded second wins. Your plugin will work just find and you can manually get to all your option pages via their slugs but you won’t be able to see it at all. We discovered this the hard way when we picked 30 for a plugin we wrote. 30 is an especially bad one to chose as that’s the same menu position that Thesis picks for itself.

WordPress understands this desire, however, and gives you an easy way to pick that spot which picking 30 would get you: add_object_page().

add_object_page('Complicated Options', 'Complicated', 'activate_plugins', 'complicated', array("tutorial", "reporting"));
add_submenu_page('complicated', 'Reporting', 'Reporting', 'activate_plugins', 'complicated', array('tutorial', 'reporting'));
add_submenu_page('complicated', 'Options', 'Options', 'activate_plugins', 'control', array('tutorial', 'controlForm'));
add_submenu_page('complicated', 'More Options', 'More', 'activate_plugins', 'moreoptions', array('tutorial', 'moreControl'));

The benefit here is that it just appends and as long as plugins are using it, they won’t be bumping into each other. There’s also add_utility_page() which appends your menu below the Settings menu page. The difference between this and just not using a position whatsoever is that this method puts it above anything menu page which has no position defined. Position 81 instead of position 100 as seen in the previous screenshots.

Hopefully this helps you understand menu positioning a little bit more and if you find that your menu position is causing your plugin to disappear in certain circumstances, take a look at what else you have activated and what positions they’re grabbing. Odds are it’s the same one you are

And, like so many things in life, it’s not always what you know but who you know. Big, big thank you to Brandon Dove for pointing out how to rename the first link in a menu page to be something different than the name of the menu page.