Justin Tadlock

Custom taxonomies in WordPress 2.8

Imagine you ran a website that reviewed books, movies, and music. When writing posts in WordPress, you want to label something as a book, yet you also want to further label it by genre or by author.

Traditionally, we’d come up with a way to use our categories and post tags to have some sort of classification system. I’m going to show you how you’ll be able to break free from this rigid system and do things your way.

In WordPress 2.3, the new taxonomy API was introduced. It allowed us to make up our own taxonomies. Here’s the problem: No one has been using custom taxonomies.

In WordPress 2.8, creating custom taxonomies won’t even be the job of a plugin developer. Average users can make and use any taxonomy they want with a few lines of code. WordPress will handle the rest by adding the meta boxes on the write post page and new admin menus for managing them.

What is a taxonomy?

I realize that word may be unfamiliar to many of you. In short, a taxonomy is a way to group items. Here’s the Answers.com definition of taxonomy:

  1. The classification of organisms in an ordered system that indicates natural relationships.
  2. The science, laws, or principles of classification; systematics.
  3. Division into ordered groups or categories.

The third definition is probably the best for our purposes.

By default, WordPress comes pre-loaded with three taxonomies: category, post_tag, and link_category. The first two allow us to label our posts a certain way. The last lets us categorize our links. I’ll be showing you how to easily create your own and use them in this tutorial.

Each taxonomy has what are called terms. For example, all of your tags are actually terms that live within the post_tag taxonomy.

What the new taxonomy features do

Once you’ve created your new taxonomy, WordPress will set up admin panels for you automatically. You’ll also get a new meta box when writing a post. This is the part that makes the new features in WordPress 2.8 so cool. We’re going to be setting up three taxonomies in this tutorial: people, places, and animals.

You’ll see this when you write a new post:

Custom taxonomies on the WordPress write post screen

Here’s the view of the admin panel for our people taxonomy (click image for larger view):

Edit taxonomy page in WordPress

Some of you might have noticed the word “tags” in a few places on the page. I’m not sure if this will be updated in the future or if it can be easily changed.

How to create a custom taxonomy

I’m only going to cover the basics here for average users. Plugin developers can take this and do all kinds of neat things. Also, the new features in WordPress 2.8 only apply to tag-like taxonomies (non-hierarchical) for posts.

In this example, we’ll be creating three custom taxonomies: people, places, and animals. You can create as many or as little as you want.

Open your theme’s functions.php file or create a plugin file to work with. Add this code:

<?php
add_action( 'init', 'create_my_taxonomies', 0 );

function create_my_taxonomies() {
    register_taxonomy( 'people', 'post', array( 'hierarchical' => false, 'label' => 'People', 'query_var' => true, 'rewrite' => true ) );
    register_taxonomy( 'places', 'post', array( 'hierarchical' => false, 'label' => 'Places', 'query_var' => true, 'rewrite' => true ) );
    register_taxonomy( 'animals', 'post', array( 'hierarchical' => false, 'label' => 'Animals', 'query_var' => true, 'rewrite' => true ) );
}

?>

Breaking down the code

Let’s look at one line of the code we started with and break down each part. The taxonomy we registered for people looks like this:

register_taxonomy( 'people', 'post', array( 'hierarchical' => false, 'label' => 'People', 'query_var' => true, 'rewrite' => true ) );

people tells WordPress what the name of the taxonomy is.

post tells WordPress what object type this taxonomy applies to. You could also make a taxonomy for pages or links if you wanted, but WordPress doesn’t do the cool stuff with anything but posts right now.

hierarchical means whether the taxonomy terms can be in a hierarchy (categories are hierarchical, tags are not). So, we set this to false to behave like tags and to use the new WordPress features.

label is the name of your taxonomy that you want to show up in things like the WordPress admin. (Note: This should be localized if you’re creating a plugin for public release.)

query_var lets WordPress know if you want to be able to query posts for things such as showing all posts in the people taxonomy about Will Smith. If you set it to true, the query variable will be the name of your taxonomy. This can also be any text string you want. We’ll keep ours at true for simplicity.

rewrite is whether you want WordPress to give you prettier permalinks when viewing a taxonomy page or archive. So, you could have something like yoursite.com/people/will-smith rather than yoursite.com/?people=will-smith.

Keep reading, and I’ll give you some practical usage examples.

How to create a tag cloud with your custom taxonomies

Let’s say you want a people cloud rather than a tag cloud. Well, we’d use our standard wp_tag_cloud() template tag with a few extra arguments. Place this code where you’d like to show your people cloud:

<?php wp_tag_cloud( array( 'taxonomy' => 'people', 'number' => 45 ) ); ?>

It’s as simple as that. All you need to do is set the taxonomy argument to the taxonomy of your choice.

How to list a taxonomy’s terms for each post

Maybe you want to show a particular taxonomy’s terms along with your post, which is common with categories and tags. In this example, we’ll show the terms from the people taxonomy. Add this within The Loop where you’d like it to show:

<?php echo get_the_term_list( $post->ID, 'people', 'People: ', ', ', '' ); ?>

How to show posts only from a specific taxonomy

Let’s suppose you wanted to create a custom page template or set your home page to show 10 posts with the term “Will Smith” (from your people taxonomy). Add this code before The Loop:

<?php query_posts( array( 'people' => 'will-smith', 'showposts' => 10 ) ); ?>

What? Did you think it would be tougher than that?

Create your own custom taxonomies

Taxonomies are no longer something that only plugin developers can create. It’s time for you to go out and explore custom taxonomies for yourself. Make something that is unique to your site.

I’m thinking of making a WordPress taxonomy for my blog since that’s pretty much all I blog about.

If you have questions or would like to see more practical usage examples, feel free to ask in the comments. It might even be cool to set up a big list of ideas for new taxonomies. There’s so much more we could do that I couldn’t cover in one tutorial. It might be worth writing another one if everyone feels we need it.

Remember, this tutorial is for WordPress 2.8, which is under development at the time of writing. Things could change by the time it’s released.