Building a Semantic Tag Cloud for Wordpress with Simple Tags plugin

Wordpress TagCloud

If you have any kind of website, and this website has some articles/posts, you probably has a tag cloud on it. If you have this kind of website and doesn't have a tag cloud, you should.

In this article I'm gonna introduce you to tags and tag clouds, show how Wordpress's default Tag Cloud's markup is and talk about Simple Tags, a Wordpress plugin that enhances its tags management UI and also generates its own enhanced Tag Cloud.

After that I'm gonna talk a bit about Semantic and Accessibility, show how these tag clouds are ugly in Semantic and Accessibility point of view, and show how we can improve Simple Tags's Tag Cloud using its almost overlooked core configs.

Introduction

If you don't know what tags, categories and taxonomy are, I'll give a small description.

Taking a PC file system as a base, we have files and folders on it right? In the same way we group our files inside folders so that related files go to the same folder, we can group related website articles inside categories. Each category has a major meaning, they are something like our website folders where we group our articles in a meaningful order.

Tags, on the other hand, can be seen as keywords. We take each article and see its most relevant words, words that are seen more often on it, and words that can best describe this article, and we list all those words as each article's tags. Tags are also meaningful, but they have a minor meaning, are more context depandant than categories and may also be found in higher numbers in each article/post.

Taxonomy is just a generic name, it is used because tags and categories are stored on a single table in the database, and on database level they are one unique element. And best CMSs also let us create more taxonomy types other than categories and tags, feeding website owners' criativity.

Another difference we can see between categories and tags, is that generally each article/post must (or should) be in at least one category, but must not have any tag if post author doesn't want it.

Ah and of course, a tag cloud is just a blob (at least visually...) of text with a lot of tags on it. Each tag has different letter sizes and colors, to represent the most and least popular tags.

Semantic Tag Cloud requirements

Well, now we all know what tags and tag clouds are, but why do we need better tag clouds than those we use actually?

We need better ones because current ones are Semantic and Accessibility weak! Mark Norman Francis (http://24ways NULL.org/2006/marking-up-a-tag-cloud) has written a very nice article showing top popular websites' tag clouds deficiencies and what a high quality tag cloud must have. You must read the whole article and see his exemples to understand my article, so go there and read it

Ok, as you've seen, what current tag clouds lack is the following:

• semantically list each tag inside a ul or ol, instead of just throwing an endless line of meaningless a links
• use class atribute instead of style to set tags sizes and colors
• Since screenreaders don't see CSS style sheets, we must use nother means of showing them how much popular each tag is

I'll add a criticism to Mark's tag cloud regarding accessibility. See his first exemple, it's already boring to see that list of tags, imagine somebody hearing that list, tag per tag, cliging Tab key to browse them. Now imagine a list of 50 or even 100 tags, all with the same context information repeating over and over and over again. Do we want to kill our blind visitors? Yes, because if we didn't want them to visit our website, we'd not build screenreader supported tag clouds to begin with!!

"For context information" matters we can change posts are tagged with by posts in, but for the amount of tags it would be harder. Taking an accessible menu as a base, insetad of a 1-deph list we could use nested list, so that most popular tags would be in first depths and least popular ones going to deeper lists. We could sort our base structure by post count, and then random each list if we wanted a random list.

Then we just set everything as display: inline and all tags will be shown linearly in main view, while screenreader visitors could just browse the main list if they wanted only those most popular tags, going deeper according to their interest.

But I'll leave this idea as a draft, at least for now. Maybe anybody implements it and share with us

Let's start working

Let's stop with the theory and go to practice. Let's start checking what we have available in Wordpress. It has a built-in tag cloud, but it sucks. Only option it offers is the widget title, and all it does is print a list of 45 anchors (a links). I used as an exemple my Consciência Planetária website, and take a look as one if its links:

<a href='http://ConscienciaPlanetaria.com/tag/carta-da-terra/' class='tag-link-76' title='1 topic' style='font-size: 8pt;'>Carta da Terra</a>

Yeah, nothing great, people prefere to share their tag cloud codes as plugins rather than offerring it to Wordpress core. So let's take a look on plugins, I'll use Simple Tags (http://wordpress NULL.org/extend/plugins/simple-tags/), which is the plugin I use to manage tags.

I added its widget to my site without any customization, to see what its default config gives us, and what I've got was also 45 tags marked up as a bunch of archors like this one:

<a href="http://ConscienciaPlanetaria.com/tag/carta-da-terra/" id="tag-link-76" class="st-tags t1" title="1 topics" rel="tag nofollow" style="font-size:8pt; ">Carta da Terra</a>

Well now we have a rel="tag nofollow", which at the same time gives us some semantic with tag and also some SEO with nofollow. But there is something really bad on it... that id="tag-link-76"! Why do we need an id for each tag?! As if an id for each tag being useless, it also prevents us from having 2 tag clouds on our site (we could have a smaller one in a sidebar and a larger one in the footer), because if they list the same tag we'll have an id duplication, which breaks our HTML spec! No way man, those id's must really get out!

Fortunately, Simple Tags has a lot of features behind its default config. Why its author doesn't use them as default on its widget tag cloud, I don't know. A simple CSS added to frontend would make it great.

Simple Tags' features

To see what Simple Tags is able to do we'll have to look at its code. Inside \simple-tags\2.7\simple-tags.client.php we have its main class where its core is located, and inside \simple-tags\2.7\inc\simple-tags.functions.php we are offered with an interface, a list of functions that let us call its singleton $simple_tags object without having to global invoke it everytime.

The function we'll use is st_get_tag_cloud( $args = '' ), it receives an array containing the tag cloud configs as parameter and calls $simple_tags->extendedTagCloud( $args = '', $copyright = true ), so let's take a look on how this method works!

What it does is set the tag cloud default configs, replace defaults by our passed configs (and also use widget configs over its defaults, so be careful if your're gonna use a widget and a custom tag clouds to not get the widget one's configs overwitting your custom ones!), and then do its magic. I won't explain the whole code, it basically uses those configs to query the tags list, and then calls $simple_tags->outputContent(...)to generate our list.

To show its features, the easiest way is taking a look on the tags list's configs, in its default:

<?php
		$defaults = array(
		'size' => 'true',
		'smallest' => 8,
		'largest' => 22,
		'unit' => 'pt',
		'color' => 'true',
		'maxcolor' => '#000000',
		'mincolor' => '#CCCCCC',
		'number' => 45,
		'format' => 'flat',
		'cloud_selection' => 'count-desc',
		'cloud_sort' => 'random',
		'exclude' => '',
		'include' => '',
		'no_follow' => 0,
		'limit_days' => 0,
		'min_usage' => 0,
		'inc_cats' => 0,
		'notagstext' => __('No tags.', 'simpletags'),
		'xformat' => __('<a href="%tag_link%" id="tag-link-%tag_id%" class="st-tags t%tag_scale%" title="%tag_count% topics" %tag_rel% style="%tag_size% %tag_color%">%tag_name%</a>', 'simpletags'),
		'title' => __('<h4>Tag Cloud</h4>', 'simpletags'),
		'category' => 0
		);
?>

We can see that some of its configs are just a copy of Wordpress's wp_tag_cloud() configs. wp_generate_tag_cloud() is not used in this part of code, so as I've verified, it is not used to query our taxonomies (that's the right term because it allows is to list categories together with tags! as long as I know Wordpress core doesn't provide this feature). It seems that Simple Tags's author indeed used wp_tag_cloud() configs as a base his own ones, to help us so that we have fewer configs to memorize. Thanks dude for the hard and great work!!!

I'll share what I know about each of these configs. You can see Wordpress ones in Wordpress Codec (http://codex NULL.wordpress NULL.org/Template_Tags/wp_tag_cloud).

• size: defines if tags will have different font-size, determined by smallest, largest and unit. If it is true, %tag_size% (we'll see these template tags soon) is replaced by the size value of each tag, if it is false, %tag_size% is removed.
• color: same as size, a true/false value defining if tags will have a color gradient, defined by maxcolor and mincolor.
• format: it has 3 possible values, the same of wp_tag_cloud(). That's cool because we could receive a PHP array storing all tags and use our own code to markup them. If we've already done that with wp_tag_cloud()and had a code that properly formatted a tag cloud, we could just replace wp_tag_cloud() by st_get_tag_cloud(), because their array outputs are compatible. But for today we'll let Simple Tags generate the XHTML markup for us.
• cloud_selection: This is a new one, it is the same of widget interface's Tags selection. We can gather tags based on alphabetical A-top or Z-bottom ones (not much useful, but it's nice to have the feature), most or least popular or random. If you have a great amount of tags and they are balanced used, you may wanna use random, but if you'd rather use only and always those most popular ones, count-desc is for you.
• Once Simple Tags had selected its tags based on former config, it uses cloud_sort to define how they will be sorted. We can sort tags alphabetically, by how many times they are used (popularity, most/least used), or sort them randomly. I really suggest using random here, otherwise our tag cloud will always look the same. random gives it a 'dynamic' look.
• no_follow is nice, it defines (with values of 0 or 1) if each tag link will have a rel="nofollow" attribute. Google asks us to not use nofollow in internal links (because Google has a fair way of dealing with duplicate content, understanding that archive pages are not meant to con it), but it also doesn't hurt as long as I know. Beyond nofollow, Simple Tags also adds a tag property, as in rel="tag", which is great for SEO, but it is only added if we are using permalink in our Wordpress website.
• limit_days is used to limit the usage of only tags that had been seen in posts that are at least this amount of days old, it is converted to year-month-day format and then used in SQL query to define tags popularity. Maybe 3 years ago we very frequently used a bunch of tags in a lot of posts and they are not seen anymore in more recent posts, so their time has come and we don't want them taking place of less used but more recent tags.
• min_usage pulls out from our tags list all tags that are less frequent than this amount. That's useful when we'd rather have a smaller tag cloud than having a bunch of 1-post tags being listed, it also allows us to set a higher number of tags to be queried without worring of having dens of small tags and just a few font-size-bigger ones.
• category is a strange option, I'm not sure but as I've seen, it seems that as in limit_days, it removes from the query any post inside categories listed in category, and it interferes in tags popularity. It seems we should use a simple string listing all categories we wanna pull out, separated by space, they are converted to an array or something like that, I couldn't understand and also didn't test this option.
• notagstext lets us choose what text is used when no tags is available, being it because our website uses none or because our options had pulled out all of them and none had survived, better leave it as default because it uses localization, or change it if you wanna replace with some funny/freak text for when all your tags are gone.
• title adds a string just before our ul list starts, its default value is <h4>Tag Cloud</h4>, wich normally adds a header and then starts the list in the next line, but everything depends on how we styled our tag cloud. If we don't want Simple Tags adding anything before our marked up list, we can use an '' empty string to it, or a 'false' string also works.
• You may have seen the $copyright parameter just after $args in $simple_tags->extendedTagCloud( $args = '', $copyright = true ), it is very polite of Simple Tags author to let us remove it from its generated tag cloud. What this option does is add an HTML commented text saying that this tag cloud was generated by Simple Tags and where the plugin can be downloaded, this copyright text is not rendered by browsers, so I suggest giving credit for its work and leaving the copyright in its place.

And we've finally come to the infame and on the same time great xformat, the config option that allows us to format our tags almost anyway we want, and one of the culprits for Simple Tag's defaut tag cloud being so weak! Here's its default value:

'<a href="%tag_link%" id="tag-link-%tag_id%" class="st-tags t%tag_scale%" title="%tag_count% topics" %tag_rel% style="%tag_size% %tag_color%">%tag_name%</a>'

As you can see, it uses symbols surrounded by %, that will be replaced by their equivalent code. They are all self explanatory, just take a look on the %tag_scale% symbol, it flags all tags on a scale from 1 to 10, being 1 those tags less frequent that are seen in fewer posts (and have smaller font-size), and 10 those most frequent and biggest ones. It doesn't matter how many tags and how many posts they are seen in, Simple Tags uses an algorithm to always scale them from 1 to 10. And it is using this scale that we'll be able to use class instead of style to format our tag cloud.

Note also the id attribute, that impedes us from using 2 tag clouds because of HTML spec that doesn't allow 2 elements with the same id on the same document, and also the style attibute that sets tags size and color even though we have the class attibute present, that unfortunately is not used in default.

Building our Semantic Tag Cloud

Let's start working with xformat and make it better. We'll remove id to let us free to use how many tag clouds we want, and also style because now we'll use apropriate CSS to style our tags. We'll also follow Mark Norman Francis's Accessibility ideas. But before that, let's have a clear list of what we want for each tag in the tag clous:

1. a way to uniquely refer to each tag, and that's not as obstructive as an id attibute
2. a small and concise text to be read from screenreaders, but hidden from normal browsers
3. a scale-based class attribute where we can securely set each tag's font-size, color, and any other style our criativity requires
4. a title attribute that helps us in SEO and on the same time has a nice and meaningful text for our visitors
5. and of course, the tag name inside the a link that is our tag cloud's base visual structure

Of those 5 requirements, only 3 and 5 are properly achieved by Simple Tag's default xformat. I've tried to improve it, and here's what I've got:

<span class="st-tag-%tag_id%"><span class="tag-cloud-accessibility">%tag_count% posts in </span><a href="%tag_link%" class="st-tags t%tag_scale%" title="%tag_count% posts are tagged with \'%tag_name%\'" %tag_rel%>%tag_name%</a></span>

Starting from its middle, id and style are gone, class I decided to leave its default in case somebody already has style for it and we can keep compatibility (even though any attempt to do so would have been overwritten by style. And speaking of them, now that %tag_size% and %tag_color% aren't present anymore, all option configs related to size and color are obsolete regardless of what is set on them.

Outside a link you can see a small text surrounded by a span with tag-cloud-accessibility class, so that we can off-left it from browser screen and leave it for screenreaders. Note also that a's title has a larger text, including tag's name, since (I believe) screenreaders don't read it.

And to finish it, we have another span surrounding the whole tag text and link, with a class that has the tag's (database) ID. I wanted to also use tag-slug as a base for referencing tags, but unfortunately Simple Tag doesn't have this option... be sure to not change your taxonomies' database ID on a database move if you are gonna style any of them based on this ID!

What's important here is that, having this span surrounding everything else, we can easily target anything inside using simple CSS. In exemple, if we wanna highlight a specific tag (let's say it has a database ID of 54) from all others with a special color or even forcing it to have bigger font-size, we can just use:

The ideal would bethis class being inside each li, and not in a span, but again Simple Tags doesn't give us access to those lis. And talking about it, Simple Tags also doesn't allow us to choose for ol, we are forced to remain only with ul. If we set tags to be sorted randomly, ul is enough for us, but having other sorting options, if we choose any of them we'd require ol for best semantics...

Ok, our tags are now way better than before. To surround them in an ulunordered list all we must do is set format option to list, it will give us all lis we need and surround them in a pretty ul. Ah if we could just receive them without the list delimiter so we could add our own, with its own custom and pretty class and id... well, we can't, so now we'll need to surround the whole Simple Tags output on a div, that preferably has a default class attibute, that can be changed as required by our criativity, and optionally an id atrribute that would be omitted as default but would allow us to have one without needing to surround everything again on another div.

Before showing the finished work (well, it is just below, you had probably already peeped on it huh you agog!), one last advise. Always, and I say always, when you develop a plugin or a theme, use a prefix on your functions and on anything you belive may conflict with anything else! This prefix should be your plugin/theme folder, because it is unique. Please never forget to use prefixes!!

And now I present you... my beloved Semantic Tag Cloud!

<?php
 function prefix_semantic_tagcloud($args = ''){
 
	$defaults = array(
	'prefix_class' => 'semantic-tag-cloud stc',
	'prefix_id' => '',
	'prefix_stcopyright' => true,
    
	'size' => 'false',		// useless
	'smallest' => 8,		// useless
	'largest' => 22,		// useless
	'unit' => 'pt',			// useless
	'color' => 'false',		// useless
	'maxcolor' => '#000000',	// useless
	'mincolor' => '#CCCCCC',	// useless
	'number' => 200,
	'format' => 'list',
	'cloud_selection' => 'count-desc', // most popular ones
	'cloud_sort' => 'random', // tags are sorted randomly
	'exclude' => '',
	'include' => '',
	'no_follow' => 1,
	'limit_days' => 0,
	'min_usage' => 2,
	'inc_cats' => 0,
	'notagstext' => __('No tags.', 'simpletags'),
	'title' => 'false',
	'category' => 0,
	'xformat' =>'<span class="st-tag-%tag_id%"><span class="tag-cloud-accessibility">%tag_count% posts in </span><a href="%tag_link%" class="st-tags t%tag_scale%" title="%tag_count% posts are tagged with \'%tag_name%\'" %tag_rel%>%tag_name%</a></span>'
	);
	
	
	$args = wp_parse_args( $args, $defaults );
	
	echo '\n<div';


	if( !empty($args['prefix_id']) && !isBlank($args['prefix_id'])){
		echo ' id="' . $args['hksmtc_id'] .'"';
	}
 
	if( !empty($args['prefix_class']) && !isBlank($args['prefix_class'])){
		echo ' class="' . $args['prefix_class'] .'"';
	}

	echo '>\n';

	global $simple_tags;
	print $simple_tags->extendedTagCloud($args, $args['prefix_stcopyright']);


	echo '\n</div>\n';

}
?>

It starts with a default array, with small changes from Simple Tags's one. I've left size and color just to remember they are now useless since their symbols are not used anymore. I've set default tags number to 200, because I use it in the footer, set no_follow active. And also set min_usage to 2, so that I don't end up with a bunch of 1-post tags blobbing my tag cloud, with this config only tags that are present in at least 2 posts will be listed.

Also note 3 new option configs there, they are used to set container div's id and class (note their defaults). I use this class to define all tag cloud's stylings, so if for some reason I'd want to use another stylings for a second or even third tag cloud, I'd just need to change this class parameter and all stylings would change. Note I used 2 classes, semantic-tag-cloud is a larger and easier to understand class, while stc is a smaller one so that my CSS gets smaller.

Note again that xformat as I said has no id inside it, and by default this code generates no id at all, it can be safely added anywhere and how many times I want without setting any config that I won't worry with XHTML validation, and indeed we'd not need any id at all. ids only differ from classes in the matter that they are unique on a document, so that with JavaScript we can use document.getElementById() and be sure to receive exactally what we want, and also to use it as http://url.com/#id to be sent directly to that point when our browser loads the document. CSS is perfectly able to style using class only, using id also only when we want to specifically style something unique on the document, whose styles wisely will have precendance over conflicting class ones.

The tird custom option config is stcopyright, just to support Simple Tags's copyright option, but as I've said it deserves that string.

After that I use $args = wp_parse_args( $args, $defaults ); to merge arguments passed to the function with default ones. Then I add the container div and its id and class. $simple_tags->extendedTagCloud() is called and its output is printed, followed by closing our main div.

Of course! let's take a look on what our semantic tag cloud generates! In the following code I show how the function was called (I've set number=1 so that I can show the whole code and on the same time give and exemple of how may be done), and its output just after.

<?php prefix_semantic_tagcloud('min_usage=0&prefix_id=prefix-tag-cloud&number=1'); ?>


<div
 id="prefix-tag-cloud"
 class="semantic-tag-cloud stc"

> 

<!-- Generated by Simple Tags 1.6.6 - http://wordpress.org/extend/plugins/simple-tags -->
	<ul class="st-tag-cloud">
	<li><span class="st-tag-55"><span class="tag-cloud-accessibility">3 posts in </span><a href="http://ConscienciaPlanetaria.com/tag/universo/" class="st-tags t1" title="3 posts are tagged with 'universo'" rel="tag nofollow">universo</a></span></li>
</ul>

</div>

Pretty huh? Note how div's id and class are in a strange position, but that's still valid. Also note that having only 1 tag, it is scaled as 1! interesting.

Let's go now for the grand finale, style it as a proper tag cloud!

Styling our Semantic Tag Cloud

Remember that Simple Tags scales all tags from 1 to 10. So for their size we must define minimum and maximum sizes, and then subtract them and divide by 9: interval = (maximum - minimum) / 9

Having this "interval" value, we just add it for each scale and we'll have their sizes. I used OpenOffice Calc for that. On my tests I belive that a minimum of 0.7em and maximum of 4em gives me some nice sizes.

Now, for colors, we'll have some harder work. You can see how Simple Tags does it by searching for getColorByScale in its code. The problem is that colors are represented as a single value, but in fact they are arrays of 3 values in RGB (4 values when transparecy is used in RGBA), and each of them must be calculated separately because for exemple a final light green may have a high blue.

I just used FireFox's ColorZilla extenssion to find a cool color, and it also gives separated and decimal RGB values, shortcutting a lot of work. I used Calc with the same algorithm used for sizes, and then passed each RGB value for each color back to ColorZilla, finally receiving the final color.

I've chosen to use hyperlink's default color, blue, for my default tag links. Darkest blue received #00016F, and for lightest blue I've chosen #0E1B7D. The algorithm for calculating colors is a bit complex, so I'll show tables I used for it. Remember that original decimal color were picked from ColorZilla (you can use anything that converts each 2 color string numbers to decimals, in exemple Red value in #0E1B7D is 0E), and then for each scale color we must bring back each RGB color to ColorZilla and it will give us that correspondent HTML color code.

These tables are copies of Calc ones, note I added their coords too.

Tag Cloud minimum and maximum color values

Color scales calculation formules

And that's it, ugly but works! Below is the final CSS, that styles our tag cloud!

And we're done, finally! Now we have a pretty, nice looking, and also semantic Tag Cloud. Visitors will love it, Search Engines will love it, screenreader visitors will love it, HTML valodators will love them, and we'll love it!!

(http://img260 NULL.imageshack NULL.us/img260/8890/tagcloudsemantic NULL.png)

Thanks for reading till the end, add critics and suggestions on comments, and see ya next time!