How To Display WordPress SubCategories: Descendant Function

August 7, 2009, Posted by Christopher at 12:50 pm

RELATED POST:
How To Display Subcategory Lists On Category Pages

We have already looked at how to display subcategory lists on the category pages … ( see this article ) … so in this article we are going to look at how to display subcategory lists anywhere in WordPress.

What Are We Doing ?
The standard WordPress “ in_category() ” call will only display the categories and subcategories that a post is directly assigned to. This is fine if you always assign your parent category, in addition to your selected subcategories, to your posts … but WordPress cannot determine ( using in_category ) the parent category of a post if you have assigned it ONLY to the parent’s subcategories. The problem is that if you want to display a subcategory list of the parent category that a post belongs to, then we obviously need to know what the parent category is.

There are certain design reasons for posting only to subcategories … doing this can reduce clutter on sites that have 3 or more category depths and certain WordPress plugins such as “related posts” programs may operate better or be more accurate.

Through the following method we are going to ask WordPress to look at the assigned subcategory, figure out what parent category that sub is under, and then post information based upon the parent category … not the subcategory. The following technique can be used to display subcategories of the current parent category in your sidebar, static pages, single post pages, and more.

Why Do We Need This ?
Here is a good example of where this would come in handy … let’s say you wanted to build a site that had the states of the US as parent categories and major cities as subcategories. The following method would allow you to list only the current state’s cities in the sidebar, so when you are viewing a California city post / listing you will not see Arizona and New York cities listed in the sidebar.

Visual Examples
I have used this in THREE locations on this page. First, click on the “New Posts In This Category” tab in the side bar. You will notice near the bottom of the box a listing for all of the subcategories that exist under the parent category of the story you are viewing. So for this article the subcategories shown will all be from the “technology” parent category. Second, in the top right corner of this post you will see a link ” The Technology & Programming Section ” that is also controlled by this. Finally, at the bottom of this post you will see a “Related Posts” section. The subcategory list in that section is also controlled by this.

Let’s Do It !

1 ) First, we need to ask WordPress to do something it is not used to doing. The following code will tell WordPress to read the subcategories of your particular post and determine the parent category … WHETHER OR NOT THE POST WAS SAVED DIRECTLY TO THE PARENT CATEGORY. This is very useful for people who post to the subcategories but may not add the post to the parent category above it.

This code needs to be added to a template, plugin, or theme functions file. I chose to add it to my theme functions file which is functions.php that resides in my current theme folder.

<?php
/**
* Tests if any of a post’s assigned categories are descendants of target categories
*
* @param mixed $cats The target categories. Integer ID or array of integer IDs
* @param mixed $_post The post
* @return bool True if at least 1 of the post’s categories is a descendant of any of the target categories
* @see get_term_by() You can get a category by name or slug, then pass ID to this function
* @uses get_term_children() Gets descendants of target category
* @uses in_category() Tests against descendant categories
* @version 2.7
*/
function post_is_in_descendant_category( $cats, $_post = null )
{
foreach ( (array) $cats as $cat ) {
// get_term_children() accepts integer ID only
$descendants = get_term_children( (int) $cat, ‘category’);
if ( $descendants && in_category( $descendants, $_post ) )
return true;
}
return false;
}
?>

If you decide to add this to your theme functions file … which is what I would suggest … you will ALMOST ALWAYS need to remove the <?php from the start of the code and the ?> from the end of the code or your functions file may not run properly. If the other code snippets in your functions file do not include the beginning and ending PHP lines then remove them from this code before pasting into your file.

2 ) Now we can use the ” post_is_in_descendant_category() “ call to pick-up the parent category of all posts assigned to subcategories under it. You can use this code anywhere in your theme pages … the side column, the footer, the single_post page, and so on. The example code I am going to show is the one that I used in the sidebar of this blog. That code is:

<?php if ( in_category( ‘3‘ ) || post_is_in_descendant_category( 3 ) ) { ?>
Visit the sub-categories in the Technology and Programming section:
<?php wp_list_categories(’child_of=3&style=list&title_li=’); ?> >>> <A href=”http://lohmantrading.com/Fourced/category/the-internet-wordpress-and-technology/”>See All Tech Articles</a>

<?php } elseif ( in_category( ‘5‘ ) || post_is_in_descendant_category( 5 ) ) { ?>
Visit the sub-categories in the Photography and Art section:
<?php wp_list_categories(’child_of=5&style=list&title_li=’); ?> >>> <A href=”http://lohmantrading.com/Fourced/category/art-and-photography/”>See All Photos and Art</a>

<?php } else { ?>
Something to display if not in above categories
<?php } ?>

To see what this output would look like, take a look at the Technology subcategory list created with this code in the “related posts” section right after my signature in this post. ( I added the code to my ” single.php “ file )

In plain English, the above code will do the following:

1. The “if” statement checks if the post you are viewing is directly in category 3 (my technology parent category) … OR … if the post is in a subcategory under that parent category. If it is, then it will display links to all of the subcategories under category 3. ( the “list_categories” statement )
2. If the post is not in category 3 or a subcategory beneath it then it goes to the next “if” statement and checks. In the above case it would be category 5.

You will need to modify the code for your particular blog. Make the following changes:

1. Change the category id numbers that are in blue. These need to be changed to the category id numbers of your parent or top-level categories.
2. The “child of” number in each statement determines which subcategory list to display. This should match the parent category number above it.
3. Everything in red manages what is actually displaied on your page if the statement is true. Modify it as you would like. Feel free to change the wording.
4. You need to make “elseif” statements for every parent category that you would like to include. If you have 10 parent categories then you should have 10 statements instead of just 2 as shown above.
5. The <?php wp_list_categories(’child_of=5&style=list&title_li=’); ?> tag is what actually displays the subcategories of the parent. You can change the display of this slightly … have a look at the WordPress Codex Page for the “list_categories” tag.

After you understand the above procedure you can actually do quite a few interesting things in addition to displaying subcategories. For example, you could display a unique sidebar image or a unique welcome message for each parent category. I used this to display the link to the master parent category in the top right corner of this post (I may add a graphic in the future).

As a side note, none of the posts in this blog are directly assigned to their respective parent categories. I have done this in an attempt to create more accuracy in navigation by reducing redundancy and clutter.

More info about the “in_category” tag an be found on the WordPress site.

Hopefully this article has been a help to those of us who are not “code” addicts. I like to pass-along tidbits of information that might allow non-programmers the ability to modify their own websites. Please keep in mind that I am not a professional programmer but I have been building and modifying websites since 1995 using HTML, cgi, perl, MIVA, PHP, and CSS. Suggestions on other ways to reach the desired goals above are always welcome … please consider leaving a comment !

Always remember to save copies of your original files BEFORE you modify them. This will allow you to easily revert your web site if the changes do not work.

Comments ( leave a comment here ) and thoughts ALWAYS welcome !