This idea is not necessarily new but finding an example may be a bit more difficult. Let’s have a look …

First off, there are several sources of information regarding wp_nav_menu() to take into consideration:

Each of these links will open in a new tab/window for convenience purposes.

• The WordPress codex reference.
• The “core.trac.wordpress.org” reference.
• This web site’s references.

Now that we have a list of reading material we should actually take a look at it …

• The first reference leads to the WordPress codex and provides the standard parameters that can be used with wp_nav_menu().
• The next reference and the experience that was offered by Ian Stewart from ThemeShaper.com is the real key to solving this little puzzle.
• The last reference simply leads to the wp_nav_menu() tag archive here.

I would suggest at least having a quick look at those pages before carrying on to the next page, especially the one referencing the wp_nav_menu() function in the “core”, or primary code base of WordPress, as you will find a very relevant comment there.

Let’s start by focusing on the following code snippet as found in the “core” reference:

// Allow plugins to hook into the menu to add their own <li>'s
$items = apply_filters( 'wp_nav_menu_items', $items, $args );
$items = apply_filters( "wp_nav_menu_{$menu->slug}_items", $items, $args );
$nav_menu .= $items;

The beauty of this little snippet is it shows, with the use of the wp_nav_menu_item filter, you can add specific items to the menu output if the end-user has chosen to create a custom menu. Let’s look at an example that will allow you to add a “Home” page link to the beginning of the menu.

If you add the following to your ‘functions.php’ template file it will add a home link to your wp_nav_menu() output:

// Filter wp_nav_menu() to add additional links and other output
function new_nav_menu_items($items) {
	$homelink = '<li class="home"><a href="' . home_url( '/' ) . '">' . __('Home') . '</a></li>';
	$items = $homelink . $items;
	return $items;
}
add_filter( 'wp_nav_menu_items', 'new_nav_menu_items' );

The basic premise of the function is:

1. Assign your desired output to a variable
2. Concatenate the output variable with the $items variable
3. Return the $items variable so it can be used in the filter
4. Add the results of the function to wp_nav_menu_items with an add_filter() function

If you wish to use this when a custom menu is not being used just add the following (or similar) filter after the above code:

add_filter( 'wp_list_pages', 'new_nav_menu_items' );

But what if we wanted to add something to the end of the menu output, such as a RSS feed link, or maybe just some random text or a static URL link. Let’s look at the following example which expands upon the code above to do just that.

// Filter wp_nav_menu() to add additional links and other output
function new_nav_menu_items($items) {
	$homelink = '<li class="home"><a href="' . home_url( '/' ) . '">' . __('Home') . '</a></li>';
	$feedlink = '<li class="feed"><a href="' . get_bloginfo_rss('rss2_url') . '">' . __('RSS') . '</a></li>';
	$random_text = '<li class="rainbows"><a href="#">OMG ... Double Rainbows!</a></li>';
	$items = $homelink . $items;
	$items = $items . $feedlink;
	$items = $items . $random_text;
	return $items;
}
add_filter( 'wp_list_pages', 'new_nav_menu_items' );
add_filter( 'wp_nav_menu_items', 'new_nav_menu_items' );

There always seems to be some new way to add more uses to the core functions in WordPress and I like to find, explore and write about them. I often implement them in the First Aid Theme, as I have done by using the above example code to add a “Home” link to the menu. On the next page I will leave you with one more example, the one I referred to in the opening paragraph.

Although this was a bit more involved it really did not make that much of a difference in the case of implementing this in a custom menu so without further ado here is the code snippet:

function new_nav_menu_items($items) {
  $cat_menu_list = wp_list_categories( 'echo=0&title_li=&child_of=124' );
  $items = $items . $cat_menu_list;
  return $items;
}
add_filter( 'wp_nav_menu_items', 'new_nav_menu_items' );

If you are trying this at home make back-ups of your files, just in case you want to revert your edits. Your category list hierarchy may need to be noted as well.

The key to this snippet is the wp_list_categories() by default will echo its results to the screen, you will have to set the parameter ‘echo=0′ to turn off this default behavior.

As for using this technique for categories with a non-custom menu I will leave that as an exercise for those looking for a challenge … Enjoy!

This article will be covering the implementation of the wp_nav_menu() function using the wp_list_pages() function as a fallback. The menu will also be centered and support full drop down sub-menu items, or child pages as some would refer to them … and, the menu system now live on this site, too.

The following code will also be released in the free WordPress Theme Shades at version 1.6, and it will also be the basis for the examples used in this post.

Let’s get started …

What We Need

• wp_list_pages()
• wp_nav_menu()
• register_nav_menu()
• Upgrade wp_list_pages() to wp_nav_menu()
• Shades
• CSS

Have a look at the codex pages above for wp_list_pages(), wp_nav_menu, and register_nav_menu to get (more) familiar with the basics of these functions. As this has to do with the use of wp_list_pages() reading the article “Upgrade wp_list_pages() to wp_nav_menu()” may also prove useful.

Although not absolutely necessary, getting a copy of the Shades theme may be handy if you wish to look at the code directly rather than the examples and snippets to follow.

The last part is the CSS to make it all work. This is from a great article written by Matthew James Taylor and can be found here.

On the next page we will look at what to do …

What We Will Do

First we are going to open the functions.php template file and start with adding the following code:

wp_nav_menu( array(
   'theme_location' => 'top-menu',
   'fallback_cb' => 'custom_list_pages'
   ) );

Next we will need to incorporate the fallback menu code via wp_list_pages(), with the following:

function custom_list_pages() {
  if ( is_home() || is_front_page() ) { ?>
    <ul><?php wp_list_pages( 'title_li=' ); ?></ul>
  <?php } else { ?>
    <ul>
      <li><a href="<?php bloginfo( 'url' ); ?>"><?php _e( 'Home' ); ?></a></li>
      <?php wp_list_pages( 'title_li=' ); ?>
    </ul>
  <?php }
}

Both of these functions will need to be included in the custom function that will be the base of our new menu system. The code looks like this:

function custom_nav_menu() {
    if ( function_exists( 'wp_nav_menu' ) )
      wp_nav_menu( array(
			   'theme_location' => 'top-menu',
			   'fallback_cb' => 'custom_list_pages'
			   ) );
    else
      custom_list_pages();
}

Then we need to register the custom function and give it a place to live. This code will accomplish that:

add_action( 'init', 'register_custom_menu' );
function register_custom_menu() {
    register_nav_menu( 'top-menu', __( 'Top Menu' ) );
}

The heavy lifting is done, now we need to address the actual display of the menu. Let’s open the header.php template file and place the custom function appropriately.

<div id="centeredmenu">
	<?php custom_nav_menu(); ?>
</div> <!-- #centeredmenu -->

Now for all intent and purpose the CSS from Matthew James Taylor’s post can be dropped into the style.css file, like so:

/* Main menu settings */
#centeredmenu {
   clear:both;
   float:left;
   margin:0;
   padding:0;
   border-bottom:1px solid #000; /* black line below menu */
   width:100%;
   font-family:Verdana, Geneva, sans-serif; /* Menu font */
   font-size:90%; /* Menu text size */
   z-index:1000; /* This makes the dropdown menus appear above the page content below */
   position:relative;
}

/* Top menu items */
#centeredmenu ul {
   margin:0;
   padding:0;
   list-style:none;
   float:right;
   position:relative;
   right:50%;
}
#centeredmenu ul li {
   margin:0 0 0 1px;
   padding:0;
   float:left;
   position:relative;
   left:50%;
   top:1px;
}
#centeredmenu ul li a {
   display:block;
   margin:0;
   padding:.6em .5em .4em;
   font-size:1em;
   line-height:1em;
   background:#ddd;
   text-decoration:none;
   color:#444;
   font-weight:bold;
   border-bottom:1px solid #000;
}
#centeredmenu ul li.active a {
   color:#fff;
   background:#000;
}
#centeredmenu ul li a:hover {
   background:#36f; /* Top menu items background colour */
   color:#fff;
   border-bottom:1px solid #03f;
}
#centeredmenu ul li:hover a,
#centeredmenu ul li.hover a { /* This line is required for IE 6 and below */
   background:#36f; /* Top menu items background colour */
   color:#fff;
   border-bottom:1px solid #03f;
}

/* Submenu items */
#centeredmenu ul ul {
   display:none; /* Sub menus are hiden by default */
   position:absolute;
   top:2em;
   left:0;
   right:auto; /*resets the right:50% on the parent ul */
   width:10em; /* width of the drop-down menus */
}
#centeredmenu ul ul li {
   left:auto;  /*resets the left:50% on the parent li */
   margin:0; /* Reset the 1px margin from the top menu */
   clear:left;
   width:100%;
}
#centeredmenu ul ul li a,
#centeredmenu ul li.active li a,
#centeredmenu ul li:hover ul li a,
#centeredmenu ul li.hover ul li a { /* This line is required for IE 6 and below */
   font-size:.8em;
   font-weight:normal; /* resets the bold set for the top level menu items */
   background:#eee;
   color:#444;
   line-height:1.4em; /* overwrite line-height value from top menu */
   border-bottom:1px solid #ddd; /* sub menu item horizontal lines */
}
#centeredmenu ul ul li a:hover,
#centeredmenu ul li.active ul li a:hover,
#centeredmenu ul li:hover ul li a:hover,
#centeredmenu ul li.hover ul li a:hover { /* This line is required for IE 6 and below */
   background:#36f; /* Sub menu items background colour */
   color:#fff;
}

/* Flip the last submenu so it stays within the page */
#centeredmenu ul ul.last {
   left:auto; /* reset left:0; value */
   right:0; /* Set right value instead */
}

/* Make the sub menus appear on hover */
#centeredmenu ul li:hover ul,
#centeredmenu ul li.hover ul { /* This line is required for IE 6 and below */
   display:block; /* Show the sub menus */
}

Although this will work as is in most cases there are a few items that can be modified to better suit a theme. On the next page is the actual CSS being used in the Shades theme, version 1.6, to accommodate its requirements as well as meeting current theme review criteria as noted on the WordPress codex page here.

What May Need To Be Adjusted

Note the changes at the following lines: 231, 251, 254, 259, 262, 296, and especially 310 for multiple line menus.

/* Main menu settings */
#centeredmenu {
   clear:both;
   float:left;
   margin:0;
   padding:0;
   border-bottom:1px solid #000; /* black line below menu */
   width:100%;
   font-family:Verdana, Geneva, sans-serif; /* Menu font */
   font-size:90%; /* Menu text size */
   z-index:1000; /* This makes the dropdown menus appear above the page content below */
   position:relative;
}

/* Top menu items */
#centeredmenu ul {
   margin:0;
   padding:0;
   list-style:none;
   float:right;
   position:relative;
   right:50%;
}
#centeredmenu ul li {
   margin:0 0 0 1px;
   padding:0;
   float:left;
   position:relative;
   left:50%;
   /* top:1px; */
}
#centeredmenu ul li a {
   display:block;
   margin:0;
   padding:.6em .5em .4em;
   font-size:1em;
   line-height:1em;
   background:#ddd;
   text-decoration:none;
   color:#444;
   font-weight:bold;
   border-bottom:1px solid #000;
}
#centeredmenu ul li.active a {
   color:#fff;
   background:#000;
}
#centeredmenu ul li a:hover {
   /* background:#36f; /* Top menu items background colour */
   background: #8c8c8c;
   color:#fff;
   /* border-bottom:1px solid #03f; */
   border-bottom:1px solid #444;
}
#centeredmenu ul li:hover a,
#centeredmenu ul li.hover a { /* This line is required for IE 6 and below */
   /* background:#36f; /* Top menu items background colour */
   background: #8c8c8c;
   color:#fff;
   /* border-bottom:1px solid #03f; */
   border-bottom:1px solid #444;
}

/* Submenu items */
#centeredmenu ul ul {
   display:none; /* Sub menus are hiden by default */
   position:absolute;
   top:2em;
   left:0;
   right:auto; /*resets the right:50% on the parent ul */
   width:10em; /* width of the drop-down menus */
}
#centeredmenu ul ul li {
   left:auto;  /*resets the left:50% on the parent li */
   margin:0; /* Reset the 1px margin from the top menu */
   clear:left;
   width:100%;
}
#centeredmenu ul ul li a,
#centeredmenu ul li.active li a,
#centeredmenu ul li:hover ul li a,
#centeredmenu ul li.hover ul li a { /* This line is required for IE 6 and below */
   font-size:.8em;
   font-weight:normal; /* resets the bold set for the top level menu items */
   background:#eee;
   color:#444;
   line-height:1.4em; /* overwrite line-height value from top menu */
   border-bottom:1px solid #ddd; /* sub menu item horizontal lines */
}
#centeredmenu ul ul li a:hover,
#centeredmenu ul li.active ul li a:hover,
#centeredmenu ul li:hover ul li a:hover,
#centeredmenu ul li.hover ul li a:hover { /* This line is required for IE 6 and below */
   /* background:#36f; /* Sub menu items background colour */
   background: #8c8c8c;
   color:#fff;
}

/* Flip the last submenu so it stays within the page */
#centeredmenu ul ul.last {
   left:auto; /* reset left:0; value */
   right:0; /* Set right value instead */
}

/* Make the sub menus appear on hover */
#centeredmenu ul li:hover ul,
#centeredmenu ul li.hover ul { /* This line is required for IE 6 and below */
   display:block; /* Show the sub menus */
   z-index: 1500; /* Required for multi-line menus */
}

/* -- Extra Window Dressings -- */
#centeredmenu ul li a {
  /* optional rounded corners for browsers that support it */
  -moz-border-radius: 5px 5px 0 0;
  -khtml-border-radius: 5px 5px 0 0;
  -webkit-border-radius: 5px 5px 0 0;
  border-radius: 5px 5px 0 0;
}

#centeredmenu ul li:first-child a { /* First parent menu item */
  /* optional rounded corners for browsers that support it */
  -moz-border-radius: 10px 5px 0 0;
  -khtml-border-radius: 10px 5px 0 0;
  -webkit-border-radius: 10px 5px 0 0;
  border-radius: 10px 5px 0 0;
}

#centeredmenu ul li:last-child a { /* Last parent menu item */
  /* optional rounded corners for browsers that support it */
  -moz-border-radius: 5px 10px 0 0;
  -khtml-border-radius: 5px 10px 0 0;
  -webkit-border-radius: 5px 10px 0 0;
  border-radius: 5px 10px 0 0;
}

#centeredmenu ul ul li:last-child a { /* remove rounded corners from sub-menu items */
  /* optional rounded corners for browsers that support it */
  -moz-border-radius: 0;
  -khtml-border-radius: 0;
  -webkit-border-radius: 0;
  border-radius: 0;
}

#centeredmenu ul ul ul li a { /* "grandchild" sub-menu items */
  padding-left: 10px;
}

A little extra was added at the end of the CSS to add some rounded corner emphasis to the top menu tabs as well as some additional padding for sub-sub-menu items.

Thanks again to Mathew James Taylor for the great CSS.

Enjoy!

Like the last post in the series we will look at the default arguments used by each function, starting with wp_nav_menu() ¹:

wp_nav_menu( array(
    'menu'              => '',
    'container'         => 'div',
    'container_class'   => '',
    'container_id'      => '',
    'menu_class'        => 'menu',
    'menu_id'           => '',
    'echo'              => true,
    'fallback_cb'       => 'wp_page_menu',
    'before'            => '',
    'after'             => '',
    'link_before'       => '',
    'link_after'        => '',
    'depth'             => 0,
    'walker'            => '',
    'theme_location'    => ''
    ) );

The following is a default “menu” version of wp_list_pages() ^{2, 3}, often wrapped within a <ul class=”menu”> tag:

<ul class="menu">
<?php wp_list_pages( array(
    'sort_column'       => 'menu_order, post_title',
    'include'           => '',
    'exclude'           => '',
    'exclude_tree'      => '',
    'child_of'          => 0,
    'show_date'         => '',
    'date_format'       => get_option('date_format'),
    'title_li'          => __(''),
    /* 'title_li' set to '' for menus from the default 'Pages' */
    'authors'           => '',
    'echo'              => 1,
    'link_before'       => '',
    'link_after'        => '',
    'depth'             => 0,
    'walker'            => ''
    ) ); ?>
</ul>

Here is the break-down of the wp_list_pages() default options from above:

• 'sort_column' – not used
• 'include' – not used
• 'exclude' – not used
• 'exclude_tree' – not used
• 'child_of' – not used
• 'show_date' – not used
• 'date_format' – not used
• 'title_li' – not used, see below for additional notes
• 'authors' – not used
• 'echo' – similar to wp_nav_menu(); true versus 1 as value
• 'link_before' – same as wp_nav_menu()
• 'link_after' – same as wp_nav_menu()
• 'depth' – same as wp_nav_menu()
• 'walker' – same as wp_nav_menu()

Similar to wp_page_menu(), the ‘sort_column’, ‘include’, ‘exclude’, ‘exclude_tree’, and ‘child_of’ are replaced via the end-user’s specific choices. The ‘show_date’ and its related ‘date_format’ option, as well as the ‘author’ argument, are not available within the default wp_nav_menu() structure. Once again, the balance of the default options in wp_list_pages() matches the defaults found in wp_nav_menu().

Also consider setting the wp_nav_menu() fallback_cb option to 'fallback_cb' => 'wp_list_pages'. This backward compatibility may also be addressed with a custom function as posted by Nicolas Kuttler.

Note: If the 'title_li' => __('') option was being used it may also require the removal of the wrapping <ul> tag in the existing menu structure created with wp_list_pages().

Let’s start with an obvious example: a link from the blog title back to the home page.

<a href="http://wpfirstaid.com/">WP First Aid</a>

The above example is very, very basic … let’s dress it up a bit:

<h1 class="blog-title"><a href="http://wpfirstaid.com/" alt="Going Home: WP First Aid">WP First Aid</a></h1>

Now we have a title using the h1 element and a CSS class of blog-title with some alt text letting the reader know where the link will be going. This is better but how does this help you? Let’s make use of WordPress’ built in functions to make this example more generic and easily transferable.

<h1 class="blog-title"><a href="<?php bloginfo('url'); ?>" alt="Going Home: <?php bloginfo('name'); ?>"><?php bloginfo('name'); ?></a></h1>

This example makes use of the WordPress function bloginfo(). Here is a link to the WordPress codex for this function; and, here is a link to the get_bloginfo() function which provides additional details.

Our next example is adding a home page link to a navigation bar. Many navigation bars are generated with one of three WordPress functions: wp_list_pages(), wp_page_menu(), or wp_list_categories(). The wp_page_menu function uses a value that creates a home page link, for example:

<?php wp_page_menu('show_home=1'); ?>

The wp_page_menu function includes all the available parameters of the wp_list_pages function and also includes wrapping the output in an unordered list.

To add a home page link into a theme using the wp_list_pages function you may look at the following example for guidance:

<ul>
  <li><a href="<?php bloginfo('url'); ?>" alt="Going Home: <?php bloginfo('name'); ?>"><?php bloginfo('name'); ?></a></li>
  <?php wp_list_pages(); ?>
</ul>

Adding a home page link to a navigation menu created with the wp_list_categories function is very similar. Let’s take a quick look at it below.

<ul>
  <li><a href="<?php bloginfo('url'); ?>" alt="Going Home: <?php bloginfo('name'); ?>"><?php bloginfo('name'); ?></a></li>
  <?php wp_list_categories(); ?>
</ul>

The only difference in the above two examples are the function call. The links we added to the home page are almost identical to the the link example we used for the blog title.

Feel free to use any of the above examples in your own works. Of course, there could be additional CSS elements needed to work with your theme’s style but I will leave that as an exercise for you … or feel free to contact us with more complex code requirements.