A taxonomy is a way to organize content. You’ve probably used two taxonomies before: categories and tags. WordPress allows you to create as many as you’d like to organize your content in whatever ways make sense to you.
I often use taxonomies when I’m creating custom post types. Categories and tags make sense for posts, but when you make a new content type you might also need to create new ways of organizing that content.
My Code Snippets post type uses a “Code Tag” taxonomy for organizing content. You can see all code snippets relating to my Display Posts Shortcode plugin here.
Creating Custom Taxonomies
In your core functionality plugin, you can create a new taxonomy using the register_taxonomy() function. Here’s an example of registering a “color” taxonomy for posts:
| <?php | |
| $labels = array( | |
| 'name' => 'Color', | |
| 'singular_name' => 'Color', | |
| 'search_items' => 'Search Colors', | |
| 'popular_items' => 'Popular Colors', | |
| 'all_items' => 'All Colors', | |
| 'parent_item' => 'Parent Color', | |
| 'parent_item_colon' => 'Parent Color:', | |
| 'edit_item' => 'Edit Color', | |
| 'update_item' => 'Update Color', | |
| 'add_new_item' => 'Add New Color', | |
| 'new_item_name' => 'New Color', | |
| 'separate_items_with_commas' => 'Separate Colors with commas', | |
| 'add_or_remove_items' => 'Add or remove Colors', | |
| 'choose_from_most_used' => 'Choose from most used Colors', | |
| 'menu_name' => 'Colors', | |
| ); | |
| $args = array( | |
| 'labels' => $labels, | |
| 'public' => true, | |
| 'show_in_nav_menus' => true, | |
| 'show_ui' => true, | |
| 'show_tagcloud' => false, | |
| 'hierarchical' => false, | |
| 'rewrite' => array( 'slug' => 'color', 'with_front' => false ), | |
| 'query_var' => true, | |
| 'show_admin_column' => false, | |
| // 'meta_box_cb' => false, | |
| ); | |
| register_taxonomy( 'color', array( 'post' ), $args ); |
Labels
The labels parameter lets you customize all the labels used throughout the WordPress backend. It’s usually as simple as find/replacing the plural and singular forms of the taxonomy, but you may want to tweak some of the other labels more extensively.
Hierarchical
If 'hierarchical' => true, it will have a hierarchical structure like Categories. If 'hierarchical' => false, it will be non-hierarchical like Tags.
Rewrite
The rewrite parameter lets you enable and customize the URL rewriting for this content type.
Show Admin Column
If 'show_admin_column' => true, the taxonomy will be included on the Edit Posts screen.
Metabox Callback
If 'meta_box_cb' => false, no metabox appears for managing the taxonomy on the Edit Post screen. This is useful if you create a custom metabox that includes taxonomy management.
Displaying Custom Taxonomies
Once you’ve created your taxonomy and added some terms, you’ll want to display the terms attached to a post. You can use the function the_terms().
the_terms( get_the_ID(), 'color', 'colors: ', ', ' );
The first argument is for the post ID, the second for the taxonomy name, the third for what’s displayed before the listing, the fourth shows the separator to use if there’s multiple terms (I’m separating with commas), and the last argument is for what’s displayed after the listing.
Sorting by Taxonomy
You can customize the main query or create custom queries that leverage your taxonomies using tax_query.
For instance, to get the 10 most recent posts with the color “blue”:
| <?php | |
| $loop = new WP_Query( array( | |
| 'posts_per_page' => 10, | |
| 'tax_query' => array( | |
| array( | |
| 'taxonomy' => 'color', | |
| 'field' => 'slug', | |
| 'terms' => array( 'blue' ), | |
| ) | |
| ) | |
| ) ); |
Christine Green says
Bill,
Very informative post. And I have to say, the display, organization and detail of your portfolio is fabulous! It’s the best I’ve seen for any web designer. Bravo!
Joshua says
Bill,
I’ve created a custom post type, with two taxonomies related to it (Post Type “License” and taxonomies “State” and “Job” – essentially, jobs that require licenses in specific states). I’ve installed the Custom Permalinks Plugin to alter the permalink structure of the taxonomy pages so that license pages show up as site.com/state/job/ instead of site.com/license/. I’m going to eventually link the taxonomy pages to pods data, but that isn’t a big deal just yet.
My problem is that I can create a state-specific taxonomy page using the thesis custom loop for archive() (or taxonomy(), both work similarly) but it doesn’t appear to work for the job taxonomy, only the state taxonomy. For instance, site.com/washington and site.com/washington/carpenter show the same state information page, rather than two different sets of information (and site.com/carpenter doesn’t work at all). I’d like to have site.com/state show custom info separate from the site.com/state/job or the site.com/job/
My question is, how do I discern between two taxonomies like this? I’d like to have a page for the state, a page for the job, and a page for /state/job/ all built on-the-fly with the custom loop and taxonomy archive. Ultimately, the site is about the licenses for a job in a state, but having the other pages will help create broader pages with information about the job or state in general.
Hoping you can help!
Thanks,
Joshua
Bill Erickson says
This is actually a really complicated issue and beyond the scope of this tutorial. I’m planning to publish another post on this exact subject once my client’s site is live, but I’ll email you directly with some helpful info.
Steven Querry says
Thanks for all the valuable information Bill. If I could ask one question, how did you get the “Featured Image” to display above your custom taxonomies? I added two taxonomies and they are both sitting above the featured image. I looked for some type of menu_position in the plugin advance options, but don’t see anything.
Thank you!
Bill Erickson says
This just depends how your theme file is constructed. I’m simply calling the_post_thumbnail() before I call the_terms()
micharo says
Thank you so much for your tutorial
I added two custom post types and one taxonomy. The taxonomy is assigned to both custom post type.
When I add a tag in the custom post type edit screen and hit the update button it removes the tag. But the quick edit works. Any ideas?
Bill Erickson says
It sounds like an issue with a plugin you have installed. There’s nothing in WordPress core that would prevent you from adding taxonomy terms to a registered taxonomy.
micharo says
Thanks for the reply!
The problem was connected with the
Custom-Metaboxes-and-Fields-for-WordPress
in particular with the “taxonomy_multicheck” – type.
If I use that type then the update of the custom post removes the assigned tags, but when I comment out that metabox field the update function works.
Bill Erickson says
If you’re using any of the taxonomy fields in CMB, you need to set ‘public’ => false when registering the taxonomy. Both the taxonomy box and your custom metabox will update the taxonomy.
The custom metabox runs second, so whatever you had selected in the taxonomy box will be overwritten.
Jamie says
Hi Bill
hope all is well
ok, so before commenting here i have searched far and wide both on google and github but just can’t find the answer.
I have a CPT and custom taxonomy (as tags)
when viewing the CPT archive, it shows ALL post
when viewing a CPT by tag, it shows all posts from that tag
ok, so how can i show all these archives as a unordered list (titles only) instead of the entire post?
looking at your code snippets section it seems you have done exactly that!
thanks in advance.
Jamie says
Hi Bill
just after posting the comment above it kinda hit me, and i worked it out 🙂
https://gist.github.com/jamiemitchell/24b9fe3830d091291615
Cathy Tibbles says
I read through the wp docs on admin columns but I can’t figure out how to add custom tax to the admin columns on a CPT. Do you have a tutorial on that already?
Bill Erickson says
When you are registering the taxonomy (
register_taxonomy()) include'show_admin_column' => true.In the example at the top of the post it is set to
falseso there’s no admin column added.