Jul 292008

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.


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.



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 :lol: For that we need to add some style to our code inside the head tag.



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.



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.

[code=”javascript”]//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,[/code]

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.



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.



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:


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.

[code=”javascript”]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.
[code=”javascript”]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. :cry: 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.

{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…

{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:



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.

[code=”javascript”]function createTagCloud() {
var oStore = new dojo.data.ItemFileReadStore({
var oCloudDiv = dojo.byId(‘tagCloudDiv’);
var oCloud = new mydojo.TagCloud({
store: oStore


Then in our body we would add the following HTML.



JavaScript version example 8.

I hope you enjoyed this tutorial and I would love to read your comments. Here you can download the [download#1]. Happy coding.  :roll:

Jan 282008

At Lotusphere in my session BP212: The Great Code Giveaway: “Beyond Cool” I showed a couple of widgets and a Grid based on the Dojo Toolkit. I’m going to show you how I did those in a couple of articles the next few days. Instead of going through the code line for line I’m just going to highlight some of the changed variables and code. All the code for these examples and demos can be found here.

Extending Dojo code

One of the really powerful things you can do with a large toolkit like Dojo is that you can extend a widget/class instead of having to change the underlying code in the toolkit itself. Instead of having to write all the code for your class you just extend an existing class and change the functions/variables you need to. You can also add your own variables and functions. Extending Dojo code is really easy. You create your own JavaScript file and “require” the existing class/widget.

dojo.declare("my.new.Widget", dijit.widgetToExtend, {
variablesToChange: "myNewValue",
functionToChange1: function(arg1){
//New code
functionToChange2: function(arg1, arg2){
//New code

In the example above we have extended a widget class called “dijit.widgetToExtend”. You would copy this JavaScript in a file named Widget.js inside a folder structure of “/my/new/” located parallel to the dijit, dojo and dojox folders. There are other places you can put your code but this is the simplest.

Using dojo.data

What is dojo.data?
Dojo.data is a uniform data access layer that removes the concepts of database drivers and unique data formats. All data is represented as an item or as an attribute of an item. With such a representation, data can be accessed in a standard fashion.

Ultimately, the goal of dojo.data is to provide a flexible set of APIs as interfaces that datastores can be written to conform to. Stores that conform to the standard interfaces should then be able to be used in a wide variety of applications, widgets, and so on interchangeably. In essence, the API hides the specific structure of the data, be it in JSON, XML, CSV, or some other data format, and provides one way to access items and attributes of items consistently.

The great thing about dojo.data stores are that they use a predefined way of getting/setting/updating code in the store. Whoever writes code for widgets that use stores does not have care about where the underlying data is located. It could come from a MySQL database, a XML file on the file system or now a Domino view.


I’ve added three variables to this class. You see them below with their default value.

parseTypes: false,
dateFormatLength: "short",
handleAsJSON: true,

parseTypes: Parses all view data into it’s correct format. Numbers become floats, dates become locale dates. Locale dates are dates that show up in the format that the current browser language want to show them.
dateFormatLength: If parseType is true, then show the date in this “length”. Can be long, short, medium or full.
handleAsJSON: Default is that all data from the Domino view is returned with JSON using the “&OutputFormat=JSON”. If you set this to false all data is retrieved using XML instead. JSON was not implemented on the Domino server until version 7.0.2 so if you use a server prior to this you need to set this variable to false.

There are five functions I want to mention briefly.

_filterResponse: Used for parsing view data in JSON format to the required format for a store.
_filterXMLResponse: Used for parsing view data in XML format to the required format for a store.
_returnColumnValue: Helper function to get the value for a specific object. Used from _filterResponse.
_returnEntryValue: Helper function to get the value for a specific XML node. Used from _filterXMLResponse.
_returnDateTime: Helper function to format the Domino date string to a dojo.date.locale.

That’s it for this time. Next time we’ll look at domino.form.ComboBox and domino.form.FilteringSelect that both use the domino.data.ViewStore. Happy coding.