I have written several posts regarding the use of the wp_nav_menu() function. I have written about its uses, its implementation, and even an older post regarding (some of) the CSS classes it generates. This post continues with an idea for extending the wp_nav_menu() function by adding additional items to the menu list with code versus the user interface found in the Administration Panels, such as automagically adding a self-propagating list of categories.

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:

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
NB: It is also important to realize that this function will work as is when a custom menu is being used, but you can easily adjust the above code to take into consideration common fallback functions such as wp_list_pages() and wp_page_menu().

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' );
NB: Note with this example the reference to the parameter ‘child_of=124′ … this is making use of some category hierarchical trickery; essentially you create a “phantom” category (note its ID to be used as the ‘child_of’ value) to be the parent of the categories you want to display in your list. If, for example, you want all your categories to be listed and you do not use the “uncategorized” category then simply make all of your current “parent” categories children of the “uncategorized” category and change the code above to use ‘child_of=1′.

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!