How to Add Horizontal Submenus to Your Administration Plugin in WordPress 2.7+

With the launch of version 2.7 in December 2008, WordPress added several new features and changed its user interface (UI). I especially like the new automatic update feature and the new vertical sidebar is sleeker and more modern looking. However, I find navigating the menus on that new sidebar to be very inefficient when administration plugins add more selections to it.
Image #1: Plugin with sidebar menu

As an admin plugin author, I want my users to have easy access to my plugin menu and submenus. In WordPress 2.2 to 2.6, the built-in menu functions accomplished this with horizontal menus at the top of the page. In 2.7, however, the same menu functions now place the plugin menu (and submenus) near the bottom of the page, in the sidebar. This makes navigation more cumbersome because plugin menus are positioned outside the initial viewing area of the screen in a typical 1280×800 browser window. The user has to scroll down to select the plugin and, after the plugin is selected, scroll down again to navigate the plugin’s submenus. Worse, it not always obvious that there are submenus available for a plugin. You can see an example of this in image #1 where the green line indicates the end of the window area of a 1280×800 resolution browser window.

To workaround this problem in my own admin plugin, I inserted a new horizontal menu containing the submenu links at the top of each submenu page.
image #2: Plugin with horizontal menu To keep the look consistent with WordPress' new style, I positioned the menu inline with the “contextual help” button and also adopted it’s “look and feel”. This was a relatively simple task to do, once I located and copied the appropriate styles from WordPress' admin stylesheets. You can see an example of this new horizontal menu in the second image to the right.

Below are step-by-step instructions on how you can do this for your own “top-level” admin plugin with submenus. Please note that the rest of this article assumes prior knowledge of WordPress plugin writing and basic PHP, HTML and CSS skills.

• Step #1: Create the plugin menu and submenu pages

  Use the WordPress functions, add_menu_page and add_submenu_page, to create your plugin's menu and submenus. This maintains compatibility with earlier versions of WordPress (2.0+) and sets the “page” parameter for your submenu pages. This parameter is used on the admin url to link to your plugin pages and is needed for the submenu links in the horizontal menu in step #2 below.

  Your plugin menu/submenu code should look something like this:

  <?php
  define('DEMOFILE',basename(__FILE__));
  
  //give plugin a top-level WordPress admin menu with submenus
  function demo_menus() {
  	// userlevel=8 restrict users to "Administrators" only
  	add_menu_page('demofromhel', 'Demo from Hel', 8, DEMOFILE, 'demo_content');
  	add_submenu_page(DEMOFILE, 'SubMenu-1 Title', 'SubMenu-1', 8, DEMOFILE, 'demo_content');
  	add_submenu_page(DEMOFILE, 'SubMenu-2 Title', 'SubMenu-2', 8, 'demo-page2', 'demo_content');
  	add_submenu_page(DEMOFILE, 'SubMenu-3 Title', 'SubMenu-3', 8, 'demo-page3', 'demo_content');
  }

  The constant, DEMOFILE, is your plugin filename and also the “page” parameter value for the default submenu (SubMenu-1) page.

• Step #2: Create a new menu as an “unordered” list of links to each submenu page

  Inside your plugin's content function, create an unordered list (<ul>) containing links to each submenu page. This will be your plugin's horizontal submenu for WordPress 2.7. Insert this list just above the main “wrap” <div> in your document. Give the <ul> tag a unique id and give each <li> tag the same class name. The submenu page links should be listed in the reverse of their intended display order. This is necessary because of the float:right style attribute used to format the menu (see step #3 below). After the terminating </ul> tag, add an empty <div> with the inline style, style="clear:right;". This extra <div> fixes a css bug in IE7. Then, enclose the entire code within a PHP statement that tests for WordPress version 2.7 or higher. This “if” code block excludes the plugin horizontal submenu from earlier versions of WordPress where it would be redundant. This section of code looks like:

  function demo_content() {
  	global $wpdb, $wp_version;
  	if (version_compare($wp_version, '2.7', '>=')) {  ?>
  	<ul id="demo-menu">
  		<li class="demo-menu-link"><a href="?page=demo-page3">SubMenu-3</a></li>
  		<li class="demo-menu-link"><a href="?page=demo-page2">SubMenu-2</a></li>
  		<li class="demo-menu-link"><a href="?page=<?php echo DEMOFILE; ?>">SubMenu-1</a></li>
  	</ul>
  	<div style="clear:right;"></div>
  	<?php
  	} ?>
  	<div class="wrap">
  		<div id="icon-plugins" class="icon32"></div>
  		<h2>Demo from Hel</h2>
  		<?php	//output page content for each plugin submenu page
  		if ($_GET['page'] == "demo-page3") {
  			print '<p>Demo page 3 content</p>';
  		} elseif ($_GET['page'] == "demo-page2" ) {
  			print '<p>Demo page 2 content</p>';
  		} else {	//page 1 is default
  			print '<p>Demo page 1 / default content</p>';
  		} ?>
  		<hr/>
  	</div>
  <?php }

  Of course, your plugin should output content for each submenu “page” of your plugin. As the above example shows, you can read PHP's $_GET['page'] parameter to identify individual pages and customize content accordingly. The content must be enclosed inside a “wrap” division (<div class="wrap">) in keeping with WordPress' admin style standard and for the “ul” menu to be formatted properly. Also, note that the variable, $wp_version is a global WordPress variable and must be declared in the “GLOBAL” section of your content function.

• Step #3: Style your new menu to display horizontally, like the “help” button

  Next, in your plugin's css stylesheet file, insert the following css code to format the menus so that they are in-line with the “contextual help” button and they use the same background image. If you don’t have a separate css file for your plugin, just put these lines in a <style> tag in your plugin's “head” function or above the <ul> menu code in the “content” function.

  #demo-menu {
  	display: inline;
  	position: relative;
  }
  #demo-menu a, #demo-menu a.link {
  	text-decoration: none;
  	z-index: 1;
  	margin: 0 auto;
  	padding: 0 6px 0 6px;
  	height: 22px;
  	line-height: 22px;
  	font-size: 10px;
  	background-repeat: no-repeat;
  	background-position: right bottom;
  }
  .demo-menu-link {
  	float: right;
  	background: transparent url(images/screen-options-left.gif ) no-repeat 0 0;
  	font-family: "Lucida Grande", Verdana, Arial, "Bitstream Vera Sans", sans-serif;
  	height: 22px;
  	padding: 0;
  	margin: 0 6px 0 0;
  	text-decoration: none;
  	text-align:center;
  }

  You can expand on these styles by adding “a:visited”, “a:hover” and “a:active” css attributes as well.

• Step #4: Integrate your plugin and menus into WordPress with admin “hooks”

  Lastly, near the bottom of your plugin program, add the appropriate admin hooks to incorporate your plugin functions into WordPress. Use the “admin_menu” hook to integrate the menus and submenu pages into WordPress admin. Use the “admin_head” hook to integrate your plugin stylesheet (and javascripts, if any) into WordPress admin <head>.

  //hook the plugin functions into WordPress admin
  add_action('admin_menu', 'demo_menus');
  add_action('admin_head', 'demo_head');
  

  Note that the “demo_content” function is also “hooked” into WordPress via the “admin_menu” hook as each submenu page calls that function. Also, the “admin_head” hook is not needed unless you created a “demo_head” function containing the <style> tag for your css code or containing the css stylesheet link.

And you are DONE!

Here is the entire code in a single program:

<?php
global $wpdb, $wp_version;
define('DEMOFILE',basename(__FILE__));

//give plugin a top-level WordPress admin menu with submenus
function demo_menus() {
	// userlevel=8 restrict users to "Administrators" only
	add_menu_page('demofromhel', 'Demo from Hel', 8, DEMOFILE, 'demo_content');
	add_submenu_page(DEMOFILE, 'SubMenu-1 Title', 'SubMenu-1', 8, DEMOFILE, 'demo_content');
	add_submenu_page(DEMOFILE, 'SubMenu-2 Title', 'SubMenu-2', 8, 'demo-page2', 'demo_content');
	add_submenu_page(DEMOFILE, 'SubMenu-3 Title', 'SubMenu-3', 8, 'demo-page3', 'demo_content');
}

function demo_head() {
	global $wp_version;
	if (version_compare($wp_version, '2.7', '>=')) {  ?>
<style type="text/css">
#demo-menu {
	display: inline;
	position: relative;
}
#demo-menu a, #demo-menu a.link {
	text-decoration: none;
	z-index: 1;
	margin: 0 auto;
	padding: 0 6px 0 6px;
	height: 22px;
	line-height: 22px;
	font-size: 10px;
	background-repeat: no-repeat;
	background-position: right bottom;
}
.demo-menu-link {
	float: right;
	background: transparent url(images/screen-options-left.gif ) no-repeat 0 0;
	font-family: "Lucida Grande", Verdana, Arial, "Bitstream Vera Sans", sans-serif;
	height: 22px;
	padding: 0;
	margin: 0 6px 0 0;
	text-decoration: none;
	text-align:center;
}
</style>
<?php
	}
}

function demo_content() {
	global $wpdb, $wp_version;
	if (version_compare($wp_version, '2.7', '>=')) {  ?>
	<ul id="demo-menu">
		<li class="demo-menu-link"><a href="?page=demo-page3">SubMenu-3</a></li>
		<li class="demo-menu-link"><a href="?page=demo-page2">SubMenu-2</a></li>
		<li class="demo-menu-link"><a href="?page=<?php echo DEMOFILE; ?>">SubMenu-1</a></li>
	</ul>
	<div style="clear:right;"></div>
<?php	} ?>
	<div class="wrap">
		<div id="icon-plugins" class="icon32"></div>
		<h2>Demo from Hel</h2>
		<?php	//output page content for each plugin submenu page
		if ($_GET['page'] == "demo-page3") {
			print '<p>Demo page 3 content</p>';
		} elseif ($_GET['page'] == "demo-page2" ) {
			print '<p>Demo page 2 content</p>';
		} else {	//page 1 is default
			print '<p>Demo page 1 / default content</p>';
		} ?>
		<hr/>
	</div>
<?php }

//hook the plugin functions into WordPress admin
add_action('admin_menu', 'demo_menus');
add_action('admin_head', 'demo_head');
?>

I put this code into a functioning plugin that you can install, activate, and test for yourself. You can download it here. To install, unzip the archive, copy demo_from_hel.php to your plugin directory, and activate.

This horizontal menu code was tested successfully in IE 6, IE 7, FF 1.5-mac, FF 2, FF 3, Mozilla 1.7, Safari 1.3, Safari 2, Safari 3-Win, Chrome 1.0, and Camino 1.6. Feedback regarding other browsers would be appreciated.

For more information on integrating WordPress’ adminstration menus or submenus into your plugin, see the codex doc: Adding Administration Menus. To learn about writing plugins for WordPress, read the codex doc: Writing_a_Plugin.