Dynamic category menu highlighting for single posts

Gosh! That’s a mouthful, isn’t it, but what does it mean? Quite simple, really. In this tutorial we’re talking about how to dynamically highlight the relevant category menu item when viewing a single post which belongs to that category. Look at my menu bars and you should see that Code Snippets is highlighted – which is pretty cool given that you are browsing a single post.

The following assumes that (a) your theme has a category navigation menu bar or similar, and (b) this menu is generated by the WordPress wp_list_categories() function.

Before we begin I have to confess that I didn’t come up with this code all by myself. The code that we will use is derived from this www.designshard.com article, but has been tweaked by me to make it even more useful for day-to-day use. The problem with the method outlined in that article, and the Show Category Archive plugin that is referenced therein, is that those methods add a CSS class to the menu <a> tag, whereas the commonly used menu function wp_list_categories adds dynamic “menu state” classes to the links’ li tag. It seems much more useful to try to fit in with what WordPress is already doing, rather than create something outside that structure.

Anatomy of a wp_list_categories menu

By all means, be my guest and dig into the wp_list_categories source code to see exactly how wp_list_categories works. But let’s not get too technical, and look at a simple example instead. Here’s the example menu code from a typical theme’s header.php template file:

<div id="subnavbar">
	<ul id="subnav">
		<?php wp_list_categories('orderby=name&title_li=&depth=4'); ?>
	</ul>
</div>

If we view the Page Source of a page other than a Category archive page, this is the markup that this code generates:

<div id="subnavbar">
	<ul id="subnav">
		<li class="cat-item cat-item-1"><a href="url to fruit category page" title="View all posts filed under Fruit">Fruit</a></li>
		<li class="cat-item cat-item-2"><a href="url to veg category page" title="veg category desc">Vegetables</a></li>
		<li class="cat-item cat-item-3"><a href="url to dogs category page" title="dogs category desc">Dogs</a></li>
		<li class="cat-item cat-item-4"><a href="url to penguin category page" title="penguin category desc">Penguins</a></li>
	</ul>
</div>

Putting aside the diverse range of topics handled by this category menu, you will notice that the function automatically outputs 4 pieces of code for each category:

• cat-item – a CSS class added to the li tag of every category in the menu.
• cat-item-x – a CSS class added to each li tag, where X is the category ID number. Very useful if you want to style individual menu items differently.
• A link to the relevant category archive page (not shown in the above example, in order to keep things simple).
• A title attribute for each link. Notice that this is pulled from the Category Description, assuming one exists, and if it doesn’t, automatically adds “View all posts filed under (category name)” to the link’s title attribute.

If we were to click on the Fruit category link and look at the Page Source of this page, this is what we will see (simplified for clarity):

<div id="subnavbar">
	<ul id="subnav">
		<li class="cat-item cat-item-1 current-cat">...link stuff...</li>
		<li class="cat-item cat-item-2">...link stuff...</li>
		<li class="cat-item cat-item-3">...link stuff...</li>
		<li class="cat-item cat-item-4">...link stuff...</li>
	</ul>
</div>

As you can see, wp_list_categories has added a CSS class of current-cat to the li tag of the Fruit category. By adding a suitable CSS style to the stylesheet to target current-cat, it’s easy to highlight the menu item when viewing any category archive page.

However, as soon as you click on a Post title, this highlighting is lost. This is because wp_list_categories relies on the category query variable, sent to the server when a category link is clicked, in order to know which category li tag to add the current-cat to. When viewing a single post, this query variable is not available to wp_list_categories, therefore the current-cat disappears from the generated markup.

The challenge

In order to get around this problem, we need to find a way to preserve the current-cat class in the relevant category. Happily, thanks to WordPress filters, this is easy to do (yes, there is a wp_list_categories filter), so all we need do now is come up with a suitable function for this filter, which needs to do the following:

• Find out which post is being requested
• Determine which categories are assigned to this post
• Add current-cat to the li tags of these categories (as posts could be assigned to more than one category)
• Return the result of the above back to WordPress so that it can continue generating the page to be viewed.

The function

Here it is:

function sgr_show_current_cat_on_single($output) {

	global $post;

	if( is_single() ) {

		$categories = wp_get_post_categories($post->ID);

		foreach( $categories as $catid ) {
			$cat = get_category($catid);
			// Find cat-item-ID in the string
			if(preg_match('#cat-item-' . $cat->cat_ID . '#', $output)) {
				$output = str_replace('cat-item-'.$cat->cat_ID, 'cat-item-'.$cat->cat_ID . ' current-cat', $output);
			}
		}

	}
	return $output;
}

Let’s take a closer look…

• Line 1: Remember – Filters are a way of adding additional processing into the normal data processing flow of WordPress. Therefore, there will be something coming in to our filter function (the $output argument), which is then processed by our function, and then is returned back to WordPress when we’re finished (see line 18). In this case, $output will be the normal output of wp_list_categories being, essentially, the markup shown in the first block of code above.
• Line 3: We need access to the $post variable so that the function knows which post is being called.
• Line 5: This check using Conditional Tags ensures that our function only does something when a single post is being called. That’s something to remember with Filters – only process what actually needs to be processed. On every other type of page, such as when generating a category archive page, we don’t want our filter function to affect the normal output of wp_list_categories, hence this check.
• Line 7: Now that we have access to the $post variable, we can use the wp_get_post_categories() function to generate an object containing database details of all categories assigned to the post.
• Line 9: We now use a foreach loop to loop through each category found.
• Line 10: Using the get_category() function we get access to the data specific to the category being looped through. Specifically, we want to get hold of the category ID number.
• Line 12: We now use a PHP function preg_match() to search for “cat-item-1” (for example) within the li tags contained in $output (the markup generated by wp_list_categories and which we’re processing).
• Line 13: If line 12 finds a match, we then use another PHP function, str_replace(), to replace “cat-item-1” with “cat-item 1 current-cat”. Hey Presto! We’ve now done the important bit – added current-cat to the li tags belonging to the categories the post has been assigned to.
• Line 18: Finally, we pass our modified $output back to the wp_list_categories function, for final processing by WordPress and the rendering of the page markup.

Add this function to your theme’s functions.php file.

Adding the Filter

Now that we have our function, we need to tell WordPress to use it by adding the necessary Filter, again in functions.php:

add_filter('wp_list_categories', 'sgr_show_current_cat_on_single');

Adding CSS styles

The final step is to add a suitable CSS style to the theme’s style.css. Each theme will be different, so you may need to experiment with different selectors in order to find the right one.

Taking our example markup as a starting point, something like this should work:

#subnav li.current-cat a { ...put your styles here...}

As mentioned, depending on the structure of your theme’s markup, you may need to experiment a little to get the selector right. The Firebug add-on for Firefox is an excellent tool to help you do this.