Today's tutorial: Dojo Tag Cloud Widget using dojo.data store
So I though it was time to post another Dojo widget tutorial. This time I have written a widget for displaying a tag cloud. Even though you could use it for any kind of links, the most common use is obviously tags from your blog or other website. The TagCloud widget is using dojo.data and any kind of store to display the tags. Let’s jump into some code shall we. In the bottom of this tutorial you will find links for downloading all the code.
First we need to add our core Dojo and dependencies to our JavaScript in the head of our HTML page.
<script type="text/javascript" src="/dojo111/dojo/dojo.js"
djConfig="isDebug: false, parseOnLoad: true, usePlainJson: true"></script>
<script>
dojo.require("dojo.data.ItemFileReadStore");
dojo.require("mydojo.TagCloud");
dojo.require("dojo.parser"); // scan page for widgets and instantiate them
</script>
You can see that we added the ItemFileReadStore, after that we have the topic of the tutorial: mydojo.TagCloud and last we added the dojo.parser so that we can create our widgets by HTML markup. You can see that the name space for my widget is mydojo.TagCloud. That means that I’ve created a folder named mydojo in the same folder as the dojo, dijit and dojox folders.
Now we add the dojo.data store and the markup HTML for our Tag Cloud widget inside our body.
<body>
<div dojoType="dojo.data.ItemFileReadStore" jsId="cloudStore" url="tagcloud.json" /></div>
<div dojoType="mydojo.TagCloud" store="cloudStore"></div>
<body>
You can see what it looks like in example 1.
The link above will give you the default TagCloud widget. If you look at the code, through Firebug naturally, you’ll see that it is made up of a DIV element with an unordered list, UL, inside. The list has all the tags from our dojo store with different sizes. Larger for tags with more values.
Most people want a tag cloud to look like a tag cloud though 
For that we need to add some style to our code inside the head tag.
<style type="text/css">
.TagCloud {
font-family:Arial, sans-serif;
font-size:0.8em;
width:350px;
}
.TagCloud ul {
padding: 0pt;
margin: 0pt;
}
.TagCloud li {
display:inline;
}
</style>
See example 2.
As you can see in the style classes above we declared a font and width inside a class named “TagCloud”. That class is always added to the div tag that the widget creates. That default class name can be changed and you can also add other classes that I will explain later. We also declared that any UL tag inside “TagCloud” will not have any margin or padding. That is because the browser automatically adds some margin and padding to unordered lists and we don’t want that for our tag cloud. Last in our style sheet we add the definition of our list item, LI. We want it to display inline and not be in a list format.
Lets add some more style to our tag cloud before I explain what attributes we can pass in to our widget. We add some more attributes to our existing classes and add two more rules.
<style type="text/css">
.TagCloud {
font-family:Arial, sans-serif;
font-size:0.8em;
width:350px;
padding: 2px;
border:1px solid #666666;
background-color:#EEEEEE;
}
.TagCloud ul {
padding: 0pt;
margin: 0pt;
text-align:center;
}
.TagCloud li {
display:inline;
white-space:nowrap;
line-height:1.7em;
}
.TagCloud a:link, .TagCloud a:visited {
color:#FF0000;
text-decoration:none;
}
.TagCloud a:hover {
color:#666666;
text-decoration:underline;
}
</style>
View it in example 3.
Tag Cloud Widget Attributes
There are a number of attributes we can pass in to change behavior and/or functionality of our widget. If we open up our widget JavaScript file we will see a number of variables at the top. You can actually change all of those by just adding attributes to our widget HTML code. They are documented inline in the code but lets look at a few of them.
//sizeDifference: Boolean
//If we should show larger font for more tags
sizeDifference: true,
//fontMaxSize: Integer
//The size of the largest tag in percent
fontMaxSize: 200,
//fontMinSize: Integer
//The size of the smallest tag in percent
fontMinSize: 100,
So we can choose not to have a difference in size on the tags. How would we add that? Let’s look at the example below.
<div dojoType="mydojo.TagCloud" store="cloudStore" sizeDifference="false"></div>
See what it looks like in example 4.
We have just added the sizeDifference attribute with a value of false to our widget code. Other then that it is the same code as example 3 above.
We can also choose to have bigger difference in size on tags. As you can see I’ve added the fontMaxSize attribute to our widget DIV tag.
<div dojoType="mydojo.TagCloud" store="cloudStore" fontMaxSize="400"></div>
Really large fonts in example 5.
I mentioned earlier that you can also add more style sheet classes besides the default class “TagCloud” to your widget. By adding the normal “class” attribute to our DIV tag. Classes will be appended after the “TagCloud” class. The default class can also be changed by changing the “baseClass” attribute.
What happens when the user clicks the tag? Well, since I don’t know what should happen because it depends entirely on what your tags represent and also on what kind of server the code sit on. In this blog, based on Wordpress, the tag when clicked would take you to a url that look like:
/index.php/tag/the_tag
So how do we do that? Well, one of the variables/attributes in our TagCloud widget is “clickFunction” with a default value of “tagItemClicked”. So you can add JavaScript funtion named “tagItemClicked” or pass in a new value to “clickFunction”. I’m going to show you the first way. Let’s add the following code to our JavaScript in the head of our HTML page.
function tagItemClicked(sTag){
alert("You clicked on " + sTag);
}
See example 6.
If you click a tag it will alert the tag. Not very useful so let’s change it a little to make it work on my blog.
function tagItemClicked(sTag){
location.href = '/index.php/tag/' + sTag;
}
Updated to example 7.
Two other very important variables that we can change in our widget are the names of the item value names in our data.store. Default are “name”, “slug” and “count” and you can obviously keep those. Many times however you might not have the luxury over what your Ajax (XHR) call will return, or you just don’t like mine. 
In that case you can change them by adding the attributes “tagAttr”, “slugAttr” and “countAttr”.
Below is the JSON i’ve been calling with the ItemFileReadStore in all our examples so far.
{items:[
{name:"ajax", count:15},
{name:"beth", count:2},
{name:"blog", count:4},
{name:"calendar", count:3},
{name:"calendar entries", slug:"calendar-entries", count:2},
{name:"Collaboration University", slug:"collaboration-university", count:14},
{name:"cu-2007", count:11},
{name:"demo", count:6},
{name:"dojo", count:31},
{name:"domino", count:20},
{name:"family", count:9},
{name:"google", count:2},
{name:"ibm", count:5},
{name:"lotusphere", count:11},
{name:"lotus quickr", slug:"lotus-quickr", count:27},
{name:"movies", count:2},
{name:"podcast", count:3},
{name:"snapps", count:30},
{name:"templates", count:17},
{name:"tutorial", count:11},
{name:"widget", count:4},
{name:"xhr", count:3}
]}
As you can see it uses the default “name” and “count” attributes for each item. If however that would be changed to “word”, “special” and “number” everywhere…
{items:[
{word:"ajax", number:15},
{word:"beth", number:2},
{word:"calendar entries", special:"calendar-entries", number:2},
...
{word:"xhr", number:3}
]}
…we would change our HTML markup to:
<div dojoType="mydojo.TagCloud" store="cloudStore" tagAttr="word" slugAttr="special" countAttr="number"></div>
What is the “slug” attribute you might ask. When a tag need a different call than it’s name you can add the slug attribute. If none is there it will just use the name attribute instead. In the example above the tag “calendar entries” has a slug of “calendar-entries” that way we can display one way but still link to the right URL.
Calling our widget with JavaScript
What if we wanted to do all this by JavaScript instead? Well Dojo widgets have this build in so all we have to do is code our HTML page a little different.
We can delete the reference to “dojo.parser” in our SCRIPT since we no longer are parsing HTML markup and we would add the following JavaScript.
function createTagCloud() {
var oStore = new dojo.data.ItemFileReadStore({
url:"tagcloud.json"
});
var oCloudDiv = dojo.byId('tagCloudDiv');
var oCloud = new mydojo.TagCloud({
store: oStore
},oCloudDiv);
}
dojo.addOnLoad(function(){
createTagCloud();
});
Then in our body we would add the following HTML.
<body>
<div id="tagCloudDiv"></div>
</body>
JavaScript version example 8.
I hope you enjoyed this tutorial and I would love to read your comments. Here you can download the Dojo Tag Cloud Widget (180). Happy coding. 
This year we are producing a few pre-conference session movies for 
