How to Create Your Own Custom WordPress Taxonomies

This tutorial will help outline all that you need to know when it comes to WordPress taxonomies.

We will begin by discussing what taxonomies are, how they can be interacted with, and why they are important.

Later in the tutorial, we will go through the step-by-step process of creating your own custom taxonomies.

By the end, you should have a strong grasp of what taxonomies are and how you can leverage your own custom taxonomies to suit your website needs.

What Are WordPress Taxonomies?

Taxonomies, in their simplest sense, are a way to group together related items using one or more sets of words.

WordPress uses taxonomies to provide a simple mechanism to group together your posts and pages. Out of the box, WordPress comes with two main types of taxonomies:

• Categories
• Tags

These two taxonomies provide you an easy way to group your posts together using names / groupings that make sense to you, and your readers. For example, you could create a new category called ‘Featured’ which you can then assign specific posts to.

When you create a category or tag, you are creating a ‘Term’ within a ‘Taxonomy’. This is useful to know: categories and tags are just WordPress’ default implementation. You can create your own ‘Taxonomies’ with ‘Terms’ that suit your needs.

Categories and Tags Admin Areas

WordPress automatically creates administration areas for you to easily add your tags and categories. These administration areas are located inside the ‘Posts’ menu as sub-menus.

Both the categories and tags administration screens will look similar, giving you an easy way to add new terms to your website.

Assigning Categories and Tags to Your Posts

The easiest way to attach your categories and tags to your post is via the WordPress editor.

When you are editing your post / page you will notice a metabox that contains your categories and tags. These boxes often appear underneath your ‘publish’ metabox. These boxes are what you will need to use to assign your terms to the currently edited post.

Both the tag and category metaboxes will let you assign multiple terms to your post. You will be able to add terms you have created previously via their administration menus, or you can create and assign them on the fly (these new terms will then be selectable for other posts in the future).

What Does WordPress Do with Its Taxonomies?

WordPress will do a series of things with its in-built taxonomies, including:

• Create a single term listing page: WordPress will create a new page for this term. The URL of the term itself will be the name of the taxonomy followed by the name of the term. For example, if you had a ‘category’ named ‘featured’, the URL would be /category/featured. The purpose of this page is essentially to act as a listing page.

• Create a link to the single taxonomy listing page on your individual posts: If you attach the in-built terms to your post, when you view your post on the front end, WordPress will display a clickable name of the term, generally directly under the title of the post. Clicking on the term will take you to the term listing page.

• List your terms inside widgets: WordPress comes prebuilt with several ‘widgets’ that allow you to easily add content to your site’s widget areas (like sidebars and footers). Both your ‘categories’ and ‘tag cloud’ widgets will pull in your terms and display them as clickable links.

• Add your terms to the navigation menu: All of your tags and categories are added to the navigation administration menu where you define and build your main menu. This allows you to easily create a link directly to your most commonly used term.

Depending on your theme, there may be be other areas that take advantage of your taxonomies.

Creating Your Own Custom Taxonomies

While the inbuilt categories and tags may suit your organisational needs, more often that not, you will need more ways in which to group together your posts, especially if you are using custom post types.

How to Register Your Own Custom Taxonomy

To create your own custom taxonomies you will need to define your taxonomy using the register_taxonomy function. This function takes in three values as follows register_taxonomy($taxonomy, $object_type, $args). A brief summary of these values are detailed below:

1. $taxonomy – Name of the new taxonomy you are creating. Where WordPress calls their taxonomy ‘categories’ or ‘tags’, you may want to give yours another name, such as ‘members’. This name has to be under 32 characters in length and may only use letters and the underscore character.

2. $object_type – Name of the post type to which you want to attach this taxonomy. WordPress’ post post type has both categories and tags attached to it. You may want to attach your new taxonomy to an existing post type, or your own custom post type that you have previously created. You have two options in this case:

   • A single string representing the name of the post type such as $object_type = 'post'

   • An array of strings for the names of the post types such as $object_type = array('post','page')

3. $args – These are your arguments used to set the various options for your new taxonomy. There are multiple options that you can set. Several of these are mandatory, but most are optional (WordPress will handle any missing arguments):

   • label – The plural name for your taxonomy, for example ‘members’, if you were creating a membership taxonomy.

   • labels – An array of your names and values that will be used for the taxonomy. These are used in administration areas for management. This array specifies all of the labels used for your taxonomy. If you leave this empty, WordPress will use your label value and set these. In addition, you can skip specific non-needed values and they will be defaulted.

     • name – Plural name of the taxonomy.

     • singular_name – Singular name used for one term within the taxonomy.

     • menu_name – Text to be displayed on the WordPress administration back-end (along the left hand side administration menu).

     • all_items – Viewing all terms from the taxonomy.

     • view_item – Viewing a single term from the taxonomy.

     • update_item – Updating a single taxonomy.

     • add_new_item – Add new term text.

     • parent_item – Used with hierarchal taxonomies, generally set to Parent $taxonomy_name.

     • parent_item_colon – Same as above, but also adding a colon to the end.

     • search_items – Search text used when looking through your taxonomy.

     • popular_items – Popular term name, used in the back-end administration section for non hierarchical terms. Can easily be set to Popular $taxonomy_name.

     • separate_items_with_commas – This text is displayed for non-hierarchical taxonomies, this is the text shown on the taxonomy meta box for individual posts (this is shown directly under the ‘add’ button).

     • add_or_remove_items – This text is displayed for non-hierarchical taxonomies. This text is only shown with JavaScript disabled inside the taxonomy meta box for individual pages.

     • choose_from_most_used – This text is displayed for non-hierarchical taxonomies, at the bottom of the taxonomy meta box and when selected it will show a listing of the most used terms.

     • not_found – This text is displayed for non-hierarchical taxonomies, inside the taxonomy meta box only once you have clicked on the ‘Chose From Most used’ highlighted text. Once clicked, WordPress will look for the most used terms. If there are none, this text will be displayed.

   • public – Determines if your taxonomy will be shown and be able to be queried against.

   • show_ui – Determines if WordPress will display an administration area for your taxonomy. If this is not set, you won’t have an area to manage your terms.

   • show_in_nav_menus – Determines if the terms from this taxonomy will be selectable in your navigation menu.

   • show_tagcloud – Determines if WordPress will include your taxonomy’s terms inside the tag cloud widget.

   • meta_box_cb – Lets you specify a function used to output the design of the taxonomies meta box inside your single posts. If not selected WordPress will use its default.

   • show_admin_column – This determines if your taxonomy’s terms will appear inside a new column for your post listings. Setting this to ‘true’ will display a new column for your specified post type that will display all of its attached terms.

   • hierarchical – Determines if your taxonomy can levels such as parents / children (like categories) or are all flat in level (like tags).

   • update_count_callback – Name of a function to call when there has been an update to the attached post type. When this taxonomy’s post type changes, this function will be called.

   • query_var – Determines the name used for querying the post type. By default this is set to the name of the taxonomy itself. If set to a string, that string will be used. This is best left to its default value.

   • rewrite – This can be set in multiple ways. Setting this to ‘false’ will disable permalinks. If this has not been set to false, you can specify multiple element such as the ‘slug’. This is best left to its default true value.

   • capabilities – Determines the capabilities (permissions) needed to interact with the taxonomy such as deleting, adding, assigning. This is best left to its default value.

   • sort – Specifies that when assigning terms to a post, it should remember the order.

   • _builtin – Determines if this term is a ‘built in’ taxonomy or a custom taxonomy. This should not be touched when creating your taxonomy

Remember to check the check the WordPress codex on custom taxonomies, as it outlines what values are mandatory and which are optional (along with what values are valid).

Creating Your First Custom Taxonomy

As you can see, there are several options that you can set to tweak your taxonomy for your own requirements.

While you can individually set all of your taxonomies options, the majority of the time it is best to let WordPress fall back to its defaults settings.

For this tutorial, we are going to create a new taxonomy called Members which we will attach to our already existing Post post type.

//create a function that will attach our new 'member' taxonomy to the 'post' post type
function add_member_taxonomy_to_post(){

    //set the name of the taxonomy
    $taxonomy = 'member';
    //set the post types for the taxonomy
    $object_type = 'post';
    
    //populate our array of names for our taxonomy
    $labels = array(
        'name'               => 'Members',
        'singular_name'      => 'Member',
        'search_items'       => 'Search Members',
        'all_items'          => 'All Members',
        'parent_item'        => 'Parent Member',
        'parent_item_colon'  => 'Parent Member:',
        'update_item'        => 'Update Member',
        'edit_item'          => 'Edit Member',
        'add_new_item'       => 'Add New Member', 
        'new_item_name'      => 'New Member Name',
        'menu_name'          => 'Member'
    );
    
    //define arguments to be used 
    $args = array(
        'labels'            => $labels,
        'hierarchical'      => true,
        'show_ui'           => true,
        'how_in_nav_menus'  => true,
        'public'            => true,
        'show_admin_column' => true,
        'query_var'         => true,
        'rewrite'           => array('slug' => 'member')
    );
    
    //call the register_taxonomy function
    register_taxonomy($taxonomy, $object_type, $args); 
}
add_action('init','add_member_taxonomy_to_post');

Executing the above code will create a new taxonomy with the name Members and attach it to the Post post type. When you view the back-end of your website you will now see a new sub-menu inside the Post menu. Clicking on this new Members sub-menu will take you to the taxonomy administration screen.

Your taxonomy administration screen will look like either the category or tag screens depending on what you set your hierarchical argument to. Our new member interface looks as follows:

Creating Your New Terms

With your taxonomy registered you can now create your new terms (in our case members) to your hearts content.

We have created three new top level terms. Our terms are called Featured Members,Standard Members and Seasonal Members.

Our featured and standard members are single level terms while our seasonal members are multi levelled, with two terms as its children called Winter Members and Summer Members.

This is easy to visualise when you consider categories. Categories can have many sub-categories or even none at all.

Adding Your Terms to Your Post

You can add as many terms as you like to your posts. You assign these terms by editing the post itself and using the taxonomy meta box to attach the terms.

Interacting with Your Taxonomy / Terms

Once you have created and assigned your terms to your posts, you will need to modify your theme to take advantage of your new taxonomy.

WordPress will display its category and term related links when you view your individual posts. However, because you have registered your own taxonomy, you will need to customise your template to ensure that your terms are displayed.

Changing Your Theme Files to Show Your New Taxonomy

As you have added an additional taxonomy, you will need to slightly modify your theme template files to ensure that your terms are shown. This involves editing a few theme files and interacting with some WordPress functions.

Understanding Your Single Template File

If you are working on a child theme (and you should be), you can open up your single.php template file. While we won’t be editing this file, it’s important to know that this file handles the output of all single posts. Since we have attached our member taxonomy to posts, we will start here.

Your single.php should look something like the following. I am using Twenty Thirteen as my parent theme, but overall most single.php files have the same core functionality.

<?php
get_header(); ?>
	<div id="primary" class="content-area">
		<div id="content" class="site-content" role="main">
			<?php /* The loop */ ?>
			<?php while ( have_posts() ) : the_post(); ?>
				<?php get_template_part( 'content', get_post_format() ); ?>
				<?php twentythirteen_post_nav(); ?>
				<?php comments_template(); ?>
			<?php endwhile; ?>
		</div><!-- #content -->
	</div><!-- #primary -->
<?php get_sidebar(); ?>
<?php get_footer(); ?>

The main part you need to focus on is the get_template_part('content',get_post_format()). This function is what will actually display all of your single post content and it is here that we will need to perform our changes.

Understanding Your Content Template File

content.php is the file responsible for outputting your posts content. In actuality, it is the main file used to output all post type content, when there is no more specific template to load, it will load content.php.

The first part of get_template_part() will take the name of the file you are trying to load. The second parameter (which is optional) will then look for a specific version of that file. As an example get_template_part('content','video') will look for a file called ‘content-video.php’. When called by itself, such as get_template_part('content’), it will look for a file named ‘content.php’

What we want to do is edit our content template part. However, this presents some difficulty because meta information such as taxonomies are handled differently in different themes.

• Twenty Thirteen: In Twenty Thirteen, meta information is displayed using the twentythirteen_entry_meta() function. This function loops through your post’s categories / tags and is called from within content.php (and all of your other ‘content’ files such as ‘content-video.php’).

• Twenty Fourteen: In Twenty Fourteen, meta information is displayed inside of content.php directly (in addition, each of the other ‘content’ files such as ‘content-video.php’ also manually process this).

Creating a Function to Output Your New Taxonomy Terms

Our solution will be to create a quick function that has the sole job of displaying our new ‘member’ terms.

Open up your functions.php and enter in the following code:

function display_member_taxonomy_terms($post_id){
    
    //get all terms assigned to this post
    $member_terms = get_the_terms($post_id,'member'); 
    //if we have member terms assigned to this post
    if($member_terms){
        echo '<div class="member-terms-meta">';
        echo '<span class="term-title"> Member Terms: </span>';
        //loop through each term 
        foreach($member_terms as $term){
            //collect term information and display it
            $term_name = $term->name;
            $term_link = get_term_link($term,'member'); 
            echo '<a href="' . $term_link . '">'; 
                echo '<span class="term">' . $term_name . '</span>';
            echo '</a>';
        }
        echo '</div>';
    }
}

Calling Your New Function Inside Your Content File

Once you have added this function to your functions.php file, open up your content.php and find where your ‘entry-meta’ is being outputted. Call your new function inside this ‘entry-meta’ div. I have called our function above the standard Twenty Thirteen meta function as detailed below:

<div class="entry-meta">
	<?php display_member_taxonomy_terms($post->ID); ?>
	<?php twentythirteen_entry_meta(); ?>
	<?php edit_post_link( __( 'Edit', 'twentythirteen' ), '<span class="edit-link">', '' ); ?>
</div><!-- .entry-meta -->

When you open up your single posts, you will see that the member terms are now displayed above the standard category and tag terms (so long as you have assigned member terms).

Understanding What We Just Did

To get your new terms to display, what we did was first call a function named display_member_taxonomy_terms($post->ID);from within your content.php file. This function takes in the current post ID and attempts to show all terms belonging to our new taxonomy that have been assigned to this post.

We first called $member_terms = get_the_terms($post_id,'member'); to collect our terms for this post. The get_the_terms($post_id,$taxonomy_name) function takes in an ID of a post, along with a taxonomy name and gives us all attached terms for that taxonomy. In our situation, we passed it our current post id and also the ‘member’ taxonomy.

Next, we check to see if we have any results using a simple if statement if($member_terms). If we have do have terms to display, we loop through each of our terms using our for loop foreach($member_terms as $term). This loop lets us iterate through each term and access its information.

Finally, we accessed the name of the term (to display it to the user) and also fetched the URL of the term using the get_term_link($term_object,$taxonomy_name) function. This function takes in a term object and the name of the taxonomy, and gets the direct link to the term itself.

Wrapping Things Up

As you can see, creating custom taxonomies can provide you with a wide range of new ways to organise your websites content such as your posts.

By creating a new taxonomy and associated terms and assigning them to a post, you can create a layer of organisation which you can leverage to further categorise content for your website.