WordPress 4.4 introduced several new features for developers. The infrastructure for the WordPress REST API got the most attention by far, but there are some other notable new features that are worth a closer look.
One in particular is taxonomy term metadata. In this article, I will discuss what term meta is and how to use it.
The need for term meta is made apparent by the wide number of solutions that existed in the past to approximate this feature via various means. For example, Pods has supported custom fields for taxonomy terms for a long time. Previously, those custom fields were stored in a custom database table.
Now users have the option of using standard term meta or a custom table. The new default option of term meta is not only an embrace of “The WordPress way” it improves data portability, making it easier for users to use existing data in Pods or to migrate away from Pods.
What Is Term Meta?
WordPress posts and users have had custom fields -—AKA metadata — for a very long time. The post and user metadata allows an arbitrary amount of information — product price, SEO description, etc. — to be associated with a post or a user. Without this system, the most successful and useful WordPress plugins would require custom database tables.
WordPress 4.4 introduced term meta, which replicates the metadata system for taxonomy terms. Previously a taxonomy term could only have a name, slug, and description. Now you can add any number of additional fields to each term.
For example, if you wanted to associate a color with each category and then use that color in your theme to make the category archive page unique, you could store that color in a term meta field.
Another example is if you wanted to build a featured product system for an eCommerce plugin based on product category. Before term meta, if you asked me to build that, I would have added a field to the product post that marked it as featured or not.
With the new changes in term meta,the relationship could work the other way. Each taxonomy term can store a list of post IDs as term meta. This method is preferable because it changes how I would query for the products and it moves the interface from the post editor to the term editor — or maybe it’s on both.
Working With Term Meta
There are several new functions to use with term meta and they all follow the same pattern as the post and user meta functions. In addition, the generic meta functions like update_metadata, delete_metadata(), and add_metadate() can now be used with term meta as well as user and post meta.
Let’s briefly take a look at the new functions. They should be easy to use as their post and user meta cousins are popular functions and the same pattern applies. I will also cover the ability to use a meta query to get_terms(). This is new but because it follows the same syntax as meta queries in WP_Query and WP_User_Query, it should be easy to learn.
Saving Term Meta
Just like saving post meta, we have two similar functions:
add_term_meta() and update_term_meta()
In general, update_term_meta() is the better choice for both creating new and updating term meta. The potentially good thing about using add_term_meta() is that it has an optional argument, $unique, which can prevent adding a term meta that already exists.
Each of these functions take the term ID. If you only have the slug, you will need to retrieve the term ID using get_term_by(). For example:
$term = get_term_by( 'slug', 'red', 'color' );
if( is_object( $term ) ){
$id = $term->term_id;
}
With the term ID, you can now add term meta key like this:
add_term_meta( $id, 'hex_value', 'ff0000' );
Then if you need to, you can update that term meta key like this:
update_term_meta( $id, 'hex_value', 'ff6666' );
Displaying Term Meta
Just like post meta, which we retrieve with the function get_post_meta(), term meta can be retrieved with get_term_meta(). The arguments passed to this function have the same order and effect.
Let’s imagine that you have added a term meta field called “background_color” to all terms of a taxonomy called “jedi” and wanted to output that as inline CSS, here is how you would do that:
add_action( 'wp_head', function() {
if( is_tax( 'jedi' ) ) {
$color = get_term_meta( get_queried_object_id(), 'background_color', true );
if ( empty( $color ) ) {
$color = '#fff';
}
printf( 'body{background-color:#%s;}', $color );
}
});
As you can see in the header, I am checking if we are on an archive page for the taxonomy “jedi.” If so, I pull the term meta field using get_term_meta() and output as an inline stylesheet. Of course, I check that it is set or a valid hex before doing so. Validating that my term meta value is in fact a hex code is essential to ensuring that I don’t end up with invalid CSS on my page and is a step that shouldn’t be skipped.
Querying By Term Meta
With the addition of term meta data to WordPress, get_terms(), the function we use to query for taxonomy terms has gained the ability to perform meta queries. Term meta queries are powered by the same class as meta queries for posts or users. If you are familiar with the patterns used for those queries, that knowledge is transferable.
One cool thing that term meta makes easy is relationships between taxonomies. For example, imagine a site with a taxonomy called “states” and one called “cities.” Term meta would be a great way to create a relationship between the term “pennsylvania” in the states taxonomy and the terms “pittsburgh” and “philadelphia” in the cities taxonomy.
We could represent this relationship with a term meta field called “state” in the cities taxonomy. Then we could query for terms of the cities taxonomy based on state.
$terms = get_terms( 'city', array(
'meta_key' => 'state',
'meta_value' => 'city'
) );
What About An Interface?
I’m not going to cover the interface for editing term meta, on the term editing screen in this post. This is partially because you should be able to put what you have learned here to use in your own form.
That’s also because next week I will be talking about the new WordPress Fields API. One of the examples of how to implement the fields API will be using it to on the term edit screen for managing meta fields.
No Comments