One feature that makes WordPress a highly flexible and powerful content management system is its implementation of taxonomies. By default, WordPress ships with the “category” and “post_tag” taxonomies. WordPress allows you to set the following metadata for each term in a taxonomy by default:
- name
- slug
- parent
- description
With the implementation of the add_metadata function in WordPress 2.9, a developer can add any metadata that s/he may desire. This tutorial will teach you how to add metadata for terms by walking you through an example of adding an image url as metadata for “category” terms.
The Basics
WordPress 2.9 added the following functions to the WordPress core in order to allow for the addition of metadata to objects other that posts.
- add_metadata
- update_metadata
- get_metadata
Add_Metadata
While it may seem that you simply fill in the arguments for these functions and the metadata will be added, there is a little more involved than that. If you visit the WordPress Codex page for the add_metadata function, it explains that you must first add a new table to the database in order for these functions, when used with taxonomies, to properly store and access data.
Fortunately, there are a number of developers who have released plugins that will do this for you, and in most instances, they provide simple wrapper functions to make adding term metadata quite simple. The plugin that I use for this task is Simple Term Meta, lovingly coded by Jacob M. Goldman. This plugin will add the needed table to your database and gives you the following functions (among others) for your use.
- add_term_meta
- update_term_meta
- get_term_meta
Yes, those functions look very similar to the WordPress functions mentioned earlier. These functions are merely wrapper functions that remove the need to declare the “meta_type” parameter for each call to the metadata functions. Additionally, these functions operate in a similar fashion to the post metadata function (i.e., add_post_meta, update_post_meta, get_post_meta). In fact, just as the term metadata functions are wrappers for the WordPress metadata functions, so to are the post metadata functions.
Make sure to install the Simple Term Meta before proceeding with this tutorial as the rest of it will not work without it installed.
Creating Form Inputs on Categories Page
In order to add information to the database, form inputs need to be created. The form inputs will be added to the following two screens:
- Add category page (e.g., yourdomain.com/wp-admin/edit-tags.php?taxonomy=category)
- Edit category page (e.g., yourdomain.com/wp-admin/edit-tags.php?action=edit&taxonomy=category&tag_ID=4&post_type=post)
To accomplish this task, add the following code to your theme’s functions.php file (or to a plugin file).
Taking a closer look at this code, the first two lines instruct the two functions that add the form inputs to be called at the bottom of the category add and edit screens. The category_add_form_fields hook is called in the add category screen (e.g., yourdomain.com/wp-admin/edit-tags.php?taxonomy=category), and the category_edit_form_fields hook is called in the edit category screen (e.g., yourdomain.com/wp-admin/edit-tags.php?action=edit&taxonomy=category&tag_ID=4&post_type=post). Notice that the first word in the hooks is “category”. The first word in the hook specifies the taxonomy in which this hook is run. If the target taxonomy was named “location”, the proper hooks would be location_add_form_fields and location_edit_form_fields.
In the present code, different functions are being sent to the different hooks. Unfortunately, the layout of the add and edit screens for taxonomies have very different markup, so the same function cannot be used for both hooks. For the category_metabox_add function, a text input with name “image-url” is added. The markup is taken straight from WordPress core in order to match the styling of the other fields. This code gives us the following:
In addition to adding an input on the add category page, a corresponding input needs to be added for the edit category page. Like with the add category page, I dipped into the WordPress core and utilized the code that generated the other fields in order to get a similar look for the new input field. You will notice that it’s presented in a table instead of a div structure. Presumably, when the edit screen is accessed, there will already be data entered for the field. In order to show that data, it needs to be accessed from the database. This task is accomplished with the use of the get_term_meta function, one of the functions made available by the Simple Term Meta plugin. The function is defined in the plugin with:
The “term_id” is the id given to the term when it is first entered into the database. The “key” is the name of the metadata. “Single” specifies whether to return an array (single = false) or a string (single = true). In order to get a value if one has already been entered, the following code is utilized.
“$tag” holds the term object, thus making the id for the tag obtainable with “$tag->term_id”. Next, ‘image-url’ is specified for the key as it is what I would like the metadata to be called. The function that displays the input for the edit screen will give you something like the following image.
Now that the input fields are set up, it is time to write some code that will add the values to the database when submitted.
Saving Term Metadata
Adding the metadata to the database is quite straight forward when utilizing the functions provided Simple Term Meta. It can be done with the following code.
To begin, the save_category_metadata function is called using two special hooks. The created_category hook is run when the category is initially added and the edited_category hook is run when the category is edited. Like the hooks used in adding the input fields to the form, these hooks can be changed for a custom taxonomy. If the taxonomy was “location”, the hooks would be changed to created_location and edited_location.
The save_category_metadata is very simple. It checks to see if the “image-url” key in the $_POST array is set. If so, the metadata is added using the update_term_meta function. The update_term_meta is defined in the Simple Term Meta plugin as:
The “term_id” and “meta_key” parameters specify the id of the term that the metadata is associated with and the name of the metadata, respectively. The “meta_value” parameter specifies value of the metadata. In the present example, the following code is used to enter the metadata.
The “term_id” is magically passed to the function using by the hook. Therefore, the “term_id” is simply thrown into the function. Because I want the metadata saved using the “image-url” key, I set that as the second parameter. Finally, the third parameter is set as the value of the field input, which is accessed using $_POST['image-url']. Upon saving the taxonomy, the values are saved to the database and can be accessed using get_term_meta, which will be demonstrated in the next section.
Using Term Metadata in a Theme
Fields have been added to the “category” taxonomy screens and the data has been saved. All that is left is using this data in some interesting way. Since I currently have the second beta of WordPress 3.2 installed on my development setup, I will demonstrate using term metadata in the brand new “Twenty Eleven” theme.
On the default category page, the theme displays the category name, description, and begins showing the posts in that category. It looks like the following screenshot.
Inserting the following code into “category.php” displays the image specified in the term metadata on the category page.
The get_term_meta retrieves the value previously saved in the database and returns it for use in the template. Using the value for the “src” attribute in the “img” tag allows the image to be displayed. This results in a slightly more “graphic” category page.
Conclusion
As one can see, adding metadata to terms is not a difficult task. With an excellent plugin like Simple Term Meta, WordPress can be extended to manage more data associated with taxonomy terms. If you have any experience with the WordPress post metadata functions, you are already familiar with how the term metadata functions work. The most important aspects to remember when dealing with term metadata is that term metadata does not work “out of the box.” It is absolutely necessary that the proper addition to the database is made. Additionally, you must make sure that you utilize the proper hooks to add input fields to the add and edit screens, as well as when saving the data. If you follow those steps, you will be on your way to creating all of the term metadata that your heart can desire.
