Plugins & Themes

Introduction to WordPress term meta

As we gear up for the release of WordPress version 4.4, many developers are planning some cool features that they’ve been waiting for years to implement. These features revolve around term metadata.

The original Trac ticket is over 6 years old. A potential roadmap was outlined by Andrew Nacin a little over 2 years ago on the changes that would need to happen to get term meta in core WordPress. Even if/when those changes happened, it didn’t guarantee the inclusion of term meta.

Fortunately, this long sought-after developer feature was green-lighted for WordPress 4.4.

And, it’s awesome.

What is term meta?

Terms are individual objects within a taxonomy. For example, the category taxonomy can have many categories (i.e., terms).

Meta (short for “metadata”) is simply additional data that can be tied to an object. This data can pretty much be anything.

Term meta, therefore, is additional data about specific taxonomy terms.

WordPress has long allowed for meta on other types of objects, such as:

Posts

Comments

Users

If you’ve used WordPress, you’ve used metadata in some way, even if you didn’t know it. Metadata is actually pretty important because it allows plugins (and even core itself) to add extra data to the various objects that’s not accounted for in the main table.

A good example of this is featured images in core. Core stores the image ID as metadata because there’s no field for the image ID in the posts table. So, metadata to the rescue!

Example uses of term meta

This is just an extremely small sampling of ideas:

Term images.

Storing the color hex code (e.g., #000000) to assign a color.

Storing the document title via an SEO plugin.

Category templates that can be re-used (like page templates).

Attach an icon to a term.

Theme sidebar position.

Privatize posts that are in a specific category in a membership plugin.

Without term-meta, it’s impossible to describe a tag or category beyond it’s literal description. Terms are crippled without metadata, and are infinitely powerful with it.

I couldn’t have said it better myself.

Terms are not posts

Before moving forward, I want to touch on something that’s been at the heart of the discussion of whether term meta even belongs in core at all.

Terms are not posts.

If you’re building terms with vast amounts of metadata, particularly things that are maybe even handled better by posts, you might need to reconsider the architecture of your plugin. Sure, the API allows for easy relationships, but if that’s the only reason you’re using a taxonomy instead of a custom post type, I’d urge you to consider the possibility of just building a post-to-post relationship (not that hard).

How to use term meta

If you’re a developer and have ever used post, comment, or user meta, you’re pretty much already familiar with the foundations of term meta. The biggest things you need to know are the new meta wrapper functions for terms:

add_term_meta()

update_term_meta()

delete_term_meta()

get_term_meta()

They work just like their *_post|comment|user_meta() siblings. I don’t think it’s worth covering these in great detail.

Instead, I’m going to walk you through building a simple plugin using term meta. What this plugin will do is allow users to assign a color to a category. This can be useful for all sorts of things. One thing that immediately comes to mind is designing a news theme and having a specific color associated with each category, which is typical of many news publications.

Registering meta

The first step is to register our meta with the register_meta() function. We’ll name our custom meta key color.

Note that we added a sanitize callback function for when meta is saved. So, let’s go ahead and add the code for that. What the function is going to do is simply make sure that we have a valid color hex code.

There’s actually several hooks available if you dig into wp-admin/edit-tags.php and wp-admin/edit-tag-form.php. I highly encourage scanning those files for calls to do_action() and finding the most appropriate hook for your use case.

One of the biggest things to note is that the add new term and edit term forms have different HTML markup. This means that you need two separate callback functions for handling output of the fields.

What we’ve done is add a basic text input to both forms for the color. Remember, we’re only adding this for the category taxonomy. So, take note that the category part of the hooks is related specifically to that taxonomy.

Saving term meta

In order to save the fields we added, we need to hook into create_{$taxonomy} (new term form) and edit_{$taxonomy} (edit term form). Fortunately, we can use the same callback function with this and just check that our field was posted.

Again, take note that the category part refers specifically to the name of the taxonomy.

That’s pretty much it for handling the adding of custom form fields and saving the data. We’ll add a color picker in just a bit to make it look a bit prettier.

Adding a term meta column

On the taxonomy management page, you might want to add a custom column to output your metadata. One thing to keep in mind is that the list table for taxonomies is kind of small, so too many columns can get unruly.

If you have been using another plugin, you may like to switch to this new one by Ronald Huereca. It uses the new built-in system in WordPress and is somewhat more efficient than the other plugins I’ve seen for this.

Hi Justin, please consider me slow on the uptake; I simply don’t understand the purpose of these term meta data. Take your detailed example, now you have great colors of categories in the backend! Is there any functional use for these in the frontend? I fail to see it and would appreciate if you can shine a light on that for me.
Thanks.

What about related post types, say we had a post type for orders and a post type for order items. Relationships like that, we of course should not store the main post type style data in a post collection.

Yet, I am wondering if the term meta could be used to use a one to many relationship index or a many to one index relationship. What doesn’t seem pragmatic is a many to many relationship using term data. This is one of the most common related data not yet part of WordPress.

Could you share your thoughts on how to deal with those three relationships. Especially it would be great if we could figure out how to do this as friendly as we do with the new term meta!

Nice tutorial. This will be a great resource for people as WordPress 4.4 was just released today. Term meta opens a lot of opportunity for developers. I’m gonna to integrate it with my Meta Box plugin. So exciting!

Really helpful guidance, and I’ve put it to use already. This feature is so new, there aren’t many good tutorials yet.

If I was going to use taxonomy meta to enable images to be associated with categories, how would I use a form control to upload an image to the field instead of using a color picker? Any thoughts welcome!

Ok, that makes sense, thanks. I suppose that post/comment types could be regarded as metadata in themselves for the creation of posts & comments, just as OOP classes are for instanciating objects. I’m not sure if this inorthogonality re. metadata makes sense for taxonomy though as these aren’t used to stamp out new terms but more as a container for grouping them as I see it.