Accessing the current category, tag, or term
The WordPress template hierarchy defines a number of templates that can be used to display archived posts which are attached to specific taxonomy terms in your WordPress site:
- category.php, category-$slug.php, category-$id.php – a single category term from the category taxonomy
- tag.php, tag-$slug.php, tag-$id.php – a single tag term from the post_tag taxonomy
- taxonomy.php, taxonomy-$taxonomy.php, taxonomy-$taxonomy-$term.php – a single term from a custom taxonomy
Simpler themes might not use these templates at all, instead falling back to archive.php or index.php to display correct the loop of posts based on the state of the active query.
In all of these cases the active query contains a current taxonomy term, noting that specific categories and post tags are just more specialised kinds of taxonomy terms. The MasterPress API has a whole host of methods to access the current term being displayed in archive templates, and all of these methods return a single WOOF_Term object.
First, let’s look at accessing the current category using the WOOF::the_category method:
Example 1: Accessing the current category
For even more concise code, the method WOOF::category, which can return a specific category, will return the current category if no arguments are provided:Example 2: The most concise way to access the current category
Now let’s look at a couple of ways to access the current post tag. We have the choice of a couple of methods WOOF::the_tag and WOOF::tag, just like we did for accessing the current category:
Example 3: Accessing the current post tag
As you can see, the code for this is consistent with accessing a category.
Now let’s look at the more general case of accessing the active term from any taxonomy. If you’ve followed along, you may have already guessed that we can use either of two methods WOOF::the_term or WOOF::term:
Example 4: Code for a custom taxonomy, perhaps in a taxonomy-ingredient.php template
How to check if there is an active term
The examples above have all made the assumption that there absolutely, positively is an active taxonomy term. This is generally fine for category, tag, and taxonomy templates, since WordPress wouldn’t redirect to those templates if there wasn’t one. If your theme only uses archive.php, or index.php, thereby relying on the active query, you may need to check for an active term. There’s a few ways to do this, firstly the more traditional way:
Example 5: Checking for active terms using template tags
… or we can make use of the fact that the methods which return our active term will return a WOOF_Silent object when there is no active term, which can be tested for with the exists method:
Example 6: Checking for an active term with the exists method
We can further simplify this code by taking advantage of quick-assignment:
Example 7: Checking for existence with quick assignment
More advanced use-cases
Note that the examples presented thus far are very simple uses of the term object returned, but WOOF_Term is a very rich class so you can do a lot more with this. For instance, you could access child terms, parent terms, and collections of posts under the current term. You can even access custom content fields setup for your terms, since MasterPress allows you to setup custom field sets for taxonomies. This can be really powerful – we might use a to display a custom banner for a certain category for example:
Example 8: Displaying a banner custom field for a certain category
The code above is remarkably intuitive and very easy to setup, especially compared to the heavy-lifting you’d probably need to do without MasterPress.
The current taxonomy
In templates with an active term, we also have the notion of an active post taxonomy. WOOF provides easy access to this object via the WOOF::the_taxonomy method:
Example 9: Accessing the current taxonomy
It’s important to note that this returns a WOOF_Taxonomy object, and not just the name of the taxonomy. You can access the taxonomy name via the name property as shown in this example.
For ultimate brevity, the WOOF::taxonomy method, which can be used to retrieve a specific taxonomy object, will return the current taxonomy if no arguments are provided: