I’ve been in San Francisco for about a week now. I know this shouldn’t have come as a surprise, but let me state the obvious. San Francisco is different than Raleigh. HTML5 should include a <DUH> element for assertions like that, but I must say, I did not fully prepare myself for the lifestyle changes associated with such a move. It’s like my life has been passed through a series of 1-to-1 substitutions. Let me see if I can illustrate this through a series of examples, showing off one of my favorite Dojo utilities: dojo.string.substitute.

Substitutions

Have you ever written JavaScript that injects values into the middle of a string? Did you slice, substring, and RegExp your way to victory? You probably did. Unless great care is taken, this approach is fragile and produces code that is difficult to read. Dojo helps solve this problem via an incredibly convenient utility for performing parametrized substitutions on a string, dojo.string.substitute. Let’s look at a quick example.

In this form, dojo.string.substitute allows you to pass it a string with numbered parameters, and an array whose indices correspond to those parameters.

(In all of the subsequent examples, be sure to dojo.require("dojo.string") to gain access to the substitute function).

var template = "In ${0}, Sweet Tea is ${1}";

var raleigh = dojo.string.substitute(template,
    ["Raleigh",
    "abundant and plentiful."]),

var sf = dojo.string.substitute(template,
    ["San Francisco",
    "no where to be found. I'm pretty sure it is illegal."]);

console.log(raleigh);
console.log(sf);

Output

In Raleigh, Sweet Tea is abundant and plentiful.

In San Francisco, Sweet Tea is no where to be found. I'm
pretty sure it is illegal.

Objects as Variables

The second argument to dojo.string.substitute can also be an object. In this case, the variables in the template correspond to the property names of the supplied object.

var template = "Autumn clothing layers for ${city}: ${clothingList}";

var raleigh = dojo.string.substitute(template,
    { city: "Raleigh", clothingList: "Hoodie, T-Shirt, Pants" });

var sf = dojo.string.substitute(template,
    { city:"San Francisco", clothingList: "Rain Coat, Coat, Puffy Vest, Hoodie, Long-Sleeve T-Shirt, Short-Sleeve T-Shirt, Pants, Shorts, Speedo (Optional, but better to be safe)"});

console.log(raleigh);
console.log(sf);

Output

Autumn clothing layers for Raleigh: Hoodie, T-Shirt, Pants

Autumn clothing layers for San Francisco: Rain Coat,
Coat, Puffy Vest, Hoodie, Long-Sleeve T-Shirt,
Short-Sleeve T-Shirt, Pants, Shorts,
Speedo (Optional, but better to be safe)

Nested Objects

When using objects to specify variable values, it is not necessary to use top-level properties. You can use plain ol’ JavaScript dot notation to specify properties nested within objects.

var template =
    "Number of naked people I saw in public in ${nakedPeopleDesc.city}: ${nakedPeopleDesc.count}.";

var raleigh = dojo.string.substitute(template,
{
    nakedPeopleDesc:
        {
          city: "Raleigh",
          count: "Zero"
        }
});

var sf = dojo.string.substitute(template,
{
    nakedPeopleDesc:
        {
            city: "San Francisco",
            count: "Four. And that was just this morning"
        }
});

console.log(raleigh);
console.log(sf);

Output

Number of naked people I saw in public in Raleigh: Zero.

Number of naked people I saw in public in San Francisco: Four.
And that was just this morning.

Your friend in i18n

Probably the most useful case for dojo.string.substitute is when specifying externalized strings in your i18n bundles. (If you aren’t familar with internationalization in Dojo, see my article on the subject). Let’s say you have something like this. This function returns a string to display a greeting to a user, informing them of their unread messages count.

function getGreeting(nameOfPerson, unreadCount) {
   return "Hello, " + nameOfPerson + ". You have " +
        unreadCount + " unread messages.";
}

When it comes time to externalize the string returned by the above function, how would you go about doing it? One option is to slice it up into multiple strings and add each string as an entry in your i18n bundle. That will work fine for English, but what about other languages? I’m no linguist, but I bet there are languages where unreadCount will make more sense in a different context than in between “You have” and “unread messages”. You are making the lives of your translation team more difficult by adopting this slice n’ dice strategy. The translator will have to first recognize that your multiple strings are part of the same message, and then heroically mash them into something that makes sense. Translators are a clever bunch, and they will figure it out, but why put them through the trouble? The more elegant solution to this problem is to externalize a template like this:

"Hello, ${nameOfPerson}. You have ${unreadCount} unread messages."

Now your translators have a single string to work with, and it’s a much easier task to rearrange that string in a manner that makes sense for a specific language. This article on developerWorks demonstrates an example of how to create a mixin that automatically delegates to dojo.string.substitute. Cool stuff, definitely worth a read.

Conclusion

dojo.string.substitute isn’t an earth-shattering API, but used effectively, it can clean up some of the less-than-beautiful string manipulation lurking in your codebase. And in an i18n context, it is absolutely essential.

Wish me luck in San Francisco; I’m doing a decent job of adjusting. Oh, except for one thing. Did you know that NFL games start at 10:00am out here?! That’s just silly.

Getting YQL Data Into Your Page

The coolest thing about YQL is how easy it is to get this great data into your app. Historically speaking it has been a pain to do mashup style apps with JavaScript due to the fact that browsers make it all-but-impossible to invoke AJAX requests across domain boundaries. YQL uses a clever technique known as JSON-P to work-around these cross-domain restrictions. JSON-P utilizes the fact that browsers do allow src attributes of script elements to be cross-domain. Thus it’s perfectly fine to include a script element with a Yahoo! domain in your page. Here is what that looks like for the Twitter query that I linked to earlier.

<script type="text/javascript"
src="http://query.yahooapis.com/v1/public/yql?q=select%20*%20from%20twitter.search%20where%20q%3D'%23dojo'%3B&format=json&diagnostics=true&env=store%3A%2F%2Fdatatables.org%2Falltableswithkeys&callback=cbfunc"></script>

The JavaScript that the above script element returns to us consists entirely of a block of JSON data wrapped in a function invocation:

cbfunc({
 ...
  "results": {
   "results": [
    {
     "to_user_id": "null",
     "text": "Understanding Widget - The dojo toolkit http://ow.ly/5kMmW #dojo",
     "id": "82046157043408896",
     "from_user_id": "2632678",
     "geo": "null",
     "iso_language_code": "en",
     "to_user_id_str": "null",
     "source": "<a href="http://www.hootsuite.com" rel="nofollow">HootSuite</a>"
    },
...

So, if we define a function in our page with the same name as the invocation supplied by YQL, that function will be called and passed the JSON ‘payload’:

// Somewhere in our page, above the YQL script element.
// This function must be called 'cbfunc' as that is the
// function that the YQL-returned JavaScript is calling
function cbfunc(yqlData) {

    // Do something cool with yqlData
    // ...

}

We now have a page that can consume data from Twitter. And we are doing it all client-side! As you can probably tell, access to great data with no server-side setup makes me a happy developer.

Using Dojo to Execute Dynamic YQL Queries

Using YQL as demonstrated above is cool but also has the limitation that your query to YQL is completely static. Sure, the #dojo hashtag is interesting, but perhaps we want to build a user interface that allows a user to choose a different hashtag to search. Since JSON-P requires that we include our query via the src attribute in a script element in the page, providing the ability to do dynamic queries requires us to dynamically inject script elements. This sounds tricky, but don’t be scared, we have Dojo. Dojo provides an API called dojo.io.script that makes dynamic script element injection easy. But an even slicker way of invoking YQL via Dojo is by using this module that I found on GitHub. It abstracts away the usage of dojo.io.script, and let’s us interact with YQL at the ‘query’ level. Using this module, we can write code like this:

function doTwitterSearch(searchTerm) {
  var query =
    "select * from twitter.search where q='" + searchTerm + "'";
  dojox.yql(query, {
    load: function(yqlData){
      // yqlData is the YQL JSON payload, do something neat with it
    ...
    }
 });
}

If that doesn’t strike you as cool, I’m sorry, but I don’t think that we can be friends. To use this module, download a Dojo Source Build and then plop the files from the GitHub repo into the dojox folder.

With those files in place, we can construct a page like this. This page loads Dojo, requires our dojox.yql module and demonstrates a simple YQL query to fetch the weather in Raleigh:

<!DOCTYPE html>
<html>
  <head>
  <meta charset="utf-8">
  <title>YQL and Dojo</title>
</head>
<body></body>
<!-- Include dojo.js -->
<script type="text/javascript" src="dojo/dojo/dojo.js"></script>

<!-- dojo.require the YQL module from GitHub -->
<script>
    dojo.require("dojox.yql");
</script>

<!-- Execute a query -->
<script type="text/javascript">
dojo.ready(function(){
  var query =
    "select * from google.igoogle.weather where weather='Raleigh'";
	dojox.yql(query, {
		load: function(weatherData){
		  console.log(weatherData);
	    }
	});
});
</script>
</html>

OK this is fun. But, I have a job.

You may be wondering if YQL has any real usage outside of Hack Nights. It does. The area of day-to-day software development that YQL really shines is the all-important product demo. Almost all demo’s involve the use of ‘dummy’ data. Demo’s are often done at the prototype or proof-of-concept stage of a project and at this point, there likely isn’t any real data to be had. When you find yourself needing some dummy data, you have two basic strategies to choose from:

• The Boring Strategy Dummy up some simple data and in-line it into your app. Don’t think too hard about this. Just create an array of Employees or something.
• The Fun Strategy Put some thought into what data might be interesting for your demo. Use YQL to fetch this data. This will only take slightly more time than The Boring Strategy.

The Fun Strategy is always better. I’ll show you what I mean. Click the button below to add a few dummy ‘Employee’ records to the table.

Add Employee

Yawn. OK, now click this button a few times. It queries Flickr for photographs of animals classified in the Order Rodentia, sorted by ‘Interesting-ness’.

Add Interesting Rodent

How many employees did you add? And how many rodents? I bet you’ve got about 3 employees, and about 3 dozen of God’s more fluffy creatures. The point that I’m trying to make here is that all data are not created equal. Your demo will be much more compelling if you give your audience something that makes them smile. Remember, people expect that your talk is going to be boring; it is a software demo after all. If you can beat the odds and grab people’s attention in the early going, they will stay engaged throughout the entirety of the demo, and you stand a much better chance of driving home whatever point it is that you are trying to make.

There’s a reason that most people use simple, hard-coded data in their demo’s. There was a time when using interesting data was simply not worth the effort. It usually involved janky server-side code that did something nefarious like scrape the HTML of a Yahoo! or Google property. YQL eliminates that hurdle and makes it dead-simple to pull fun data into your apps.

An Example of a YQL-Driven App

A few months ago, I used this exact technique for a personal project involving stock quote data. I’ve always loved quirky data visualizations, and for as long as I can remember I’ve had this idea for a visualization of stock quotes using fish. (Yes, I am crazy). I call it QuoteBowl. The basics of QuoteBowl involve a portfolio of stocks with each stock symbol in the portfolio represented by a goldfish in a fish bowl. If the stock is up on the day, the fish is rendered in a green color. If the stock is down, the fish is red. From there, the possibilities for fun visualizations are limitless. You could have different types of fish for different classes of stocks. You could draw the fish bigger or smaller depending on how much the stock was up or down. You could make the fish turn over and float upside down if the stock fell more than ten percent, etc, etc. I took a couple weekends and got a decent start. Check it out for yourself at quotebowl.com. Add some fish. It’s fun!

Here is the code that drives the data. I am using the Yahoo! Finance YQL service to fetch quotes on the symbols that a user has added to the fish bowl. The symbols are stored as an array of strings called userSymbols:

var query =
  'select symbol, LastTradePriceOnly, ChangeRealtime, ChangeinPercent from yahoo.finance.quotes where symbol in (' + userSymbols.join() + ')',

dojox.yql(query, {
  load: function( quoteData ) {
    // Add/Update the fish
  }

Conclusion

Software Demo’s are serious business. Everyday millions of dollars change hands, or don’t change hands, depending on how well a particular software demonstration went. That is not to say that every demo is mission critical, but regardless, the ability to give a great demo is a skill that every engineer should aspire to have. Given the right situation YQL may be the perfect tool for giving your demo the extra splash of flavor that it needs. Happy Demo’ing, and may all your fish be green.

Mustang Sally

Let’s use dojo.declare to specify a ‘class’ for an Automobile. This Automobile will have five instance variables and zero class (static) variables. The Automobile will have two String variables for its make and model, a Number variable for its year, an Array variable for a list of options, and an Object variable to describe its engine. One might think that a sensible way to declare this type would be something like:

dojo.provide("machines.Automobile");

dojo.declare("machines.Automobile",  null, {
	/* summary:
	 * 		VROOOOM!
	 */

	make: "",
	model: "",
	year: null,				// YYYY
	options: [],
	engine: {
		horsepower: 0,
		size: 0
	}

	//...

});

Some of these instance variables are declared properly, but a few aren’t. Can you guess which ones are a problem? We’ll need to create an instance of our class to try it out. But first lets add a print() function to our “Automobile” class for convenience sake:

	print: function() {

		// Dump the properties into the console
		console.log("%s %s %s. %s. %s hp, %f L."
				,this.year
				,this.make
				,this.model
				,this.options.toString()
				,this.engine.horsepower
				,this.engine.size
		);
	}

Let’s write some code to bash this ‘class’ around a bit. Let’s create an Acura Integra with 160 horsepower and a 1.7 Liter engine. We’ll then call print on the Integra. Next, we’ll do the same for the 127 horsepower Honda Civic. Lastly, we’ll call print again on the Integra.

	// Make a car
	var teg = new machines.Automobile();

	// Bring in the competition
	var civette = new machines.Automobile();

	// Set some properties on the first car
	teg.year = 1992;
	teg.make = "Acura";
	teg.model = "Integra";
	teg.options.push("Sunroof");
	teg.engine.horsepower = 160;
	teg.engine.size = 1.7;

	teg.print();

	// Set some properties on the second car
	civette.year = 1998;
	civette.make = "Honda";
	civette.model = "Civic";
	civette.options.push("Power Steering");
	civette.engine.horsepower = 127;
	civette.engine.size = 1.6;

	civette.print();

	// How's the teg doing?
    console.log("\tAfter setting the properties on the Civic, let's check back in on the Acura...");
	teg.print();

The output in Firebug’s console looks like this:

Hold your horses! Who swapped the Integra’s motor for the Civics’?! Problem? Indeed! Properties of the first car were overwritten by the second. Notice that the only properties that were overwritten were those that were instantiated as an array or object. So, if you guessed earlier that options and engine were the troublesome fields, you shouldn’t be reading this tutorial as you are a Dojo genius! The moral of the story is to be wary of instantiating properties as types other than the simple string, number, or boolean. Any fields declared in-line as complex objects will be treated as ‘static’ properties shared between all instances of that type.

This is How We Do It

If you would like to use a complex object as a field, hope is not lost. The proper way to do this is to set the variable to null initially, and then instantiate it in your type’s constructor function like so:

//...
	make: "",
	model: "",
	year: null,				// YYYY
	options: null,
	engine: null,

	constructor: function() {
		this.options = [];
		this.engine = {
				horsepower: 0,
				size: 0
		};
	},
//...

But hey, don’t hate on statics just yet! The concept of static class properties can be very useful. In our example, let’s assume that every Automobile had a standard set of options that was identical for each (A/C, cruise control, sunroof, etc) and we wanted to create an enumeration of these options. This would be an ideal candidate for a static array. The key to effective use of dojo.declare is to avoid accidentally creating a static variable when an instance variable is intended. Another important skill is to recognize when you have made this mistake. It is very easy to make and even veteran Dojo-slingers do it. If during a debugging session, you ever encounter a scenario where the properties of one instance of a dojo.declare‘d type is trampling another’s, you should immediately think ACCIDENTAL STATIC ALERT!

My dad is not a JavaScript programmer, but he does have something in common with nearly all of us; a deep and passionate love of beer. Unlike most JavaScripters, however, my dad’s favorite brew is on the lower-end of the quality spectrum. When he reaches for a cold one, he Heads for the Mountains. Yes, my dad’s favorite beer is Busch. This presents a problem when he makes the journey from Maine to North Carolina for a visit. Being the good son that I am, I make sure my fridge is stocked with a case upon his arrival. Inevitably though, he never finishes all of them before heading home. I can’t be certain, but I’m quite sure the first person to ever utter the phrase ‘You can’t give these things away!’ was faced with a Busch beer surplus . After his most recent visit, I turned to Facebook to help myself out…

I don’t want to brag or anything, but I have well over 100 Friends on Facebook. Would you believe not one of them took these fine beverages off my hands? There are some problems even Mark Zuckerberg can’t solve.

If Life Were Software

The other day, I was working on a Dojo-based project and was paring down a JavaScript array using the ultra-slick dojo.filter function. As I was effortlessly discarding the unwanted array elements, I had the thought, “Man, I really could have used dojo.filter when I was trying to get rid of those Busch beers!”. (Am I the only one that wishes for the ability to apply software-based solutions to our physical world? Surely I’m not the only person that gets an overwhelming urge to do a ctrl-f while hopelessly searching the aisles at Wal-Mart?). The revelation at the handiness of dojo.filter made me realize that the Dojo array functions deserve a blog post of their own. And what better contrived data set than an array of beers?

Some Silly Data

In this article, we will use the following array. It contains two Busch beers and an assortment of good beers. Each beer object contains two strings, one representing the brand of beer, and a second that contains a path to an image of that beer’s logo.

	var beersData = [
	  {"brand":"Busch", "image":"images/busch.png"},
	  {"brand":"Blue Moon", "image":"images/bluemoon.png"},
	  {"brand":"Fat Tire", "image":"images/fattire.png"},
	  {"brand":"Stella Artois", "image":"images/stellaartois.png"},
	  {"brand":"Busch", "image":"images/busch.png"}
	];

Note: I am of the extremely rare classification of JavaScript programmer that does not drink. Therefore, I have no idea if these beers are any good. I queried the most sophisticated of my IBM colleagues for their favorite beer and these names kept coming up, so I trust that they must represent the very best beers in the world.

dojo.forEach

We’ll begin our investigation of the Dojo array functions with a look at the workhorse dojo.forEach. It’s true that dojo.forEach is just a syntactically sugared version of a for-loop, but oh how sweet it is. In its simplest form, dojo.forEach is passed an array and a function that gets executed on each member of that array. The following code uses dojo.forEach to craft a function called beersToDOM which creates an img element for each beer in our array.

dojo.ready(function(){
	var beersData = [
	  {"brand":"Busch", "image":"images/busch.png"},
	  {"brand":"Blue Moon", "image":"images/bluemoon.png"},
	  {"brand":"Fat Tire", "image":"images/fattire.png"},
	  {"brand":"Stella Artois", "image":"images/stellaartois.png"},
	  {"brand":"Busch", "image":"images/busch.png"}
	];

	var beersToDOM = function(beers, target) {
		dojo.forEach(beers, function(beer){
			dojo.create("img", {"src":beer.image}, target);
		});
	};
	beersToDOM(beersData, dojo.byId('foreachDemo'));
});

Run this code

This div has an id of foreachDemo.

It also bears noting that the arguments passed to dojo.forEach‘s callback function include two other parameters that I omitted from the above example. In addition to the current array element, the array index (“i value”), and a reference to the array itself are also passed. It is often-times helpful to have these bits of information while iterating over arrays. Here is the same forEach code with those arguments specified:

dojo.forEach(beers, function(beer, index, array){
	dojo.create("img", {"src":beer.image}, target);
});

Another nifty feature of dojo.forEach is the optional scope parameter. Passing an object as the final argument to forEach results in the callback function being executed in the scope of that object. This means that the ‘this’ in the callback function will be the object you pass it.

dojo.forEach(array,
 function(item, index, originalArray) {...},
 obj); // Invokes the function in the scope of 'obj'

dojo.filter

dojo.filter looks much like dojo.forEach. Its arguments are an array and a function to run on each array member. dojo.filter returns a new array whose contents are determined by the boolean return value of its callback function. If true is returned for an individual array item, that item is included in the new array. If false is returned, that item is excluded. Look at how elegantly we can return a new array that contains none of the undesirable Busch beers.

	var skunkFree =
		dojo.filter(beersData,
			function(beer){ return beer.brand != "Busch"; }
		);
	beersToDOM(skunkFree, dojo.byId('filterDemo'));

Run this code

This div has an id of filterDemo.

Getting rid of the Busch beers was a solid accomplishment, but it would be much better if we could somehow transform them into good beers. For this Rumpelstiltskin-esque task, we’ll turn to dojo.map. dojo.map runs its callback function on every item in the array and creates a new array containing the return values of each invocation of the function. Let’s write a function that detects if an array item is a Busch beer. If so, we’ll return an object literal representing a Blue Moon. If the beer is not a Busch, we’ll return a copy of that perfectly-fine-as-it-is beer.

var beerAlchemy = dojo.map(beersData, function(beer) {
 return beer.brand === "Busch" ?
  {
	 "brand":"Blue Moon",
     "image":"images/bluemoon.png"
  } : dojo.clone(beer);
});
beersToDOM(beerAlchemy, dojo.byId('mapDemo'));

Run this code

This div has an id of mapDemo.

Rounding out the Dojo Array functions are two simple functions that return boolean values. dojo.some returns true if some of the items in the passed array return true for the passed callback function. dojo.every returns true if all of the items in the passed array return true for the callback function. As a simple example, here is a function that does a sniff test to determine if the beer is a Busch. dojo.some returns true because there are two Busch beers in the array. dojo.every returns false because the array is not entirely composed of Busch beers.

var beersData = [
	  {"brand":"Busch", "image":"images/busch.png"},
	  {"brand":"Blue Moon", "image":"images/bluemoon.png"},
	  {"brand":"Fat Tire", "image":"images/fattire.png"},
	  {"brand":"Stella Artois", "image":"images/stellaartois.png"},
	  {"brand":"Busch", "image":"images/busch.png"}
	];

var skunkTest = function(beer) {
	return beer.brand === "Busch";
}
var hasSkunk = dojo.some(beersData, skunkTest);  // TRUE
var nuthinButSkunk = dojo.every(beersData, skunkTest);  // FALSE

Array functions, the key to cleaner code

Before discovering the array functions, many Dojo newcomers transitioning from Java or C# find themselves lost without formal ‘Collection’ types. It’s not long before things like function contains(array, object){...} are springing up all over the place. Writing helper-functions like this is a natural reaction, but almost always unnecessary. When used proficiently just about all array manipulation tasks can be completed using forEach, filter, map, some, or every. Mastering these functions will result in concise and readable array manipulation code, definitely something worth raising a glass to.

The Dojo DataGrid is the Super Bowl of widgets. Newcomers flock to it! Everyone wants one on their page, but it is not easy to win the Super Bowl, nor is it easy to conquer the Grid. The first time I got one working I took a victory lap around the office, high-fiving co-workers who stared back at me suspiciously. It was pretty awesome. Unfortunately, many people never experience that moment of ecstasy, or if they do, it is after many long hours of pain. You may feel like your code matches an example from the web exactly, but no matter what you do, the Grid will just not show up! Trust me, I know how it feels to be so close to your goal, yet continually come up short (or wide right, as it may be), I am a fan of the Buffalo Bills.

This post will feature a simple, all inclusive, example for populating a Grid with data and displaying it on your web page. We will start with the basic page set up, including the style sheets, then move on to writing the necessary markup and JavaScript code. The DataGrid really isn’t that hard, you just need to understand all its parts.

Buffalo Bill Greats and their Super Bowl Victories

In honor of the 20th Anniversary (January 27, 1991) of one of the most traumatic memories from my childhood (see this YouTube video if you don’t know what I’m talking about), I reluctantly present you the following Grid:

Notice some of the nice built-in features of the Dojo DataGrid, such as column sorting and row highlighting. Below you will find all the code required to produce this Grid. Keep heading down the page and we’ll go over the pieces in detail.

A Single Page Dojo DataGrid Example

<!DOCTYPE html>
<html>
<head>
<title>The Simplest Dojo DataGrid Example of All Time</title>
<link rel="stylesheet" type="text/css"
 href="http://ajax.googleapis.com/ajax/libs/dojo/1.5/dijit/themes/claro/claro.css" />

<link rel="stylesheet" type="text/css"
 href="http://ajax.googleapis.com/ajax/libs/dojo/1.5/dojox/grid/resources/Grid.css" />

 <link rel="stylesheet" type="text/css"
 href="http://ajax.googleapis.com/ajax/libs/dojo/1.5/dojox/grid/resources/claroGrid.css" />
</head>

<body class="claro">
	<div style="width: 600px; height: 200px">
		<table id="billsGrid" dojoType="dojox.grid.DataGrid">
	  		<thead>
	    		<tr>
	      			<th field="number">Number</th>
	      			<th field="name">Name</th>
	      			<th field="position">Position</th>
	      			<th field="victories" width="180px">Super Bowl Victories</th>
	    		</tr>
	  		</thead>
		</table>
	</div>

<script type="text/javascript"
 src="http://ajax.googleapis.com/ajax/libs/dojo/1.5/dojo/dojo.xd.js"
	djConfig="parseOnLoad:true"></script>

<script type="text/javascript">
	dojo.require("dojox.grid.DataGrid");
	dojo.require("dojo.data.ItemFileReadStore");
</script>

<script type="text/javascript">
dojo.ready(function() {
	var theGreatestTeamOfAllTime = {
		items: [ {
				  "number":"12",
				  "name":"Jim Kelly",
				  "position":"QB",
				  "victories":"0"
				  },
		         {
				  "number":"34",
				  "name":"Thurman Thomas",
				  "position":"RB",
				  "victories":"0"
				  },
		         {
				  "number":"89",
				  "name":"Steve Tasker",
				  "position":"WR",
				  "victories":"0"
				  },
			{
				"number":"78",
				"name":"Bruce Smith",
				"position":"DE",
				"victories":"0"
			}
		       ],
		identifier: "number"
	};

	var dataStore =
	new dojo.data.ItemFileReadStore(
		{ data:theGreatestTeamOfAllTime }
	);
	var grid = dijit.byId("billsGrid");
	grid.setStore(dataStore);
});
</script>

</body>
</html>

Step 1: Include Dojo on your page

Starting on line #29, Dojo is included on the page. In this example we are pointing to the copy of Dojo hosted on the Google CDN. The important thing to take away from this line is the djConfig="parseOnLoad:true" attribute. When parseOnLoad is set to true the Dojo parser will automatically search for tags containing a dojoType attribute and replace that element with the markup of the specified widget. If you are unfamiliar with Dojo Widgets, I recommend reading Dan’s article on the subject. If you forget to add the parseOnLoad:true parameter, you’re going to end up with a very boring HTML table instead of a fancy Dojo DataGrid. This is a very common mistake.

Step 2: Add the style sheets

Being that the DataGrid is the Super Bowl of widgets it gets some special treatment when it comes to styling. Unlike most widgets, the Grid has its own set of style sheets. In the HEAD section of the example you’ll see the standard Claro theme style sheet is included, but directly below it the grid.css and gridClaro.css files are also added. This is very important. If you don’t include those, your Grid won’t even be recognizable! See…

On line #15, in the body tag, the Claro class is specified. This, combined with the style sheet includes, will load all of the necessary styling information for your Grid.

Step 3: Require the necessary modules

Dojo 101 lesson reminder…if you are using a specific Dojo type on your page you need to require it. Starting on line #34 we include the dojox.grid.DataGrid and the dojo.data.ItemFileReadStore. We’ll see how these are used momentarily.

Step 4: The Markup

There are three main parts to the markup of our example DataGrid.

• The surrounding div tag (line #16) wraps the table markup and contains settings for the height and width. The Dojo DataGrid tends not to show up if no sizing information is specified, so don’t forget this part.
• The table tag (line #17) contains the dojoType="dojox.grid.DataGrid" attribute. This is the attribute the Dojo parser looks for when the page loads and thus this element represents the element that will be replaced with the Grid’s markup. Also notice that an id for the table is specified inside the table tag. This id will be referenced later in the JavaScript code used to populate the Grid.
• You need to add a th tag for each column in your data set that you want displayed in the DataGrid. Each column header tag contains a field attribute. This attribute corresponds to the name of a field in a data store that contains your data. Table rows will automatically be generated for each entry in your data store. (More on data stores in a bit).

Step #5: The JavaScript code

The JavaScript code to populate the Grid begins on line #39 with a call to dojo.ready(). dojo.ready is a synonym for dojo.addOnLoad. This function ensures that the function passed in as an argument only executes after the DOM is ready, preventing us from operating on the DataGrid object before it has been created.

The coolest part about the Grid is that it utilizes the dojo.data API. You can use any Data Store that conforms to the dojo.data API with the Grid. For our example, we will use Dojo’s built-in ItemFileReadStore.

Inside the function our first step is to create an object literal in JSON format that contains the data we want to display in the Grid. (In an actual application this data would likely be pulled in from a database or other web service). The structure of this data is very important. The ItemFileReadStore requires a very specific format. First, it must have a field named items that contains an array of objects that represent the data. Second, it needs to contain a field named identifier that specifies the primary key of the data. Neglecting to put your data in this format is an extremely common mistake when dealing with the ItemFileReadStore.

On line #69 the dojo.data.ItemFileReadStore object is created. It requires a single argument, the object literal object in JSON format defined right above it and described in the previous paragraph.

Lastly, the Grid object itself is retrieved via a call to dijit.byId("billsGrid"), passing in the ID of the table as specified in the markup on line #17. The retrieved Grid object then has the ItemFileReadStore set on it. Setting the store will cause the Grid to load and display the data.

Putting it through the uprights

The intent of this article was to get you started with the Grid. Maybe this example represented your very first experience with Dojo, and I hope that it steered you clear of some of the mistakes most Dojo newcomers make. If you are brand new to Dojo, you can copy and paste the code example into an HTML file and it will work. But if you want to have consistent success over the long term (like those damn Pittsburgh Steelers), take this example and study it. Take the time to learn the different components and how everything works together. After you have the Grid running, experiment with some of the other widgets available in the Dijit library.

In future articles we will look into some more advanced Grid topics, such as inline editing, moving things around, paging, event handling, and all those other exciting things one can do with a Grid. Any special requests? Post them in the comments!

Grid Reference: http://dojotoolkit.org/reference-guide/dojox/grid/DataGrid.html

Good luck and go Packers (next week) and go Bills (next year)!!

Not out of the woods

Does the use of a JavaScript library mean your days of browser-specific issues are over? Should you just test your code in the latest version of Chrome and call it a day? Of course not. There still exists an entire class of programming errors that only appear as bugs in certain browsers. Of these, none is more sinister than……..the Trailing Comma of Death.

This is my affectionate nickname for the oh-so-common mistake of adding a comma after the final declared property within a JavaScript object. Here is a contrived example. Note the extra comma after the declaration of the get2 function.

dojo.ready(function() {
	var testObject = function() {
		var testString1 = "Trailing commas? ";
		var testString2 = "They don't scare me.";
		return {
			get1 : function() {
				return testString1;
			},
			get2 : function(){
				return testString2;
			},
          // ^ Trailing Comma of Death
		};
	};

	var t = testObject();
	dojo.byId("commaTest").innerHTML = t.get1() + t.get2();
});

Let’s look at a series of screenshots that shows the output of the above code in Firefox, Chrome, and Internet Explorer. Assume that Dojo is included in the page, and that there exists a div element with an id of ‘commaTest‘.

Here’s what it looks like in Firefox 3.6:

In Google Chrome 9:

And in Internet Explorer 8:

Wuh-oh, what happened in Internet Explorer? It turns out that the trailing comma is right on the edge as to what is permissible JavaScript syntax. Internet Explorer does not tolerate a trailing comma while the rest of the browsers do. The lesson? Internet Explorer is terrified of the Trailing Comma of Death.

That this issue is specific to Internet Explorer makes for a very dicey situation. Web developers tend to use the “any-browser-but-IE” strategy as they develop their JavaScript code because the debugging tools provided by those browsers are so much better. This means that most developers fire up Internet Explorer only as a last step in code verification, and will not catch trailing comma problems until that point. Thankfully the Developer Tools console of IE8 usually gives a nice, clear error when a trailing comma is encountered:

A Harrowing Tale

You may be wondering why I think the trailing comma problem is a big deal. How on Earth could it make its way into a production code-base? Well, my skeptical friends, let me tell you a story…..

There once was a newly minted JavaScript programmer who was given his very first assignment. We’ll call him Stan Dee. Stan was asked to write a simple Dojo widget, something his boss thought would be a good introductory work item. Naturally, Stan wanted his first code delivery to be flawless, elegant, and clever. You know, in case any of his new team-mates happened to see it in the commit logs. Stan wrote the widget and tested it obsessively in all of the product’s supported browsers, and even in one that isn’t officially supported. It looked great. As he was about to commit his work and move on, Stan noticed a block of code in his widget that was unnecessarily repeated. A firm believer in the DRY principle, Stan could not do the commit before abstracting the duplicate code into its own function. He was using Dojo’s animation features to pull off a fade-out technique and had almost exactly the same code in two places.

Stan sought to DRY this situation out a bit. He created a new function in the file. Stan, like all developers, is lazy. Instead of typing out the necessary code, he swiped an already existing function, copied it, and pasted it at the end of the widget’s function declarations, and changed the name:

Stan then cleaned up the rest of the code, replacing the contents of the new function with the appropriate code and updating the other functions to invoke the new common one:

Along the way, Stan made one glaring mistake. Did you catch it? What’s that laughter? Oh, it appears as though somebody has spotted the problem:

Gah! The Trailing Comma of Death found its way into the code! That’s OK though, surely Stan tested in IE before he dropped his code, right? Well…..Stan had a deadline, and his thought patterns were something along the lines of this:

“Oh crap, the build is about to kickoff. If I want to get this code in, I need to commit it now. It’s just a little function refactor, how could that not work in IE? I better test it though….. Oh man, IE is so slow, it’s going to take me 15 minutes to test this…. Forget it. Let me verify it real quick in Firefox. Yup, it works. It’ll work in IE, I just know it.” *CLICK*

And with that, the Trailing Comma of Death was committed to the source code repository. The build ran that night and was first picked up by Stan’s colleagues in the UK. The build failed violently in Internet Explorer. As Stan slept, a British colleague of his was forced to investigate the failure and checked the commit history of the previous day. Stan’s colleague, who was no stranger to the Trailing Comma of Death, found the problem and delivered a fix. When Stan checked his email that morning, he found a note in his inbox. The note was short and painful:

Hey Stan. Your commit broke the build.
Watch out for those trailing commas.

-[Name redacted]

Defending Against the Trailing Comma

Trailing Commas are no joke. As Stan learned the hard way, they are extremely easy to introduce. And when working on a large and complex JavaScript application, they can be increasingly hard to find and troubleshoot. Oh, and as Stan also learned, there are few things that Development Managers hate more than bugs introduced by trailing commas!

So how do we make sure that they never make it into the code in the first place? Sadly, there is no magic bullet here. The best way to stop trailing commas is a two-pronged approach of disciplined programming and configuring your development tools to flag them. The discipline part is easy; always validate in IE while developing. I know that IE’s Developer Tools are not the best, but that’s no excuse. As developers, each day is filled with temptations to take short-cuts. Skipping IE testing is a short-cut that you can’t afford to take.

On the tools front, my preference for combating these devils is the Eclipse JavaScript Development Tools. The JavaScript source editor in JSDT flags trailing commas as errors:

The venerable JSLint can be configured to flag them as well. The next level in protection after arming developers with tools is to add a trailing comma check to your build facility such that they can be sniffed out at build-time. I’ve heard of home-brewed systems based on JSLint used for this purpose, but there may be other solutions out there as well.

A Call for Discussion

If you’ve been a JavaScript programmer for any length of time, you’ve almost certainly had a run-in or two with the Trailing Comma of Death. Maybe you’ve developed your own tactics for defeating it? I am sure that there are tools and techniques out there that I have not heard of. I would love to hear your stories. Please, add a comment to this post if your team has found a good solution. Together, we can help our fellow developers defeat this pesky adversary!

A couple weeks ago I was walking back from the break-room when the words every Enterprise Developer fears came from my boss’s office.

“Hey Dan. Get in here. I’ve got an idea”.

Nervously, I walked into his office and replied, “Sure, what’s up?”

“Well, I read a book this weekend and it really got me thinking.”

My heart skipped a beat. This was going downhill fast.

“This book talked about the role of psychology when it comes to salesmanship. It quoted a study where salespeople described their mood at 9am every morning. Do you know what they found? They found that when a salesperson described their mood as ‘inspired’, they sold an average of 23% more stuff! Can you believe that?!”

“That’s pretty cool”, I said.

The motivational Dojo widget

I wasn’t in love with my boss’s idea, but it certainly wasn’t the worst one he’d ever had. Plus, I would get to implement this feature with Dojo. And whenever I get to use Dojo, I get excited. (This is the level of excitement that I’m talking about. Just replace the words “NINTENDO Sixty-FOOOOOOOOOOUR!!!!” with “DOJOOOOOOOOOO!!!!”).

I pondered a bit as to whom these motivational quotes should come from. I considered Gandhi, Sun Tzu, and other great thinkers, but after a little more thought, the answer became obvious. This man has spoken more motivational phrases than any other in contemporary times. I speak, of course, of Homer J. Simpson.

The Dojo Widget

After an hour or so, I had a pretty good looking widget. Here it is:

And here is the code. Remember, Dojo widgets typically consist of three elements: an HTML fragment that holds the actual markup of the widget, a CSS file that contains the widget’s styling information, and a JavaScript file that declares the widget and defines its logic. (If you aren’t familiar with the components of custom Dojo widgets, it would be a fine time to have a look at my Introduction to Custom Dojo Widgets article).

The HTML template (Homer.html)

<div class="homer">
	<div dojoattachpoint="messageHeading" class="message heading"></div>
	<div dojoattachpoint="message" class="message"></div>
</div>

The CSS file (Homer.css)

.homer {
	background: url("homer.png") no-repeat #4EA235;
	min-height: 230px;
	width: 500px;
	font : bold 18px "Helvetica Neue",Arial,Sans-serif;
}

.homer .message {
	color: #FFFFFF;
	margin-left : 160px;
}

.homer .heading {
	padding: 20px 0 20px 0;
}

The JavaScript (Homer.js)

dojo.provide("widgets.motivational.Homer");

dojo.require("dijit._Widget");
dojo.require("dijit._Templated");

dojo.declare("widgets.motivational.Homer", [ dijit._Widget, dijit._Templated ], {
    templateString : dojo.cache("widgets.motivational",
    		                    "templates/Homer.html"),

    postCreate : function() {
    	this.messageHeading.innerHTML =
    		"Today's Motivational Message:";
    	this.message.innerHTML =
    		'"You tried your best and you failed miserably. The lesson is: Never try."';
    }
});

Here is the layout of these files on disk:

I was about to show my boss my progress when he enthusiastically burst into my cube.

“Dan! Great news. I just got off the phone with our European Sales Team and they love my idea! Whatever you’re working on, make sure you make a German, French, and Dutch version of it too!”

“Oh. Awesome!”, I said, matching his enthusiasm. “I’m on it.”

Nobody is a fan of having more work added to their plate at the last minute, but this request was not going to be a problem. Dojo provides built-in support for internationalization, so this was going to be a snap. In fact, it’s so easy I’ll take a break from my riveting corporate software development story and explain the basics of using Dojo to provide internationalization (which is often abbreviated i18n).

i18n with Dojo: Externalizing the strings

The first step in internationalizing a Dojo module is to create a folder called nls in the root folder of the module. Inside this folder, we place one or more files that contain all of the strings that require translation. As a convention, we can create one file for each widget in the module and name these files the same name as our widget’s JavaScript file, but they can be named anything and organized in any way that you see fit. In our case, we will create a single file named Homer.js.

The contents of this file are a JavaScript object literal containing all of the strings that require translation. Thus the contents of nls/Homer.js are:

{
	"messageHeading" : "Today's Motivational Message:",
	"message" :
	        '"You tried your best and you failed miserably. The lesson is: Never try."'
}

In Dojo parlance the above file is called a language bundle. This particular bundle (which contains the English versions of our strings) is called the default translation bundle and will get fetched whenever a more specific language is not available. (More details on this in a bit).

Inside our nls folder we will create a sub-folder for each language we want to support. The names of these directories need to be lowercased versions of the appropriate RFC 3066 locale abbreviations. For example, the abbreviation for French is fr and the more specific abbreviation for French as it is spoken in France is fr-fr. If we wanted to support Haitian French, we would create a directory called fr-ht. Dojo uses the browser’s locale setting to figure out which translations to load. If the fr-fr locale is detected, Dojo will attempt to load translations at nls/fr and nls/fr-fr. The idea here is that you can put all of the strings common to the french locale in nls/fr and any strings specific to the France dialect in fr-fr.

In this particular instance, dialects are not a big concern. We will simply create folders for German, French, and Dutch, placing a translated version of our Homer.js bundle in each. We don’t need to create folders for English, as the English cases will be handled by the default bundle in the root of the nls directory.

The contents of the bundle files are identical to the English version, but the values of the JavaScript object are UTF-8 encoded translations of the strings.

nls/de/Homer.js

{
	"messageHeading" : "Die heutige Motivation Nachricht:",
	"message" :
		'"Sie haben versucht, Ihre besten und Sie scheiterte kläglich. Die Lektion ist: Niemals versuchen."'
}

nls/fr/Homer.js

{
	"messageHeading" : "Message de motivation d'aujourd'hui:",
	"message" :
		'"Vous avez essayé de votre mieux et vous avez échoué misérablement. La leçon est la suivante: Ne jamais essayer."'
}

nls/nl/Homer.js

{
	"messageHeading" : "Motiverende boodschap van vandaag:",
	"message" :
		'"Je hebt geprobeerd je best en je mislukte jammerlijk. De les is: probeer nooit."'
}

Editor’s Note: I used Google Translate to come up with these translations, so they probably aren’t very good. If any European Dojo enthusiasts have stumbled across this post and would like to help provide more authentic translations, please let me know!

Dojo APIs for Loading Externalized Strings

Now that we have our strings externalized, we can modify our widget to use the appropriate translation instead of hard-coding English strings. First, we have to load Dojo’s core i18n module. Like any Dojo module we load this with a call to dojo.require:

dojo.require("dojo.i18n");

Next, we have to tell Dojo to load the appropriate language bundle. This is accomplished with a call to dojo.requireLocalization. This API is very similar to dojo.require. The first argument is the name of the module where the language bundle lives, and the second argument is the name of the bundle itself. In our case, the name of the module is widgets.Motivational and the language bundle is in a file called Homer.js. Thus the call to dojo.requireLocalization looks like:

dojo.requireLocalization("widgets.motivational", "Homer");

Lastly, we will replace the occurrences of our English strings in our widget with calls to a dojo.getLocalization. Just like dojo.requireLocalization, the arguments to dojo.getLocalization are the name of the module followed by the name of language bundle. This API returns the actual JavaScript object literal that we defined in our language bundle files. So once we have that object, we can access our strings using regular JavaScript object ‘dot’ notation. Thus, the original code from the postCreate function of our widget:

    	this.messageHeading.innerHTML =
    		"Today's Motivational Message:"
    	this.message.innerHTML =
    		'"You tried your best and you failed miserably. The lesson is: Never try."'

becomes:

    	var localization =
    		dojo.i18n.getLocalization("widgets.motivational", "Homer");   	

    	this.messageHeading.innerHTML = localization.messageHeading;
    	this.message.innerHTML = localization.message;

It’s as easy as that. In the future, if we want to add support for another language, all that is required would be to add a new folder and language bundle file to our nls folder. We will not have to modify the widget’s source code at all. Sweet.

Here is the internationalized widget in its entirety:

dojo.provide("widgets.motivational.Homer");

dojo.require("dijit._Widget");
dojo.require("dijit._Templated");

dojo.require("dojo.i18n");
dojo.requireLocalization("widgets.motivational", "Homer");

dojo.declare(
  "widgets.motivational.Homer",
  [ dijit._Widget, dijit._Templated ],
  {
      templateString : dojo.cache(
				"widgets.motivational",
				"templates/Homer.html"),

	  postCreate : function() {
		  var localization = dojo.i18n
				.getLocalization(
						"widgets.motivational",
						"Homer");

		  this.messageHeading.innerHTML =
                  localization.messageHeading;
		  this.message.innerHTML = localization.message;
	}
});

Testing our Translations

One way to test would be to painstakingly launch our web browser in each of the locales. A more convenient technique though is to take advantage of the locale setting in Dojo’s djConfig variable. To use it, we add it to the djConfig attribute in the script element that loads the dojo.js file. For example, to set the locale to de:

<script src="/path/to/dojo.js"
        type="text/javascript" djConfig="locale:'de'"></script>

Using the djConfig variable allows us to quickly assess how our widget looks in different languages.

Here’s how the widget looks in German:

In French:

And In Dutch:

The above are images. If you’d like to take a look at a real HTML representation of the widget in translated form, check out these pages. Do a ‘View Source’ in your browser and look for the djConfig variable to see an example of setting a specific locale.

• German Test Page
• French Test Page
• Dutch Test Page

Showing the Boss

I had built a multinational, motivational, Homer Simpson-themed Dojo widget. At risk of sounding too pleased with myself, I was pretty sure this was the crowning technical achievement of my development career. Surely, a raise was in my immediate future. Curiously though, when I showed it to my boss, I didn’t get the reaction I was hoping for. I gave him a quick demo, and when I asked what he thought, he fell silent. He stared at my laptop’s screen with a blank expression on his face for a good 30 seconds and then finally muttered something along the lines of, “Dan, you’re lucky that you are good at this JavaScript stuff”, and walked out of my cube. I’m not exactly sure what he meant by this, but I think I’ll hold off on buying that boat…

Conclusions

As you may have come to expect from Enterprise Dojo, the examples that we show here are silly, but the concepts are serious. For enterprise applications an internationalization story is not ‘nice to have’; it is an absolute must. Rolling your own solution for i18n concerns is not out of the realm of possibilities for a good team of developers, but it’s certainly not something you want to do if you can avoid it. Dojo provides a battle-tested and elegant solution for i18n out-of-the-box. Use it.

This article introduced the broad concepts of Dojo’s i18n support, but there is a lot more to it. Consult the official i18n Quickstart on dojotoolkit.org for more details, and happy i18n’ing!

The ‘High Schooler’ widget we created in my last post was fun, but incomplete. A severe limitation of the widget was its static nature. As we all know, High Schooler’s are far from static. I’m speaking from experience here. I went through a drastic metamorphosis as I progressed through that stage of my life. Just look at these photos from my formative years.

(1997 was a bit of a rough year for me. I was listening to a lot of Fiona Apple. You understand).

Yes, High Schoolers are dynamic creatures, so our widget should account for that. We will enhance our widget such that its graphical representation can be updated on-the-fly.

This Agreement is Binding

We will explore how to ‘bind’ a widget property to a DOM node. That is, we will configure our widget to listen for changes in its properties and automatically update the relevant DOM nodes when a change occurs.

I can already hear the Software Engineering part of your brain thinking about how you would code this solution. Something like this, right?

• We’ll need an event listener. We’ll listen for any changes to the widget’s properties.
• When we get a change event, we’ll figure out which property changed.
• Once we know what property changed, we’ll know which part of the DOM to update. We’ll then update that DOM node.

You are on the right track! And in fact, Dojo contains two wonderful APIs for dealing with these types of situations. dojo.connect is a general event handling mechanism and dojo.publish/dojo.subscribe is a lightweight publication/subscription mechanism that allows us to model this pattern in a loosely coupled fashion. Both of these APIs belong in your toolbox and will be covered in future Enterprise Dojo articles. Today we won’t be needing either, however. Binding widget properties to DOM nodes is an extremely common use-case and Dojo widgets provide native support for this scenario.

Using attributeMap for Simple Bindings

To review, let’s take a look at the HighSchooler widget.

Here is the HTML template

<div class="highSchooler">
  <div class="avatar">
    <img dojoattachpoint="imageNode"></img>
  </div>
  <div>
    <ul class="profile">
      <li><span class="label">Name</span>
	    <span dojoattachpoint="nameNode"></span>
	  </li>
	  <li><span class="label">Grade</span>
		<span dojoattachpoint="gradeNode"></span>
	  </li>
	  <li><span class="label">Hero</span>
		  <span dojoattachpoint="heroNode"></span>
	  </li>
	</ul>
  </div>
</div>

And its JavaScript code is as follows:

// dojo.provide allows pages to use all of the
// types declared in this resource.
dojo.provide("widgets.HighSchooler");

// dojo.require the necessary dijit hierarchy
dojo.require("dijit._Widget");
dojo.require("dijit._Templated");

dojo.declare("widgets.HighSchooler", [ dijit._Widget,
		dijit._Templated ], {
	// Path to the template
	templateString : dojo.cache("widgets",
			"templates/HighSchooler.html"),

	// Widget properties
	fullName : "",
	grade : "",
	hero : "",
	stereotype : "",

	// Manipulate the widget's DOM, when ready
	postCreate : function() {
		// Using the attributes defined via dojoattachpoint
		this.nameNode.innerHTML = this.fullName;
		this.gradeNode.innerHTML = this.grade;
		this.heroNode.innerHTML = this.hero;

		// Setting the avatar to be the appropriate image
		var keys = {
			emo : "emo.png",
			geek : "geek.png",
			punk : "punk.png"
		};
		var key = keys[this.stereotype] || "na.png";
		var imagePath = dojo.moduleUrl("widgets",
				"themes/highschool/images/" + key).toString();

		// Set the 'src' attribute on our <img>
		dojo.attr(this.imageNode, "src", imagePath);
	}
});

Let’s take a closer look at the code that does the actual DOM manipulation for the fullName, grade, and hero properties:

postCreate : function() {
		// Using the attributes defined via dojoattachpoint
		this.nameNode.innerHTML = this.fullName;
		this.gradeNode.innerHTML = this.grade;
		this.heroNode.innerHTML = this.hero;
 ...

Notice the simple relationship between the fullName, grade, and hero widget properties and their respective DOM nodes. In each case, the value of the property is set as the innerHTML on a span element in the template. The problem is this code runs in the postCreate function of our widget. This means that it is executed after the widget is placed in the DOM, but is never run again. What we want to do is ensure that whenever the value of fullName, grade, or hero changes, the innerHTML of their corresponding span element is updated. To do this, we’ll take advantage of a slick feature provided by Dojo widgets called attributeMap.

attributeMap is a special property that we can optionally define in our widget’s JavaScript file that specifies relationships between widget properties and DOM nodes in the widget’s HTML template. In attributeMap, we specify literal objects that contain the name of a widget property, the name of the DOM node that we are binding this property to, and a type field that indicates what type of relationship our property has to this DOM node. In our case, fullName, grade, and hero will be bound to the innerHTML of their respective DOM nodes. Thus our attributeMap property looks like this:

    // Bind 'fullName', 'grade', and 'hero' to the
	// innerHTML of their respective DOM nodes
	attributeMap: {
		fullName : {
			node : "nameNode",
			type: "innerHTML"
		},
		grade : {
			node : "gradeNode",
			type: "innerHTML"
		},
		hero: {
			node: "heroNode",
			type: "innerHTML"
		}
	}

(In addition to innerHTML, it is also possible to bind properties directly to an HTML attribute or to a CSS class name. See this for an example).

With the attributeMap specified, whenever fullName, grade, or hero are modified via calls to widget.set('property', 'newPropertyValue'), the innerHTML of the corresponding DOM node will be automatically updated to the new property value. (Note: The same behavior occurs when using the deprecated widget.attr('property', 'newPropertyValue'). The attr function is slated to go away in Dojo 2.0. But, and this is very important, the binding behavior is not honored if one modifies the property value directly, e.g. widget.property = 'newValue').

attributeMap Bindings in Action

To give a concrete example, assume we have a reference to a HighSchooler widget in the variable myWidget. Setting the hero property to ‘Clyde the Glide Drexler’ would be done in the following way.

myWidget.set('hero', 'Clyde the Glide Drexler');

The innerHTML of the hero span in our widget’s DOM will be automatically updated when the above code is executed.

As they say, a live demo is worth 1,000 words, so give this one a try. Changing the value of the combo will be immediately reflected in the HighSchooler widget below.
I have wired the following combos to call set('property', valueOfCombo) on the widget below using code that looks like:

dojo.connect(dijit.byId('idOfCombo'), "onChange",
    function(newValue) {
        var widget = dijit.byId('idOfHighSchoolerWidget');
        widget.set('nameOfPropertyToSet', newValue);
    }
);

Beyond Simple Mappings

The relationship between a widget property and its corresponding DOM representation can be more complex. The stereotype property in our widget is a good example. To determine which photo to use in our widget we use the value of stereotype to calculate the path to an image. We then set this path as the src attribute on the img element in our widget’s HTML template. Here’s the code in the postCreate function that quantifies the relationship:

// Setting the avatar to be the appropriate image
var keys = {
	emo : "emo.png",
	geek : "geek.png",
	punk : "punk.png"
};
var key = keys[this.stereotype] || "na.png";
var imagePath = dojo.moduleUrl("widgets",
				"themes/highschool/images/" + key).toString();

// Set the 'src' attribute on our <img>
dojo.attr(this.imageNode, "src", imagePath);

This relationship cannot be specified in attributeMap because it requires several lines of processing code to calculate the image path, however, Dojo provide us with a convention-based approach for achieving the same goal. By specifying a function in the widget’s JavaScript file that is called_setPropertyNameAttr() where ‘PropertyName‘ is the name of the widget’s property, this function will automatically be called anytime that set('PropertyName', 'newValue') is called. Thus, for our widget to take advantage of this, we remove the above code from postCreate and refactor it into a function called _setStereoTypeAttr:

// Whenever set('stereotype', 'newValue') is called,
// this function will be called.
_setStereotypeAttr : function(newType) {
    // Setting the avatar to be the appropriate image
	var keys = {
		emo : "emo.png",
		geek : "geek.png",
		punk : "punk.png"
	};
	var key = keys[newType] || "na.png";
	var imagePath = dojo.moduleUrl("widgets",
				"themes/highschool/images/" + key).toString();

	// Set the 'src' attribute on our <img>
	dojo.attr(this.imageNode, "src", imagePath);
}

With this code in place, anytime that widget.set('stereotype', 'newValue') is called, our _setStereoTypeAttr function will also be called. This will ensure that the image that represents the stereotype is updated. Try it out for yourself.

The Whole Thing

Here is the full version of our widget’s updated JavaScript file, notice that the postCreate function is removed completely. The relationship between the widget’s properties and its DOM nodes are specified in attributeMap and the _setStereotypeAttr function.

dojo.provide("widgets.HighSchooler");

dojo.require("dijit._Widget");
dojo.require("dijit._Templated");

dojo.declare("widgets.HighSchooler", [ dijit._Widget,
		dijit._Templated ], {
	// Path to the template
	templateString : dojo.cache("widgets",
			"templates/HighSchooler.html"),

	// Widget properties
	fullName : "",
	grade : "",
	hero : "",
	stereotype : "",

    // Bind 'fullName', 'grade', and 'hero' to the
    // innerHTML of their respective DOM nodes
	attributeMap:
    dojo.delegate(dijit._Widget.prototype.attributeMap, {
		fullName : {
			node : "nameNode",
			type: "innerHTML"
		},
		grade : {
			node : "gradeNode",
			type: "innerHTML"
		},
		hero: {
			node: "heroNode",
			type: "innerHTML"
		}
	}),

	// Whenever set('stereotype', 'newValue' is called,
	// this function will be called.
	_setStereotypeAttr : function(newType) {
		// Setting the avatar to be the appropriate image
		var keys = {
			emo : "emo.png",
			geek : "geek.png",
			punk : "punk.png"
		};
		var key = keys[newType] || "na.png";
		var imagePath = dojo.moduleUrl("widgets",
				"themes/highschool/images/" + key).toString();

		// Set the 'src' attribute on our <img>
		dojo.attr(this.imageNode, "src", imagePath);
	}
});

UPDATE: I added a call to dojo.delegate in the attributeMap property to ensure that the attributeMap in _Widget is not clobbered. See Kenneth G. Franqueiro’s helpful comment for more details.

Dojo is Deep

I’ve been writing Dojo widgets for a few years now, but only recently discovered this technique. I was content writing my own property/DOM synchronization code, but one day I stumbled across attributeMap in the documentation and realized that I could have been using it all along. This tends to happen when working with Dojo. Dojo is not a ‘Do One Thing and Do It Well’-type toolkit. Dojo is the Staples® of JavaScript toolkits. ”Dojo: Yeah, we’ve got that”.

With all of that excellent functionality, it often means that facilities within Dojo contain gems that aren’t plainly visible on the surface. In the fast-paced world of Enterprise software development, the pressure to meet a deadline makes finding these gems even less likely. But one of the best things about working with JavaScript, CSS, and HTML is that it is simple and fast to get a throwaway HTML page up and running. Whenever you are given a new assignment that involves Dojo, I encourage you do a little digging first. Create a test page, navigate to Dojo’s reference guide, and try to get the examples presented there running in your browser. Experiment with the API, even the parts that don’t appear 100% relevant to your latest assignment. You’ll understand the subject matter better, and probably learn something that you will use later on down the road.

Programmers are drawn to Dojo for its incredible suite of user interface widgets, better known as Dijits. If you are not familiar with the breadth of Dijits that are available the Theme Tester is a good place to have a look around. Any doubts that you have about whether Dojo provides a suitable suite of widgets for your web application should go away quickly after playing with the Theme Tester for a few minutes. Another invaluable resource is the Dijit Reference Guide on dojotoolkit.org that shows examples of all of the widgets in the Dijit library.

Custom Dojo Widgets

Often lost in the shuffle is that you can write your own custom widgets in addition to using the off-the-shelf Dijits. Enterprise Web Applications are full of common UI elements and functionality that are ripe to be encapsulated into a reusable widget. Lucky for you, Dojo makes this process easy. The resulting code is cohesive and modular, just the way we like it.

Let’s build a simple Dojo Widget using some best practices. Now, if this were an ordinary Enterprise-y blog, our example widget would be some kind of ‘business card’ that showed the details of a corporate employee. But let’s be honest, corporate employees are boring. We will build a business card widget for a much cooler class of people. Who are the coolest people in the world? That’s right, high school students!

Building a High School Student Widget

Our widget will show a picture of a high school student and their pertinent details. I don’t know many high school students, so acquiring photographs for use in this demonstration proved challenging. It was really weird, these kids acted downright frightened when I approached them in the mall and asked if they wanted to be in a JavaScript blog. Youth these days! To solve this problem, I spoke with a renowned social anthropologist who explained to me that High School students can be classified into exactly three groups: Emo, Punk, and Geek.

Our finished product will look something like this 1998-era version of your author:

(You guys would have guessed that I was an Emo, huh?)

Widget Pieces

A typical Dojo Widget is comprised of three files:

• A JavaScript file that declares the widget and defines its logic.
• An HTML fragment file that declares the widget’s semantic markup.
• A CSS file that defines the widget’s styling information.

These files don’t have to be placed in any particular location, but we will use the same convention that Dojo uses for its widgets and set up a directory structure like this:

Our widget will be called widgets.HighSchooler, and its JavaScript file will be placed in a corresponding resource located at widgets/HighSchooler.js. (If you read my previous post about writing modular JavaScript with Dojo, this will look familiar). Our HTML fragment will live in a folder called templates and our CSS file will live in a folder called themes ,with a sub-directory called highschool. The images will also be placed in the themes directory.

The JavaScript File

Let’s take a look at a stubbed version of our widget’s JavaScript file.

dojo.provide("widgets.HighSchooler");

dojo.require("dijit._Widget");
dojo.require("dijit._Templated");

dojo.declare("widgets.HighSchooler", [ dijit._Widget, dijit._Templated ], {
    templateString : dojo.cache("widgets",
    		                    "templates/HighSchooler.html"),
	name : "",
	grade : "",
	hero : "",
	stereotype : ""
});

Declaring a widget is straight-forward. We use dojo.provide to declare our namespace, use dojo.require to load the necessary dependencies, and then use dojo.declare for the actual widget definition. The first argument to dojo.declare is our widget’s name. We are using the pattern of giving our widget the same name as our namespace. The second argument is the widget’s super types. Dojo Widgets typically define two super types, dijit._Widget and dijit._Templated. _Widget provides our widget with necessary life-cycle methods, which we will soon explore. _Templated provides support for instantiating our widget from an HTML template.

The rest of the JavaScript defines the properties and methods for our HighSchooler widget. templateString is a special property that indicates where to find the HTML template file. The rest of the properties represent the meaningful fields of our HighSchooler.

The CSS File

.highSchooler {
	border:1px solid #CCCCCC;
	height:165px;
	margin: 10px;
}

.highSchooler .profile {
	 list-style:none outside none;
	 font: 1.3em 'Lucida Grande',sans-serif;
}

.highSchooler .avatar {
	float: left;
	margin:5px 30px 5px 10px;
}

.highSchooler .profile .label {
	font-weight: bold;
	padding-right: 5px;
}

Nothing special here, just some styles that our widget will use. The interesting thing here is that all styling information about the widget is encapsulated into this file. If we were clever about our styling information it would be possible to implement a skinnable widget, as Dojo does with the Dijit library. (This is beyond the scope of this exercise though, our widget’s styling is rudimentary).

The HTML Template

This file contains the actual HTML markup of our widget. In this case, we define a div that contains an image element for the avatar and another div that contains an unordered list to display the details of our HighSchooler. Notice that the relevant CSS classes are set on the nodes of this HTML fragment.

<div class="highSchooler">
  <div class="avatar">
    <img></img>
  </div>
  <div>
    <ul class="profile">
	  <li><span class="label">Name</span><span></span></li>
	  <li><span class="label">Grade</span><span></span></li>
	  <li><span class="label">Hero</span><span></span></li>
	</ul>
  </div>
</div>

Using dojoAttachPoint

There are certain elements in the widget that we will want to manipulate with JavaScript. In this case the elements of interest are the image tag that shows the avatar and the span elements next to the Name, Grade, and Hero labels. We’ll use an extremely cool feature of Dojo called dojoattachpoint to enable these elements to be programmatically manipulated. We’ll add dojoattachpoint attributes to each of the elements that we would like to manipulate like so:

<div class="highSchooler">
  <div class="avatar">
    <img dojoattachpoint="imageNode"></img>
  </div>
  <div>
    <ul class="profile">
      <li><span class="label">Name</span>
	    <span dojoattachpoint="nameNode"></span>
	  </li>
	  <li><span class="label">Grade</span>
		<span dojoattachpoint="gradeNode"></span>
	  </li>
	  <li><span class="label">Hero</span>
		  <span dojoattachpoint="heroNode"></span>
	  </li>
	</ul>
  </div>
</div>

By adding dojoattachpoint, we have provided access to these DOM nodes in the widget’s JavaScript file. A property is dynamically added to the instance of the widget whose value is the DOM node associated with the element with the dojoattachpoint attribute. The name of this property is the value of the dojoattachpoint attribute. For example, if we want to set the innerHTML of the ‘Name’ span to correspond to our widget’s fullName property, we can do so in the widget’s JavaScript file like this:

this.nameNode.innerHTML = this.fullName;

The rest of our widget’s DOM manipulation code follows this same pattern. One thing to point out is that we only want this code to run after the widget’s DOM is ready. Dojo provides lifecycle methods that get called during a widget’s initialization. The lifecycle method where it is safe to make DOM manipulations is called postCreate. We’ll add a postCreate function to our widget that sets up each of the span elements and sets the image to the appropriate avatar based on the stereotype property:

	postCreate : function() {
		this.nameNode.innerHTML = this.fullName;
		this.gradeNode.innerHTML = this.grade;
		this.heroNode.innerHTML = this.hero;

		var keys = {
				emo : "emo.png",
				geek : "geek.png",
				punk: "punk.png"
		};
		var key = keys[this.stereotype] || "na.png";
		var imagePath = dojo.moduleUrl("widgets",
				"themes/highschool/images/" + key).toString();

		dojo.attr(this.imageNode, "src", imagePath);
	}

That’s it! Our widget’s JavaScript is done. Here it is in its entirety with some helpful comments.

// dojo.provide allows pages to use all of the
// types declared in this resource.
dojo.provide("widgets.HighSchooler");

// dojo.require the necessary dijit hierarchy
dojo.require("dijit._Widget");
dojo.require("dijit._Templated");

dojo.declare("widgets.HighSchooler", [ dijit._Widget,
		dijit._Templated ], {
	// Path to the template
	templateString : dojo.cache("widgets",
			"templates/HighSchooler.html"),

	// Widget properties
	fullName : "",
	grade : "",
	hero : "",
	stereotype : "",

	// Manipulate the widget's DOM, when ready
	postCreate : function() {
		// Using the attributes defined via dojoattachpoint
		this.nameNode.innerHTML = this.fullName;
		this.gradeNode.innerHTML = this.grade;
		this.heroNode.innerHTML = this.hero;

		// Setting the avatar to be the appropriate image
		var keys = {
			emo : "emo.png",
			geek : "geek.png",
			punk : "punk.png"
		};
		var key = keys[this.stereotype] || "na.png";
		var imagePath = dojo.moduleUrl("widgets",
				"themes/highschool/images/" + key).toString();

		// Set the 'src' attribute on our <img>
		dojo.attr(this.imageNode, "src", imagePath);
	}
});

Programmatic Widget Creation

OK, we’ve got everything defined. The question is, how do we get these bad-boys into a page? There are two ways to instantiate a Dojo Widget, programmatic and declarative. We’ll look at programmatic creation first. To create an instance of a widget, you simply ‘new’ it up. Optionally you can pass the ID of a node in your page where you would like the widget to appear. Alternatively, you can use the widget’s placeAt function if you need more finely grained control of where it shows up.

// Always dojo.require the resources that will be used
dojo.require("widgets.HighSchooler");

// Widget instances are almost always created inside a 'ready'
// block, as they represent DOM manipulation
dojo.ready(function() {
    // Replace the contents of the node with ID 'nodeId'
   // with our widget
    var kalEl = new widgets.HighSchooler({
        fullName:"Clark Kent",
        grade:"Senior",
        stereotype:"geek",
        hero:"Myself?"}, "nodeId");

    // Place our widget at the end of the node with ID 'nodeId'
    var kalEl = new widgets.HighSchooler({
        fullName:"Clark Kent",
        grade:"Senior",
        stereotype:"geek",
        hero:"Myself?"});
kalEl.placeAt("nodeId", "last");

});

The literal object that we pass in the constructor corresponds directly to the properties of our widget. Dojo takes care of initializing them for us. Slick!

Programmatic Widget Creation In Action!

Here’s a little demonstration of programmatic widget creation. I used Dojo to bind an event to the button that uses the value in the combo to programmatically create a new widget and add it to the end of the node below. When the button is clicked, this code is run. Try it out. Making Geeks is fun!

// Get the value from the combo
var typeOfTeen = dijit.byId('highSchoolerSelect').attr('value');
var newHighSchooler = new widgets.HighSchooler({
    fullName : "I was",
    grade : "created",
    stereotype : typeOfTeen,
    hero : "programatically"});

newHighSchooler.placeAt("teensGoHere", "last");

Declarative Widget Creation

Sometimes it is more convenient to specify a widget in markup. Using markup is also a fantastic way to quickly prototype your widget as you are developing it. Dojo provides the dojoType attribute to facilitate this. To declare a widget using markup, you simply specify the type-name of the widget using the dojoType attribute, and then specify any widget properties using attributes of their own. So if we wanted to declare a punk named Chris Jaun who’s hero is Bill Bradley, we’d do it like this.

<div dojotype="widgets.HighSchooler"
       fullName="Chris Jaun"
       grade="Senior"
       stereotype="punk"
       hero="Bill Bradley">
</div>

Which would get rendered like this.

(For all of you XHTML purists out there, dojoType is being deprecated in Dojo 1.6 in favor of HTML5′s data-* mechanism. Hooray for clean W3C validation scans!)

One thing to point out about declaring widget’s using markup is that in order to get Dojo to automatically parse the page for them, you have to set the parseOnLoad attribute to true in Dojo’s djConfig configuration variable.

Conclusion

Like most Dojo features, custom widgets are an incredibly powerful mechanism that would be impossible to fully cover in a single blog post. As such, expect many future Enterprise Dojo posts about this topic. I hope that this post piqued your attention and that you are now hungry to learn more. Check out this article in on dojotoolkit.org for a more detailed look at writing your own widgets.

As your web application requirements get more mature, separating and organizing your presentation layer is critical. Custom Dojo widgets enable us to create modular, reusable user interface components, something that every enterprise-caliber web application needs.

Stage One : Doubt

Description

As I discussed earlier, the Enterprise Developer’s usual introduction to JavaScript is less than stellar. Rightly so, when a developer hears that the next ‘Big Project’ will be done in JavaScript, their first thoughts are of the skeptical variety.

Symptoms

• Sufferer will indicate that the prospect of using JavaScript will certainly lead to folly.
• Sufferer will be heard saying things like, “JavaScript? Isn’t that the thing hackers use to screw up your Back button so you can’t leave a page?”

Stage Two: Hate

Description

Forced to learn JavaScript, the former-Java programmer decides that their 10 years of working with Java is more than enough experience to dive right in. Frustration of the highest order soon follows.

Symptoms

• Sufferer’s cubicle bookshelf is completely devoid of any books on JavaScript.
• Sufferer has web browser tab open to W3 Schools.
• Sufferer’s JavaScript code has been bent, battered, and forced to conform to the look-and-feel of Java.
• Sufferer’s screams of frustration are easily heard over hum of white-noise generator.

Stage Three: Begrudging Appreciation

Description

The most important stage. If the Enterprise Developer does not quit in spectacular fashion, the only other choice is to request time from management for some much-needed JavaScript education. Once the fundamental aspects of JavaScript are learned, productive results soon follow. Our Enterprise Developer recognizes that JavaScript has some good stuff in it, has discovered a great JavaScript toolkit like Dojo, and is producing efficient, cross-browser code. To be certain, the developer still hates JavaScript, however, this emotion has been put in check for the good of the project.

Symptoms

• Sufferer’s cubicle bookshelf contains both JavaScript: The Definitive Guide and Dojo: The Definitive Guide
• Sufferer has become proficient at debugging problems with Firebug, and cannot fathom a world without it.
• Sufferer’s code still looks a bit Java-ish, but contains healthy doses of lambda functions, asynchronous callbacks, and other JavaScript goodies.
• Sufferer begins to think about problem solutions in terms of JavaScript. Periodic returns to the Java world begin to feel awkward.

Stage Four: Love

Description

The final stage of JavaScript grief is one of gushing adulation. Most developers will remain indefinitely in Stage Three, but there are exceptions. The developer that reaches the ‘Love’ stage of JavaScript Grief has completely looked past all of JavaScript’s short-comings and finds joy in its powerful concepts.

Symptoms

• Sufferer’s cubicle bookshelf contains nothing but JavaScript books. Directly below bookshelf, sufferer will often build a shrine to Douglas Crockford and John Resig.
• Sufferer’s interest in JavaScript has moved beyond the browser. Sufferer will actively look for ways to add JavaScript into other parts of a software stack, usually in annoying fashion.