Solving The WordPress Template Hierarchy Puzzle: Taxonomies

Josh Pollock - April 23, 2014

http://joshpress.net/blog/category/wordpress/tutorials/solving-the-wordpress-template-hierarchy-puzzle/http://joshpress.net/blog/category/wordpress/tutorials/solving-the-wordpress-template-hierarchy-puzzle/

Last week I wrote about how the WordPress template hierarchy works for custom post types, and this week I will be discussing taxonomies, including the built-in taxonomies, categories and tags. The template hierarchy is the system for determining what file in a WordPress theme is used for displaying which information. For more information about learning the template hierarchy, you should check out my post on learning the template hierarchy, which is full of great resources on the subject.

When reading the breakdowns of the hierarchy below, keep in mind the following:

  • The text int he brackets is replaced. IE For category-{category-id}.php you replace {category-id} with the id of a category.
  • Reading left to right, the first file that exists in a theme will be used.

Templates For Categories

The template hierarchy for categories is as follows:

category-{category-slug}.php -> category-{category-id}.php -> category.php -> archive.php -> index.php

You substitute just the slug for {category-slug} or just the id for {category-id}. So for a category with the slug ‘star-wars’ with the ID of 7 you would use ‘category-star-wars.php’ or ‘category-7.php’. Note that if you had both of these files in your theme, category-star-wars.php would be used not ‘category-7.php’.

Category templates are treated as archives, so if no category template is found, the archive.php template is used. If no ‘archive.php’ template is found, than ‘index.php’ will be used.

While it may be easier to keep track of templates name with slugs, naming with IDs ensures better future-compatibility, as category slugs can be easily changed. For that reason, I recommend naming templates with IDs and putting the category name and slug in a comment at the top of the file. In order to easily find the category ID, install the Simply Show IDs plugin. Once it is installed you will see the ID on the categories admin page.

Templates For Tags

The template hierarchy for tags is as follows:

tag-{tag-slug}.php -> tag-{tag-id}.php -> tag.php -> archive.php -> index.php

This is the same as for categories, with tag, instead of category as the prefix. Again, slug overrides, ID and ‘archive.php’ followed by ‘index.php’ are used as fallbacks.

Templates For Custom Taxonomies

The template hierarchy for custom taxonomies is as follows:

taxonomy-{taxonomy-name}-{taxonomy-term-slug}.php -> taxonomy-{taxonomy-name}.php -> taxonomy.php -> archive.php -> index.php

For custom taxonomies you can create a custom template for each term in the taxonomy and for all terms in the taxonomy, if no term specific template exists. You can also use taxonomy.php for all custom taxonomies without taxonomy or taxonomy term specific templates. If none of these files exist, WordPress falls back to ‘archive.php’, followed by ‘index.php’.

To illustrate imagine you have a custom taxonomy called ‘jedi’ and two terms ‘light’ and ‘dark’ and add two templates, ‘taxonomy-jedi-dark.php’ and ‘taxonomy-jedi.php’. The term ‘dark’ will be displayed using ‘taxonomy-jedi-dark.php’ and the term ‘light’ will be displayed using taxonomy-jedi.php.

If you added second custom taxonomy called ‘planets’ than neither of these templates would be used to display it and instead, WordPress would fall back to ‘taxonomy.php’, ‘archive.php’ or ‘index.php’, in that order.

Keep in mind that the taxonomy name is almost always different than the label you see in the WordPress admin. A good trick to find the proper name for your custom taxonomies is to do this in the console:

$taxonomies=get_taxonomies('','names');
foreach ($taxonomies as $taxonomy ) {
echo $taxonomy;
}

Using Conditional Tags Instead Of Separate Templates

If you only need to make a small change or two to your archive.php file, for a when its being used for a taxonomy, or to adjust ‘taxonomy.php’, ‘category.php’ or ‘tag.php’ for a specific term, it might be better to use a conditional function instead of creating a new template file.

You can check if a any category is being displayed using is_category() or you can check for a specific category by using its slug or id as the parameter for the function. For example, is_category() will return true for any category, while is_category('jedi') will return true only for the jedi category. You can check for two or more categories using an array, like this: is_category( array( 'jedi', 'planet'))

Tags have a similar function is_tag(), which works the same way. You can check for any tag, a specific tag or many tags the same way as with is_category().

For custom taxonomies the equivalent function is is_tax(). This function has two optional parameters, one for taxonomy and one for term. This means that is_tax() will return true when any custom taxonomy is being displayed, while is_tax( 'jedi' ) will only return true if the ‘jedi’ taxonomy is currently being displayed and is_tax( 'jedi', 'old-republic-era' ) will return true if the term ‘old-republic-era’ in the ‘jedi’ taxonomy is being returned.