Customize Your WordPress Tag Cloud Widget

If you Google this topic, you’ll see that most of the posts that come up help you achieve what you’re looking for, but I couldn’t help but notice that most of them are doing it the wrong way. If you’re starting out with WordPress, there’s one thing you have to always keep in mind — never, and I mean never edit the WordPress core files. It’s a bad thing to do, all your changes will be lost during your next update and you’ll never figure out what you had done in the past and how to do it again.

There’s a 99% chance that what you’ve been trying to achieve by editing core files, is easily implemented without touching them. The remaining 1%, oh well, #blamenacin ;) Anyways, in this tutorial I’ll show you how to customize your WordPress tag cloud widget — change the number of printed tags, change the font sizing options and exclude a certain tag from the cloud. In this tutorial we will dig into the WordPress core files, but we will not edit them.

If you’re a WordPress theme or plugin developer, you shouldn’t be afraid of the core files, they’re one of the best resources (together with the Codex) where you can actually learn how to do things which are not clearly explained elsewhere. By reading them, you’ll be able to understand of how things work internally, and how you should adapt to the algorithms and techniques in your own projects. As the post title suggests, we’ll be working with widgets today, but before you start reading your core files, let’s see what tag clouds are all about.

Understanding the WordPress Tag Cloud

The tag cloud is not new to WordPress but definitely something you should consider using on your website or blog, especially if you use tags in your publications. The tag cloud gives a rough overview of what your content is all about, what you blog about the most. Tag clouds aren’t generally clicked on by users, although it’s still a good way to provide quick links to the archives.

WordPress comes with a built-in function for generating tag clouds called wp_tag_cloud, which in fact has received an update in 3.1 and now supports different taxonomies. This means that you can create tag clouds out of tags, categories and custom taxonomies you have defined. If you look at the function reference closely, you’ll notice that it accepts quite a wide range of arguments to customize the cloud, keep that page open for a while.

The Standard Tag Cloud Widget

Now forget about that function for a while, since you’ll not be using it, that would be too easy. Our goal today isn’t to output a customized tag cloud. Our goal is to customize the standard tag cloud widget that WordPress provides.

Right, there are numerous plugins out there that give you all the range of options in a new tag cloud widget, but what’s the point if you’re simply looking to exclude a couple of tags from the cloud, or bumping up the maximum font size? So let’s get cracking.

To customize something that’s built in to the core, you should start by examining how it works, so pop up your core files and look inside the wp-includes directory. You’ll get more familiar with how files are named in the core and where to look for what, but this time I’ll give you a tip — the file is called default-widgets.php. Open up the file in your favorite code editor or take a look at it in the WordPress trac. Each and every one of the default (or standard) WordPress widgets are defined in this file. Look for the class called WP_Widget_Tag_Cloud.

The widget method inside that class is the one responsible for output. You should easily spot the wp_tag_cloud function being called from within that method, and woah! There’s a call to apply_filters!

echo '<div class="tagcloud">';
wp_tag_cloud( apply_filters('widget_tag_cloud_args', array('taxonomy' => $current_taxonomy) ) );
echo "</div>\n";

This means that it’s something we can take advantage of outside the core using the widget_tag_cloud_args filter name, and as you can see, the taxonomy is passed in through the arguments, we shouldn’t forget to keep that.

Hooking into the Tag Cloud Widget

Enough with the core, hit close and make sure you don’t save any changes. We’re not editing the core files, remember? Now, in your plugin or theme’s functions.php file, all you have to do is add a filter to that filter name we found above and define the handler function. Like this:

add_filter( 'widget_tag_cloud_args', 'my_widget_tag_cloud_args' );
function my_widget_tag_cloud_args( $args ) {
	// Your extra arguments go here
	return $args;
}

As I mentioned, don’t forget to return the passed in arguments as I mentioned earlier. Note the commented line I gave, that’s the place where you would edit the $args variable which is passed on to the wp_tag_cloud function. So let’s try out a few things.

Changing the Number of Tags to Display

From the wp_tag_cloud it’s quite simple to figure out that the number key is responsible for the maximum number of tags to output. The default value is 45, so let’s change that to 20. Here’s how my handler function now looks:

function my_widget_tag_cloud_args( $args ) {
	$args['number'] = 20;
	return $args;
}

Simple as that! Let’s try out the font size.

Changing the Largest and Smallest Font Sizes

As the reference states, our keys are largest, smallest, and perhaps the unit. Let’s go for 18 pixels largest and 9 pixels smallest. Here’s how our handler function looks now, together with the number of tags reduced to 20 in the previous step:

function my_widget_tag_cloud_args( $args ) {
	$args['number'] = 20;
	$args['largest'] = 18;
	$args['smallest'] = 9;
	$args['unit'] = 'px';
	return $args;
}

Voila! Finally, let’s say we want to exclude one of the tags.

Excluding A Tag From The Tag Cloud

This might be a little tricky, but the thing to remember about the include and exclude keys is that they don’t accept strings, they work based on the terms IDs. It’s quite simple to figure out the ID for a specific term — browse to your admin panel, fire up the list of all post tags and hit on one of the tags to edit it. Look at the browser URL and you’ll notice a tag_ID variable, that’s your term ID.

I’ve no clue what your term IDs are, there really is no way to guess, so I’ve browsed through mine an figured out I want to exclude the one with the ID of 80 and one with an ID of 20. Here’s how I did it:

function my_widget_tag_cloud_args( $args ) {
	$args['number'] = 20;
	$args['largest'] = 18;
	$args['smallest'] = 9;
	$args['unit'] = 'px';
	$args['exclude'] = array(20, 80);
	return $args;
}

That’s all there is to it, really.

Conclusion

Tag clouds are not a difficult topic in WordPress and today’s lesson was primarily about how you should get comfortable with WordPress core and structure, and that you should never edit those core files. Although the tag cloud widget part might come in handy some day too ;)

Hope you enjoyed today’s post and thank you so much for reading. Feel free to tell us about your experience dealing with the WordPress core and the tag cloud widget too. Use the comment form section below to share your thoughts and don’t forget to subscribe to our RSS feed.