If you’re at all familiar with taxonomies in WordPress, you already know how awesome it is to add custom taxonomies to your posts or custom post types. WordPress developers have known this for a while.
What many people don’t know is that the current taxonomy schema was added way back in WordPress 2.3. Yes, that means the ability to create and use custom taxonomies has been around since 2007. We didn’t get all the cool functions added until 2.8 though.
However, one thing we’ve had since 2.3 was the ability to create taxonomies for any object type, not just posts. In WordPress, there are several object types:
- Posts
- Users
- Comments
- Links
So, you can technically create a taxonomy for any object type. Most of WordPress core support is for posts, but the API is extremely well thought out and can handle the other object types with minimal code effort.
This tutorial will focus on registering and using a taxonomy on the user object type. It will not be a 100% solution for everything you can do with a custom user taxonomy. Consider this an extremely rough draft of what’s possible.
Because this is such an in-depth topic, I cannot explain every minute detail. That would make for about a 50-page tutorial. You’ll need to be familiar with a few key areas in WordPress development before proceeding: plugins, themes, users, and taxonomies.
Registering a user taxonomy
In this tutorial, you will use and register a taxonomy called “Profession.” This is just an example, so feel free to experiment and create your own taxonomies for your uses.
To register the user taxonomy, you use the register_taxonomy() function just like you would with any other taxonomy. The following code block will register the profession taxonomy and set up its arguments.
/**
* Registers the 'profession' taxonomy for users. This is a taxonomy for the 'user' object type rather than a
* post being the object type.
*/
function my_register_user_taxonomy() {
register_taxonomy(
'profession',
'user',
array(
'public' => true,
'labels' => array(
'name' => __( 'Professions' ),
'singular_name' => __( 'Profession' ),
'menu_name' => __( 'Professions' ),
'search_items' => __( 'Search Professions' ),
'popular_items' => __( 'Popular Professions' ),
'all_items' => __( 'All Professions' ),
'edit_item' => __( 'Edit Profession' ),
'update_item' => __( 'Update Profession' ),
'add_new_item' => __( 'Add New Profession' ),
'new_item_name' => __( 'New Profession Name' ),
'separate_items_with_commas' => __( 'Separate professions with commas' ),
'add_or_remove_items' => __( 'Add or remove professions' ),
'choose_from_most_used' => __( 'Choose from the most popular professions' ),
),
'rewrite' => array(
'with_front' => true,
'slug' => 'author/profession' // Use 'author' (default WP user slug).
),
'capabilities' => array(
'manage_terms' => 'edit_users', // Using 'edit_users' cap to keep this simple.
'edit_terms' => 'edit_users',
'delete_terms' => 'edit_users',
'assign_terms' => 'read',
),
'update_count_callback' => 'my_update_profession_count' // Use a custom function to update the count.
)
);
}I won’t cover all the arguments used in the code above. I’ve written about those in a previous tutorial. However, there are a few arguments you should pay careful attention to:
- rewrite['slug']: I used
author/professionso that the slug would fall in line with the WordPress user slug,author. We’ll need a slight fix for this too, which I’ll get to later in the tutorial. - capabilities: For simplicity, I’ve set most of the capabilities to
edit_users. Only administrators can manage, edit, and delete professions with this by default. Theassign_termscapability is set toreadso all users can edit this on their profile page. You’ll want to set up some custom capabilities or configure this to do what you want. - update_count_callback: You must use a custom function for this because WordPress expects the taxonomy to be for the post object type.
Once you’ve registered your taxonomy, WordPress really doesn’t do much for you. It won’t add any custom admin pages, meta boxes, or anything of the sort like it does for posts. That’ll be left up to you.
Custom term update count callback
Right off the bat, you’ll already need some custom code. Since WordPress will only update the term counts for taxonomies on posts, you’ll need a function to do this for users.
When you registered your taxonomy, you set the update_count_callback argument to my_update_profession_count. The following code is that callback function.
/**
* Function for updating the 'profession' taxonomy count. What this does is update the count of a specific term
* by the number of users that have been given the term. We're not doing any checks for users specifically here.
* We're just updating the count with no specifics for simplicity.
*
* See the _update_post_term_count() function in WordPress for more info.
*
* @param array $terms List of Term taxonomy IDs
* @param object $taxonomy Current taxonomy object of terms
*/
function my_update_profession_count( $terms, $taxonomy ) {
global $wpdb;
foreach ( (array) $terms as $term ) {
$count = $wpdb->get_var( $wpdb->prepare( "SELECT COUNT(*) FROM $wpdb->term_relationships WHERE term_taxonomy_id = %d", $term ) );
do_action( 'edit_term_taxonomy', $term, $taxonomy );
$wpdb->update( $wpdb->term_taxonomy, compact( 'count' ), array( 'term_taxonomy_id' => $term ) );
do_action( 'edited_term_taxonomy', $term, $taxonomy );
}
}I just kept this extremely simple and modified the _update_post_term_count() WordPress function. Feel free to further modify it to suit your needs.
Creating the manage terms page
Since WordPress does not create an admin page for managing terms of custom user taxonomies, you’ll need to create that. For the sake of simplicity and laziness, I just used the admin page WordPress already uses for other taxonomies.
The problem with this is that WordPress doesn’t recognize that the “Professions” admin page is a sub-menu of the “Users” admin page when viewing it. The sub-menu is placed correctly, but when clicking on it, the “Posts” menu is opened in the admin. I’d really love to see some WordPress core support for this.
Update: See the comment by James below to get a fix for this.
The following code is what I used, but you can definitely create a custom admin page for managing your terms.
/* Adds the taxonomy page in the admin. */
add_action( 'admin_menu', 'my_add_profession_admin_page' );
/**
* Creates the admin page for the 'profession' taxonomy under the 'Users' menu. It works the same as any
* other taxonomy page in the admin. However, this is kind of hacky and is meant as a quick solution. When
* clicking on the menu item in the admin, WordPress' menu system thinks you're viewing something under 'Posts'
* instead of 'Users'. We really need WP core support for this.
*/
function my_add_profession_admin_page() {
$tax = get_taxonomy( 'profession' );
add_users_page(
esc_attr( $tax->labels->menu_name ),
esc_attr( $tax->labels->menu_name ),
$tax->cap->manage_terms,
'edit-tags.php?taxonomy=' . $tax->name
);
}This will at least allow you to create and manage custom terms of the profession taxonomy. If you have a better solution for this, please post it in the comments for other people to see.
Fixing the “Posts” column
After creating the admin page, you probably noticed a column on it called “Posts.” Instead, it should display a “Users” column. The following code will fix this issue and list the number of users with each term from the profession taxonomy.
/* Create custom columns for the manage profession page. */
add_filter( 'manage_edit-profession_columns', 'my_manage_profession_user_column' );
/**
* Unsets the 'posts' column and adds a 'users' column on the manage profession admin page.
*
* @param array $columns An array of columns to be shown in the manage terms table.
*/
function my_manage_profession_user_column( $columns ) {
unset( $columns['posts'] );
$columns['users'] = __( 'Users' );
return $columns;
}
/* Customize the output of the custom column on the manage professions page. */
add_action( 'manage_profession_custom_column', 'my_manage_profession_column', 10, 3 );
/**
* Displays content for custom columns on the manage professions page in the admin.
*
* @param string $display WP just passes an empty string here.
* @param string $column The name of the custom column.
* @param int $term_id The ID of the term being displayed in the table.
*/
function my_manage_profession_column( $display, $column, $term_id ) {
if ( 'users' === $column ) {
$term = get_term( $term_id, 'profession' );
echo $term->count;
}
}Assigning terms to users
Thus far, you’ve got a custom taxonomy and can add terms for it, but you need a way to assign these terms to individual users. For this example, you’ll be adding a custom section to the edit user/profile page in the admin. It will display a list of radio select boxes so the user can choose their profession.
This is just an extremely basic example. You have tons of room for customization. You can do select elements, checkboxes, a text input, or whatever best works for you.
The following PHP code will add this section to the edit user/profile page.
/* Add section to the edit user page in the admin to select profession. */
add_action( 'show_user_profile', 'my_edit_user_profession_section' );
add_action( 'edit_user_profile', 'my_edit_user_profession_section' );
/**
* Adds an additional settings section on the edit user/profile page in the admin. This section allows users to
* select a profession from a checkbox of terms from the profession taxonomy. This is just one example of
* many ways this can be handled.
*
* @param object $user The user object currently being edited.
*/
function my_edit_user_profession_section( $user ) {
$tax = get_taxonomy( 'profession' );
/* Make sure the user can assign terms of the profession taxonomy before proceeding. */
if ( !current_user_can( $tax->cap->assign_terms ) )
return;
/* Get the terms of the 'profession' taxonomy. */
$terms = get_terms( 'profession', array( 'hide_empty' => false ) ); ?>
<h3><?php _e( 'Profession' ); ?></h3>
<table class="form-table">
<tr>
<th><label for="profession"><?php _e( 'Select Profession' ); ?></label></th>
<td><?php
/* If there are any profession terms, loop through them and display checkboxes. */
if ( !empty( $terms ) ) {
foreach ( $terms as $term ) { ?>
<input type="radio" name="profession" id="profession-<?php echo esc_attr( $term->slug ); ?>" value="<?php echo esc_attr( $term->slug ); ?>" <?php checked( true, is_object_in_term( $user->ID, 'profession', $term ) ); ?> /> <label for="profession-<?php echo esc_attr( $term->slug ); ?>"><?php echo $term->name; ?></label> <br />
<?php }
}
/* If there are no profession terms, display a message. */
else {
_e( 'There are no professions available.' );
}
?></td>
</tr>
</table>
<?php }After adding the preceding code, you’ll get a new section near the bottom of your edit user/profile page that looks like the following screenshot.
You’ll need a way to save the selected term (profession) for the user. The next code block will handle that.
/* Update the profession terms when the edit user page is updated. */
add_action( 'personal_options_update', 'my_save_user_profession_terms' );
add_action( 'edit_user_profile_update', 'my_save_user_profession_terms' );
/**
* Saves the term selected on the edit user/profile page in the admin. This function is triggered when the page
* is updated. We just grab the posted data and use wp_set_object_terms() to save it.
*
* @param int $user_id The ID of the user to save the terms for.
*/
function my_save_user_profession_terms( $user_id ) {
$tax = get_taxonomy( 'profession' );
/* Make sure the current user can edit the user and assign terms before proceeding. */
if ( !current_user_can( 'edit_user', $user_id ) && current_user_can( $tax->cap->assign_terms ) )
return false;
$term = esc_attr( $_POST['profession'] );
/* Sets the terms (we're just using a single term) for the user. */
wp_set_object_terms( $user_id, array( $term ), 'profession', false);
clean_object_term_cache( $user_id, 'profession' );
}Displaying user taxonomy terms
You can use any of the standard WordPress taxonomy functions for listing out your terms. For example, wp_list_categories() and wp_tag_cloud() will both work fine. Each will link to the term archive page (covered in the section below).
If you wanted to show a tag cloud with all of your “professions” (profession cloud) in a theme template, your code would look something like the following.
<?php wp_tag_cloud( array( 'taxonomy' => 'profession' ) ); ?>One thing to look out for though is that the title attribute for links in the tag cloud will read “1 topic” or “X topics.” An easy way to change this is to write a custom callback function to modify the text. In the following screenshot, you can see this changed from “topics” to “users”.
The following code block is a function that will handle that.
/**
* Function for outputting the correct text in a tag cloud. Use as the 'update_topic_count_callback' argument
* when calling wp_tag_cloud(). Instead of 'topics' it displays 'users'.
*
* @param int $count The count of the objects for the term.
*/
function my_profession_count_text( $count ) {
return sprintf( _n('%s user', '%s users', $count ), number_format_i18n( $count ) );
}You’d use it when displaying your tag cloud like so:
<?php wp_tag_cloud(
array(
'taxonomy' => 'profession',
'topic_count_text_callback' => 'my_profession_count_text'
)
); ?>Templates for term archives
The template for term archives is handled the same as any other taxonomy. So, if you wanted to create a custom template (you probably should) for your theme to display users by profession, you’ll want to create a template named taxonomy-profession.php.
I won’t cover creating theme templates here. It’s outside the scope of this tutorial.
The big difference between this template and a normal template is there’s no post loop. Instead, you need to create a user loop. The following code should replace your normal post loop in this template.
<?php
$term_id = get_queried_object_id();
$term = get_queried_object();
$users = get_objects_in_term( $term_id, $term->taxonomy );
if ( !empty( $users ) ) {
?>
<?php foreach ( $users as $user_id ) { ?>
<div class="user-entry">
<?php echo get_avatar( get_the_author_meta( 'email', $user_id ), '96' ); ?>
<h2 class="user-title"><a href="<?php echo esc_url( get_author_posts_url( $user_id ) ); ?>"><?php the_author_meta( 'display_name', $user_id ); ?></a></h2>
<div class="description">
<?php echo wpautop( get_the_author_meta( 'description', $user_id ) ); ?>
</div>
</div>
<?php } ?>
<?php } ?>The most important function used in the code above is the WordPress get_objects_in_term() function. By putting in a term ID and taxonomy name, you can grab an array of all the object (user) IDs with that term (profession). With the user ID, you can load any information about a user you want with any standard WordPress functions.
Of course, you’re free to customize this however you want. The preceding code merely loops through each of the users with a specific profession. It then displays each user’s avatar, name with a link to their posts archive, and description.
Disabling the ‘profession’ username
When you registered the profession taxonomy, you created the slug author/profession so that the profession archive pages would have a URL like yoursite.com/author/profession/designer. The problem with this that “profession” could potentially be a username someone signs up to your site with.
The following code will make sure no one can sign up with this username:
/* Filter the 'sanitize_user' to disable username. */
add_filter( 'sanitize_user', 'my_disable_username' );
/**
* Disables the 'profession' username when someone registers. This is to avoid any conflicts with the custom
* 'author/profession' slug used for the 'rewrite' argument when registering the 'profession' taxonomy. This
* will cause WordPress to output an error that the username is invalid if it matches 'profession'.
*
* @param string $username The username of the user before registration is complete.
*/
function my_disable_username( $username ) {
if ( 'profession' === $username )
$username = '';
return $username;
}Of course, if you use a different rewrite structure for your taxonomy, don’t worry about that code.
Time to create your own user taxonomies
Whoah! That was certainly a ton of information to cover in a single tutorial. I’m sure some of you have questions, so please ask away in the comments.
Now it’s time for you to venture out on your own and create some cool stuff. I’d love to hear what ideas you have and see any projects that you use this code in. I’m definitely interested in seeing some practical, real-world use cases of user taxonomies.
One final note: The code in this tutorial is just something I played around with in about a two-hour span. It’s still a work in progress. Honestly, it took me much longer to write this tutorial. Therefore, I leave it up to you, dear reader, to improve upon the code.
It’s features like this that take WordPress beyond being just another piece of blogging software. I think we’ll start seeing even more non-blog sites powered by WordPress in the next few years.
Also, thanks for another great tutorial, Justin.
Yeah, there’s so many of these additional “features” that are built in that many people don’t really know about. The more people continue to figure out these things and put them into practical use, the better WordPress will become and the more non-blog sites we’ll see.
Thanks for this, Justin!
I’ve never messed with this much, but I’ve always wondered if conflicts would arise with the fact that wp_term_relationships has a column for object_id, but no way of differentiating between different kinds of objects. That is, if you apply a term to a post with ID = 34, and another term to a user with ID = 34, does it cause problems? Presumably, for this reason, you couldn’t use the same taxonomy for users and for posts/CPTs?
I imagine that would be problematic. I haven’t given it much thought though. I doubt I’d ever run into that situation because I can’t think of a reason I’d use a taxonomy for one object type on an entirely different object type.
So far I’ve been able to share two object types. Where this is useful is if you have hundreds of terms in a taxonomy that change frequently you don’t want to have to update two lists. For example, I have posts categorized by client. I’ve modified this code to eliminate registering the new taxonomy and just used my existing taxonomy. This way, on the user profile page I can assign a user to a term that already exists. Posts categorized by clients and users assigned to those clients.
So far everything works great, except I can’t get the term count to work properly and I don’t think I can because of what Boone pointed out. That’s not a feature I need though.
Did you try the custom update term count functionality from above? That may or may not help.
By not working properly I mean that I can’t update the term count for the specific object. So while the term is being used X times by the post object, I can’t determine how many times its being used by the user object.
Yeah, that makes sense. One thing you might try is updating and saving this as separation options in the options table instead. You’d need a custom function to loop through the array of IDs, checking what each object type it is based on the ID.
It’s probably possible with something like that.
Hello Justin. Thanks for another great tutorial.
I have a similar question here regarding a taxonomy for multiple object types. I have been administrating a WP based site for our non-profit organization. The site organizes content around our various locations in the field.
At present, each location has a dedicated page with a description of the country, it’s history and all that is taking place there. At present, I can include links from around the site drawing on posts, users, and links. But I’d prefer to automate this.
I’d like to use a hierarchical “location” taxonomy to pull CPTs, users and links into one catch-all archive page. I’ve wondered for a long time about how to do this and your tutorial answers a lot of my questions. But now I see that with these objects separated into separate db tables it might be much more complicated.
Why doesn’t WP just group all objects into one table: CPTs, users, links …. That would make a relationships table much more helpful, wouldn’t it?
I really hope they add more core support for user taxonomies in future WordPress releases. It’s really unfortunate that you have to hack together a lot of the functions that make user taxonomies actually useful. Nonetheless, very insightful tutorial Justin, as usual. Cheers!
I could live with what we have if we just got a fix for the admin page/menu issue. And, maybe a fix for the update term count because I don’t want to have to deal directly with the database.
I’ve been looking forward to this post from the first time I read the tweet.
Thank you for such a detailed setup and explanation of what works and the current pitfalls. It’s really awesome to see tutorials and snippets like this that are way out of the wp ‘norm’.
This is incredibly timely for a project I’m working on right now, thank you for posting it!
Thanks for such detailed explanation, Justin. Superb as usual. I didn’t know that
userobjects are the same as posts and links. You already put an idea in my head (of implementing a project using these methods).In another note, when I enter the site with the
www.subdomain it redirects to a Google 404 page. Maybe your host didn’t add thewwwsubdomain automatically to your domain name.Actually, there’s no redirection at all. It shows a blank Google 404 page with a link to Google homepage.
Excellent, as always.
Presumably we could also create a hierarchical custom taxonomy for users, such as geographical values, e.g. Continent > Country > Region etc ?
If so then this opens up some really interesting opportunities
Definitely. I just used a non-hierarchical taxonomy in the tutorial since it’s a little simpler.
brilliant tutorial, Justin ! Thanks !
I created one taxonomy in my post but when i update without check any they dont have a default taxonomy.
How i can set a default taxonomy?
Great tutorial! And just in time for a project I am working on. I implemented this for a “Location” taxonomy that is used for grouping users by country. However I noticed that when a user is deleted the term relations are not deleted and the term count remains the same. Is there an easy fix for that? Something to run on the ‘delete_user’ action maybe?
In order to delete user object to term relations upon user deletion use this function on the ‘delete_user’ action hook:
Hi Justin,
Nice article, but I hope you’ll consider improving this theme so that source code is presented better than just simple large-size fixed-width font. I yearn for your prior theme…
-Mike
Are you having trouble reading the code? I’ve tested it in a few different browsers; it’s coming out great for me.
Great article. The benefits of taxonomies are clear, and I want to start using them on my site. So I’m kind of dabbling at the moment, behind the scenes with them, on my website.
Quick question though, that kind of puzzles me about the creation of taxonomies. Suppose I change my mind about a particular taxonomy, and no longer want it. Is it just a case of deleting the relevant call to register_taxonomy in functions.php? What would happen to any terms that have been added under that particular taxonomy? Do they stay in the database?
Hi and thanks for all your articles.
On that one, I’m just wondering where to apply the filters and actions you created. Thanks !
Please ignore my previous question. I just didn’t know these filters were core and also working for taxonomies.
If you add the following to the
admin_head, it will simulate being on the right page:Thank you for this great tutorial; it’s been very helpful!
Here’s the code, properly formatted:
Awesome! Thanks for posting this.
This is fantastic. I love WordPress but user types and permissions are definitely an area where it’s lacking. With this custom taxonomy stuff I think I can get my WP site doing everything I want. Thanks!
I’m in the initial stages of planning a project and may end up using some of this rather than going with additional user roles or user meta as I was first thinking.
The following will set the right menu parent for your profession taxonomy.
Thanks for posting this, James.
Thx Justin for a good tut.
I am trying to use this and allow Admin to set Multiple Taxonomy term for each user.
In your example, only 1 profession can be set for each.
In my example, I Need to allow multiple Profession to be set.
I have already changed
my_edit_user_profession_section()to use checkbox instead of radio.2 problems
- How to save all checkbox selected.
- How to make each selected checkbox checked
Stuck on
and
thx in advance
Found my own answer
Change checkbox name to be
profession[]then in saving options
Hi Justin,
thanks for this, is a fantastic tutorial, exactly what I was looking for.
One thing I’d love to have, is this taxonomy showing in the ‘All Users’ screen (and preferably to be able to filter by it), I have found code to add a column but can’t figure out what code to use to pull out the taxonomy term/s.
I was trying with
but not sure if i’m totally in the wrong ball park!
Any ideas, or links to other places that could help?
thanks
elvis
Hi,
I managed to get the terms appearing in the column with wp_get_object_terms (simple error in column name!) but any ideas or links for how to set up a pulldown filter (like ‘category’ in all posts table).
thanks
elvis
Hi there Ive created a custom taxonomy called ‘province’ when I try to add these provinces to the menu (under appearance) it shows in red and says invalid.
Any ideas why this is occurring?
The custom taxonomy appears in my custom post type and everything seems to be working except I cant add it to the menu cause when I do it comes up as invalid.
Some great code snippets here, really helped me out a lot.
On a project I’ve been working on, needed a fair few user taxonomies, so I abstracted out a lot of the backend logic into a plugin, so all you have to do, is register a taxonomy in the normal way, and the rest of taken care of for you.
I’ll be expanding on the functionality in the coming weeks, but it will hopefully save some others the need for some of the code here
http://wordpress.org/extend/plugins/user-taxonomies/
Looks pretty good. The two things I didn’t like were:
1) How the “Taxonomies” section is handled on the user profile screen. I’d just assign the HTML to a variable and output the header if it’s not empty instead of using output buffering. I’d also separate each taxonomy into a unique section with its own header, which would really get rid of the need for output buffering.
2) Defaulting to radios for the taxonomy form element. I’d go with checkboxes for hierarchical and a text input for non-hierarchical as a default to match how WordPress handles these types of taxonomies for posts.
I know it’s still early in development, but maybe that’ll give you some ideas to work with.
Thanks for the feedback, very useful
1) I did consider an alternate heading, or no heading at all, as “taxonomies” has little meaning to anyone other than developers.
Having the headings as the taxonomy name and then repeating it as a label seemed redundant, and not having anything as the label didn’t seem too great either.
As for the use out output buffering, I was using that as I’m not a fan of concatenating more than one line of HTML using strings. To me, it makes more sense to use HTML with embedded variables, then PHP with mixed in HTML, but I guess that’s just a personal preference.
Out of curisity, what is your objection to the use of output buffering?
2) I had considered adding an additional (optional) property when registering the taxonomy which would control how it’s displayed (checkbox, radio buttons, select, textfield etc), but now that you mention it, that’s both unnecessary and an oversight, as checkboxes and textfield are both the standard way of handling it, and more than sufficient.
Thanks again for your feedback
Great tutorial on creating user taxonomies … really well explained.
One question I have and can’t seem to find the answer to is given a user has selected (in my particular case) a number of terms from the custom taxonomy, what code is needed to find all selected terms for that user?
In the tutorial you show the users for a particular term but not the other way around.
Any help would be greatly appreciated.
Thanks.
Awesome! Works great.
I’m wondering how I could incorporate this into the front end?
I have some basic edit profile fields set up which are working but how would I be able to add taxonomies to a front end edit page?