WordPress: List Categories next to their Descriptions

Listing Category names beside their Description is not something WordPress offers an easy solution to within the codex though it sounds easy enough. WordPress’ wp_list_categories will add the Description to the Category name link as a title tag replacing the default “View all posts filed under CategoryName”. Unfortunately we ran into this issue while building a client web site and after several hours of research into the matter and altering the core to suit our needs we at last discovered the beauty of get_categories.

The goal of this tutorial is to demonstrate the use of get_categories to echo both the category name and it’s description side by side. From the WordPress codex: ‘get_categories’ “returns an array of category objects matching the query parameters. Arguments are pretty much the same as wp_list_categories and can be passed as either array or in query syntax.”

We will be covering both the alteration of the WordPress classes.php file and demonstrate the get_categories function to achieve the desired results.

Classes.php Core Alteration:

This method is a little on the risky side as it can easily be deleted during a hasty WordPress upgrade and as such we do not recommend it. We are presenting this core alteration as a learning experience only.

Begin by locating the classes.php file within the wp-includes folder. At the time of this article we are using WordPress 2.9.2 so the line number may vary with a newer release but we are looking for the ’start_el’ function on line 1325:

function start_el(&$output, $category, $depth, $args) {
		extract($args);

		$cat_name = esc_attr( $category->name);
		$cat_name = apply_filters( 'list_cats', $cat_name, $category );
		$link = '<a href="' . get_category_link( $category->term_id ) . '" ';
		if ( $use_desc_for_title == 0 || empty($category->description) )
			$link .= 'title="' . sprintf(__( 'View all posts filed under %s' ), $cat_name) . '"';
		else
			$link .= 'title="' . esc_attr( strip_tags( apply_filters( 'category_description', $category->description, $category ) ) ) . '"';
		$link .= '>';
		$link .= $cat_name . '</a>';

In the function above we can see the “category_description” is placed within a ‘title’ tag of the link which begins on line 6. We want to alter this function to instead display the “category_description” within it’s own ‘div’ tag and not the ‘title’ tag. With a few alterations to the function it is possible to add additional code modifying it to display the description outside of the link. The example below is one of many ways to achieve this.

function start_el(&$output, $category, $depth, $args) {
		extract($args);

		$cat_name = esc_attr( $category->name);
		$cat_name = apply_filters( 'list_cats', $cat_name, $category );
		$link = '<a href="' . get_category_link( $category->term_id ) . '" ';
		if ( $use_desc_for_title == 0 || empty($category->description) )
			$link .= 'title="' . sprintf(__( 'View all posts filed under %s' ), $cat_name) . '">' .  $cat_name . '</a>';
		else
			$link .= '>' . $cat_name . '</a><div class="myClass">' . esc_attr( strip_tags( apply_filters( 'category_description', $category->description, $category ) ) ) . '</div>';

The example above allows for two potential outputs. The first output assumes that we have not included a Description for our Category and as such the result is exactly as WordPress intended. The Category name is echoed as a link and the ‘title’ tag’s output is “View all posts filed under CategoryName”. The second output relies on the fact that we have included a Description for our Category. In this situation the Category name is echoed as a link and below this is a ‘div’ tag with a class of “myClass” echoing the Description. Keep in mind this is not a necessary course of action as there is an easier and non core-altering option which will produce the same result.

Get_Category Function Alternative:

The easier and more desirable option, just shy of a plugin, is to use the following get_category function.

<ul class="myClass">
 <?php $categories = get_categories('number=10');
       foreach ($categories as $cat) {
       echo "<li><a href=\"" . get_category_link( $cat->term_id ) . "\">" . $cat->cat_name . "<div class=\"description\">". $cat->description ."</div></a></li>";
       } ?>
</ul>

Here we are calling on the first ten categories through the use of the ‘number’ parameter within the array and cycling through each of the Categories. We are then passing along the line item, link, category name, description and so forth providing a nearly identical output as wp_list_catgeories but with the twist of allowing for the option to echo the Description as text and not as a ‘title’ tag.

The WordPress codex provides a total of eleven parameters to use within the array including: ‘child_of’, ‘orderby’, ‘order’, ‘hide_empty’,include_last_update_time’, ‘hierarchical’, ‘exclude’, ‘include’, ‘number’ and ‘pad_counts’ for more information please refer to the function reference for get_categories.