A Guide to WordPress Custom Taxonomy

By John Gadbois

Advertisement

In this guide, we will cover an incredibly great feature of WordPress: Custom taxonomy. Custom WordPress taxonomies give you unprecedented power in the way you can categorize and relate your WordPress content with each other. Though WordPress taxonomies were introduced in WordPress 2.3, it has been revamped in WordPress 3.0 for WordPress developers.

Recently, we had looked at creating custom WordPress post types in the WordPress custom posts guide, and to further our command of WordPress 3.0 site and theme development, we’re going to now discuss custom taxonomies.

What is Taxonomy in WordPress?

Taxonomy is simply a way of organizing data and, in the WordPress world, a taxonomy is a way of organizing and tying your site content together.

Even though you don’t realize it, you’re probably already very familiar with at least one of the built-in WordPress taxonomies: WordPress tags. Tags are a taxonomy because posts can be linked to tags, viewed by tag, and organized by tags. Another WordPress taxonomy are post categories.

Taxonomies add a lot of power to WordPress because they allow users to filter the information they want to see on your site.

A custom taxonomy is exactly what it sounds like — a custom way to relate disparate content together. Custom taxonomies can be applied to custom post types or to regular pages and posts.

Here are some things you might use custom taxonomies for:

Release Year for movies

Urgency like High Priority, Low Priority for service bulletins

Location like room name, zip code or state for events

Each of these taxonomies could help to organize information stored in a WordPress site. If you read the custom post types guide, than the last example (events) on that list will be familiar.

The Game Plan

We’re going to build on the Event custom post type we produced in the WordPress custom post types guide by creating a custom taxonomy for it called Location. The Location taxonomy will allow us to organize our events by their location.

Before we begin, a couple of caveats.

First, for the purposes of this guide, we’ll be using the default TwentyTen theme that comes with WordPress 3 so that we all have the same base theme. However, these instructions can be adapted quite easily for using your own theme.

We’ll also be assuming that you followed along the custom post types guide and that you already have the custom Event post type created.

OK, with that said, let’s get started!

Creating a Custom Taxonomy

As with custom post types, WordPress makes it pretty simple to create your own custom taxonomy.

Let’s take a look at the code required to create the Location custom taxonomy:

The above code should go in the functions.php file inside your theme’s directory. The register_taxonomy WordPress function is what actually creates the taxonomy, so let’s start by looking at a couple of the arguments that we passed to it.

'location' is the internal name of our taxonomy.

'event' tells WordPress what post types will use this taxonomy. In our case, we’re tying it to our custom Event post type. You could replace this with 'post' or 'page' if you wanted to use your taxonomy on your posts and pages. You could also pass in multiple post types (via an array) so that multiple types of content can use the taxonomy.

array(...) is the last argument to register_taxonomy. It’s a PHP array of options that tells WordPress how this taxonomy will work.

Let’s go over the keys inside the array argument.

'hierarchical' is a boolean key that states whether or not the taxonomy has a hierarchy, i.e., whether the taxonomy has child categories or not. For our Location taxonomy, we are going to have a hierarchy. For example, think: Building 1, Conference Room A. There may be several Conference Room A’s, but since its parent is Building 1, then we are able to give our location greater specificity.

'labels' is simply information about the way the taxonomy information is going to be printed (as specified by the $labels array inside the create_locations function).

Also notice that the register_taxonomy call is inside a function called create_locations. This is a custom function of ours (it can be named anything you want) that is called when WordPress initializes add_action( 'init', 'create_locations' ).

Still with me? I know it’s a lot, but let’s keep moving forward and soon it will all come together.

Adding Your Custom Taxonomy to Posts

OK, now that we’ve created the Location taxonomy, let’s log into WordPress and create some locations that we can use with our events.

If you look under the Events menu (on the left-hand side of the administration screen), you can see there is a new link called "Locations". Clicking on it will bring you to a screen where you can add, edit, and remove locations from the system.

Create the following locations:

Building 1

Conference Room A

Conference Room B

Once you do, you should see your new locations in the Location table (right next to the Add Location interface).

Now that we have some locations, let’s add them to an Event post! Head over the Add New Event screen (or edit an existing event), and you should see a new Locations widget on the right-hand side. This widget appears because when we created the taxonomy, we told WordPress to associate it with the Event custom post type.

Check off Conference Room A and then publish or save the event. Notice that you can add new locations right from this screen if you find that there’s one missing. This whole display should be familiar to you as it works exactly like WordPress post categories. If you make a non-hierarchical taxonomy, then it will behave exactly like post tags.

Now that we’ve created some locations and used one of them to an Event post, we want to display each event’s location on the front-end of the site so that our readers can see them. Let’s do that next.

Displaying Your Taxonomy Information

The first place we want to show the location is when we are displaying a single event.

If you remember back in the previous custom post types guide, we created a file called single-event.php in our theme directory that was used to display an individual event. If you were doing a custom taxonomy on a default content type (i.e. posts or pages), then you can do the same thing, but only you’d need to do it in single.php.

When we visited an event, it looked like this:

We can add the location (or locations) to the post using WordPress’s get_the_term_list function, which looks like this:

get_the_term_list( $id, $taxonomy, $before, $sep, $after )

Here are brief descriptions of each get_the_term_list argument:

$id – the ID of the event to get the taxonomy for

$taxonomy – what taxonomy to get ('tag', 'location', etc.)

$before – The HTML to print before the list

$sep – what should separate the various items in the list

$after – The HTML to print after the list

We can use the get_the_term_list function to display all locations assigned to an event using the following code block:

Now if we refresh the event’s page in our browser, we can now see the location assigned to it:

Filtering Posts by Custom Taxonomy

Now that we’re displaying our Location taxonomy in our events pages, we need to configure a page template to show all the events for a given location.

As noted previously, the "Conference Room A" link will automatically take you to a page that displays all the posts with the given location (which is pretty useful for when you want to know what other events will be happening in "Conference Room A").

But since we’re tying our taxonomy to a custom event type, we’ll need to get our hands a little dirty and make some modifications.

If we follow the link as-is, we’ll see the following:

To understand what’s going on, we need to know a little about WordPress’s template hierarchy. Whenever a page is loaded in WordPress, it looks in your theme for the correct template to load based on a specified naming convention. When a taxonomy page is encountered by the user, the sequence in which WordPress checks what WordPress theme page template to use is this: taxonomy-[your_taxonomy_term].php > taxonomy-taxonomy.php > taxonomy.php > archive.php > index.php.

What this means is that, going left to right, WordPress will use the first file it encounters that matches the naming convention. In the TwentyTen WordPress theme, the first file that is a match is archive.php since the first three files are non-existent. That explains why we saw the "Blog Archives" heading in the page.

To display our locations, we’re going to add a file called taxonomy-location.php.

Since this is higher in the page template hierarchy (i.e., it’s taxonomy-[taxonomy-term].php from above), WordPress will load this file instead of archive.php when a user hits the location taxonomy page.

So to get started, create taxonomy-location.php in your theme’s directory and copy the contents of tag.php into it so that we have a starting point.

The first thing we need to do is get the location that we are currently viewing (like "Conference Room A").

WordPress terminology calls this the term of the current custom taxonomy. To get the terms of an event post, add the following line right below the get_header() line.

query_posts will override the default WordPress loop and replace it with a custom one that finds all Events with the current location.

Due to a bug in WordPress (at the moment), any other post types that are at the current location will also be returned. This is not a problem for us right now, but is something to keep in mind in the future as you work with custom taxonomies.

Once we’ve added the query_post call, here’s what we see:

As you can see, we’re now showing all of our "Conference Room A" events (we only have one), awesome!

If you noticed, when originally creating the locations, you can optionally specify a location description. How would we add that to our template? That’s pretty easy. Just add the following line right under the closing h1 tag in taxonomy-location.php.

Related Content

About the Author

John Gadbois is a 27-year-old web developer who codes and runs Domain Superstar, a domain name tools site. He also works on the online calculator site, CalculatorPro.com and enjoys working with WordPress, PHP, jQuery, and Ruby on Rails.

– Maybe it was just me but I found WP’s support for taxonomies a bit overstated. Mainly the built in functions seem to be pretty limited in capabilities and parameters. To get what I needed I had to do some homegrown hacking.

– The biz need I had to satisfy was closer to uber-tags than taxonomy buckets. From this project I developed a couple custom functions that make it easier to work with taxonomies. I don’t mean to link-drop but for anyone who might be interested I’ve shared those functions at:

Excellent post. I wish I would have known more about this earlier, I could have really used it to organize my site. It might be a lot of work to go back and do it now but on all my upcoming sites I’m going to make use of this technique. Thanks!

It could potentially be used for a glossary, but I think you’d have to manually assign the glossary terms for each post. Then you could have a page that listed all your glossary terms and the posts that were tied to that term.

I am following your article here and keep running into the same issue. I can create a custom taxonomy with no issue, I can display the taxonomy on the post with no issue. However when I click on the taxonomy I get a 404 page. Regardless if I create a taxonomy.php page.

My custom taxonomy is Products with a term of Photoshop. I have tired creating a taxonomy-products.php and taxonomy-products-photoshop.php page and I still always get a 404 page. The url looks like http://communite/products/photoshop Any suggestions???

I have run into one issue with custom taxonomies though and that is pagination. I can set the number of posts to display when listing objects of a custom taxonomy, but going to page 2 of the results always gives a 404.

hello
iam using custom taxonomies in my site,so i did have seperate templates for displaying them.
i have created a taxonomy called people and a term called star and also respective template to star (taxonomy-people-star.php) every thing works fine http://sportsstatus.in/dev/people/star/ .
but when i query some other taxonomy like http://sportsstatus.in/dev/people/star/?sports=tennis to it the template structure changes to the archive format. how to over this.
i want the original template structure assigned for star(taxonomy-people-star.php) to work.

Great article. I’ve added a custom taxonomy to my project and it works well but I have a problem. As soon as I activate permalinks, the links created with this code /location/name_of_the_location/ :
echo get_the_term_list( get_the_ID(), ‘location’, “Location: ” )
aren’t working anymore.

I used this guide to build my custom taxonomies and everything seems to work great except one thing. This may be something to do with the template I am using, but I am clueless at this point.

I copied the code from my archive.php file and pasted it into a new file called taxonomy.php, which builds an archive of posts from the taxonomies I have defined. I added a post-thumbnail and prettier formatting that my standard archive.php file. My problem is, that I cannot change the length of the_excerpt that it displays on the taxonomy.php page. I have tried adding custom functions to my functions.php file to control it and almost every plugin available and nothing will change it. I need it trimmed on my taxonomy archive page, but display a full excerpt on the single post page.

I have to get it to work as described above. I can’t paste the full text into the_content, because it totally ruins my formatting.

Great tutorials.
I’ve created several content types but I’m come across a problem. I have a hierarchal custom taxonomy which I called “country” and then using this assign my posts related to whatever country name they are associated with.

In my case I would be using the same taxonomy for multiple content types. Now when I call up an archive page or single for a custom post type and use e.g. get_the_term_list it will show the country name, but when clicking on it, it shows posts of other content types as well (that have the associated taxonomy).

How do I limit the taxonomy to that particular content type for users when browsing but still have the flexibility to use it across content types when posting content?

You mentioned a WordPress bug at the very end of your article. Just wondering if it’s what is affecting my simple taxonomy search menu.

I registered two taxonomies to work with ordinary posts. I can assign them correctly in the combo box. I’m using a taxonomy search widget, which is generating a good URL. In my results page I get every post, as opposed to just the posts tagged with the taxonomy value in question.

Thanks for explaining that. My question is about showing multiple taxonomies in a post, but only the taxonomies that have a value.

For example, on a portfolio site, if there are taxonomies for “Writer” “Illustrator” “Designer”, I want to return only the taxonomies that I have given values to. I could hard code a line of code for each taxonomy, but I do not want any blank fields returned.

You just need to do a “functions flush”. Go to WP Admin > Settings > Permalinks and simply click “Save changes”. You don;t need to change anything; it just flushes the system. Your taxonomies will appear like magic.

Thanks for an incredible useful tutorial.
I’ve tried to wrap my head around custom taxonomies and this guide has been the revelation for me.
One small suggestion, maybe make it even clearer that you need the code from the “WordPress custom post types guide” – although it just might be me who is a bit slow :)

trying to get this to work on another custom template that i downloaded and can’t get it to drill down and some other display things that i can’t seem to figure out how to fix. would anyone be able to help me out ???

Is there any way to create a page where all the taxonomies are listed? If I , for example, have 5 different taxonomies. Actors, Genre, Atmosphere etc. and I’d like to have some pages where my readers can chose a term, eg. ChickFlick or something like that?

Because I’m lazy enough to admit that I don’t want to add all the terms manually.

Very helpful. I guess one key difference between taxonomies and categories is that a post can quite reasonably have multiple categories, whereas it’s best than a post just has one place in your taxonomy.

I was trying to build a Yellow Page function and didn’t really get it right using custom post types only. I found your article about custom post types and found out that I actually did the right thing, but adding the taxonomi function right got me through.

So now I just need to add a function to show the taxonomy tree on the taxonomy page as well to get all the way.

Thank you for posting this, I always get stuck on the “Making stuff show up in the taxonomy listing pages” part of it. It really is stupid that WordPress can’t ascertain by itself what taxonomy is being requested — if the template hint being given is taxonomy-custom_taxonomy.php, it already knows the taxonomy being requested is called “custom_taxonomy” because it just loaded the file. Why one must override the loop in these situation dumbfounds me.