Basic Layout

So here's the cocktail napkin view of the email client:

Like most Outlook-inspired email programs, it will have a three pane, split-screen layout with a toolbar on top and status bar on the bottom. The left hand side will use accordion panes that flip up and down like a window blinds. Fortunately, all the layout tools you need are already in Dijit.

Andy likes to build the layout from the inside-out best, so he'll tackle the steps in this order:

1. Divide the screen into list and messages areas
2. Add the navigation bars - address book, message list, etc. - to the left hand area
3. Add the message preview pane
4. Add the tabbed panes for Compose Mail
5. Glue on the toolbar and progress bar

Dividing the Screen with SplitContainer

start with the message list and message area first. In between these two is the movable divider bar, called the sizer. In Dijit, you can use the dijit.layout.SplitContainer widget to model this like so:

Usually the innermost children in a layout are dijit.layout.ContentPane's. You can place arbitrary HTML in the pane, as we've done here, or lazy load the content from other URL's, like a server-side include.

The dijit.layout.SplitContainer itself can be oriented horiztonally or vertically, as the "orientation" attribute shows. A vertically oriented SplitContainer means the components are stacked vertically. Note that the orientation is opposite of the sizer bar orientation - i.e. if the SplitContainer is vertical, as it is in this case, the sizer orientation is horizontal. The sizer bar here is 5 pixels and changing it does not change the content immediately, as the activeSizing attribute shows.

The Navigation Bars: AccordionContainer

The left hand bar is an Accordion Container, which is easier to show than to describe. In Dijit, the dijit.layout.AccordionContainer holds dijit.layout.AccordionPane's, a special kind of ContentPane.

The title attributes give the label for the top of the AccordionPane. When the user clicks on this title or the arrow icon next to it, the pane will slide into view.

The Message Preview Pane - SplitContainer

Now we can glue these two pieces together with another SplitContainer, this one oriented horizontally:

Tabbed Panes - TabContainer

The whole thing will be situated in a tab named Inbox. Though our cocktail napkin drawing doesn't show other tabs, the idea is to open them for new email composition. This way you can work on many emails at once, clicking on the tabs to switch between them. Dijit has a widget dijit.layout.TabContainer, and like the Split and Accordion containers, it's a container for subscontainers and panes.

The dijit.Layout.TabContainer can hold as many tabs as you want, each marked with a title attribute used to title the tab. This illustrates a familiar pattern in Dijit. Sometimes a widget contains attributes that don't really deal with the widget itself - title, for instance, or sizeMin and sizeShare in earlier examples. They only make sense when that widget is used within other widgets. So an AccordionContainer ignores a sizeMin attribute, but because it's a child of a SplitContainer, the SplitContainer uses it for sizing. Title is similar. In a normal HTML tag, title would display a tooltip, but because the SpilitContainer is inside a TabContainer, the title is used specially.

What is that jsId attribute? jsId sets a global JavaScript variable for the widget, which will make it easy to script widget actions later. For example:

// Note used for step 1 - this is a preview
tabs.closeChild(tabs.selectedChildWidget);

closes the currently selected tab in the tab container. Without even knowing the Dijit API's, it's easy to understand what's going on here. That's object-oriented magic at work.

Gluing On Toolbar and Status Areas - LayoutContainer

To top it all off, we smush these tabs into a dijit.layout.LayoutContainer. A LayoutContainer was pioneered by Borland Delphi and copied in Java AWT and other toolkits. The idea is to split a box into five areas: top, bottom, left, right, and client (the middle). If the box is resized, the client area takes most of the growth or shrinkage - it's the document part of the app.

In our email client, the toolbar will occupy the top, the status bar the bottom, and the TabContainer the client portion:

The layoutAlign attributes tell LayoutContainer where they should be placed.

Now Andy just adds the standard Dojo headers and the skeleton is complete! /* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */ .geshifilter {font-family: monospace;} .geshifilter .imp {font-weight: bold; color: red;} .geshifilter .kw1 {color: #b1b100;} .geshifilter .kw2 {color: #000000; font-weight: bold;} .geshifilter .kw3 {color: #000066;} .geshifilter .coMULTI {color: #808080; font-style: italic;} .geshifilter .es0 {color: #000099; font-weight: bold;} .geshifilter .br0 {color: #66cc66;} .geshifilter .st0 {color: #ff0000;} .geshifilter .nu0 {color: #cc66cc;} .geshifilter .sc0 {color: #00bbdd;} .geshifilter .sc1 {color: #ddbb00;} .geshifilter .sc2 {color: #009900;}

There's no JavaScript at all beyond the dojo.require statements. And because he's using CDN, he didn't even have to install Dojo on the server. While Andy takes a moment to write more of his empassioned speech, you can download the code in step1.html below and try it out.

Ready? On to the next step...

The Address Book

Andy thinks, "That was easy. Now what's the next easiest thing to do?" The left-hand side panes, Address Book and Folders, will each have a tree. The Folders tree will have a heirarchy - folders within folders - but the Address Book is nice and flat. Andy figures he'll use the Address Book to learn Dijit Trees, then use his knowledge on the more complex Folders pane later. Here's the cocktail napkin view:

Back in the old days (i.e. 5 minutes ago), Andy would have drawn up a PHP file that sent all the markup for the Address Book tree - the folder IMG tags, the labels, etc. - over the wire. While this approach worked fine in the old days, he has learned it doesn't work well for Web 2.0 applications like this one. Why?

• It doesn't scale well. For a few entries, assembling the markup on the server, downloading, parsing and inserting the HTML is no problem. But this Address Book could contain hundreds or thousands of entries. And it will need to be drawn frequently.
• It requires PHP to generate JavaScript. Since each Book entry needs an onlcik handler, Andy would need to embed onclick handlers into each tag. Mixing languages like this requires him to juggle syntax in his head. His mind is on other things (remember the girlfriend? the proposal?)

Address Book Data - dojo.Data and JSON

He decides to leave the architecture questions alone for a moment, and looks at the Dijit catalog entry for Tree. The easiest data-driven way to approach this uses dojo.data. Dojo.data reminds Andy of ODBC in the Windows world, JDBC in Java, and DBD in PHP (Andy gets around.) Though dojo.data can talk to many different kinds of backing stores formatted in CSV, XML or HTML, Andy picks JavaScript Object Notation, or JSON. A JSON representation of the address book would look like this:

{ 
	identifier: 'id',
	label: 'label',
	items: [
		{ type: 'address', id: 'adam', label: "Adam Arlen" },
		{ type: 'address', id: 'bob', label: "Bob Baxter" },
		{ type: 'address', id: 'carrie', label: "Carrie Crow" }
        ]
}

JSON nicely represents JavaScript objects, bracketed by { and }, and arrays bracketed by [ and ]. The attributes identifier and label conform to dojo.data's metadata specifications. Dojo.data uses the drivers dojo.data.ItemFileReadStore and dojo.data.ItemFileWriteStore to read JSON data in this format.

Andy thinks, "it'll be a snap to write a PHP for that format!" For the demo, he will simply use the above file as mail/mail.json. If the project moves past the demo phase, he can replace it with a PHP that reads mail on the database server and outputs JSON. Good deal.

To connect his demo to the data store, he inserts this below the BODY tag:

He has decided to use the ItemFileWriteStore to write entries back later (maybe not in the demo, but later on.)

Displaying the Address Book - Tree

Now drawing the tree is a snap using dijit.Tree:

The store attribute connects to the jsId attribute on the ItemFileWriteStore. LabelAttr tells which attribute is used for the labels. Finally, the query tells dojo.data which entries to retrieve. You can equate a dojo.data query with a SQL query - it works with any backing store that dojo.data understands. As you can see here, a dojo.data query is much simpler than a SQL query. Sorting and compound selection are available for later, but for now this simple query will do fine.

Tree Icons - Extension Points

But wow ... what's up with that SCRIPT tag? What is type "dojo/method"?

That came about when Andy learned about tree icons ... the hard way. His first stab at dijit.Tree drew a nice address book but no icons. That wouldn't do. Clickdammit.com really, really likes icons. The trouble is there might be different icons based on the address book entry type.

At first Andy thought he'd have to modify dijit.Tree ... good thing Dojo is open source, right? But he'd been down that road before. You start monkeying around with changing the source and it becomes a never-ending struggle with revision control. So he read over the Dijit catalog entry for Tree and found:

An extension point is a point at which you can add, remove or replace functionality. The Dijit designers have built lots of extension points so you can change Dijit instances to your heart's content. And that's what Andy did.

First he looked up the signature for the extension point in the API guide: dijit.Tree.getIconClass:

getIconClass: function(/*dojo.data.Item*/ item){
		// summary: user overridable function to return CSS class name to display icon
	},

Since each of the address book entries was a dojo.data.Item, he had no problem passing something in. Now he can replace the guts of the SCRIPT tag with JavaScript code to read the icon attribute and turn it into a CSS class name. That class name points to the right icon specified in mail/mail.css. Problem solved!

One note about that "item &&" phrase. In Dojo 1.0, Trees always have one and only one root node. There is nothing in dojo.data that specifies items as root nodes, and thus the first item passed to getIconClass is always null. By saying "item &&" we take advantage of JavaScript's short-circuit && (and) operator. It says "if item is a false-y value (= false, 0, null), stop here and don't evaluate what's after the &&."

"Cool!" thought Andy. Extension points made it easy to change widget behavior, and dojo/method calls did the nasty job of wiring JavaScript code.

And with a few more header entries:

dojo.require("dojo.data.ItemFileWriteStore"); 
	dojo.require("dijit.Tree");

step2.html is now a working address book. If you don't believe it, download it and try it yourself! Then we'll move right along...

User Interaction

Pretty nice so far, but this app is long on displaying, short on interaction. So next Andy decides to add some toolbars, tooltips and dialog boxes. "Surely this will involve lots of JavaScript," he thinks.

Here's the cocktail napkin view of the toolbar:

We already have the dijit.Toolbar widget in the app as a placeholder. Dijit.toolbar expects its immediate children to be buttons:

• dijit.form.Button is a plain ol' command button, but better.
• dijit.form.DropDownButton, when clicked, displays a menu of commands
• dijit.form.ComboButton combines the two - acting like a button when clicked, or a menu when held-down.

Getting Mail - ComboButton and Tooltip

The New Mail button is a ComboButton:

The dijit.Tooltip does what you think it should - it displays a message when the user hovers over the button. It knows this by connecting the connectId to the id attribute of the widget.

At the heart of a ComboButton or DropDownButton is a dijit.Menu, itself composed of dijit.MenuItem objects. Andy chooses not to wire the items - Yahoo and GMail - to an event handler yet. But he does tie the onClick handler of the ComboButton itself.

Like for the Tree, Andy uses a dojo/method script to fire off a snippet of JavaScript. In this case, it's a stubbed out function called fakeDownload(). But wait! Can't you just do this? /* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */ .geshifilter {font-family: monospace;} .geshifilter .imp {font-weight: bold; color: red;} .geshifilter .kw1 {color: #b1b100;} .geshifilter .kw2 {color: #000000; font-weight: bold;} .geshifilter .kw3 {color: #000066;} .geshifilter .coMULTI {color: #808080; font-style: italic;} .geshifilter .es0 {color: #000099; font-weight: bold;} .geshifilter .br0 {color: #66cc66;} .geshifilter .st0 {color: #ff0000;} .geshifilter .nu0 {color: #cc66cc;} .geshifilter .sc0 {color: #00bbdd;} .geshifilter .sc1 {color: #ddbb00;} .geshifilter .sc2 {color: #009900;}

Yes, but you wouldn't want to. Using dojo/method and connecting to the extension point gets you the DOM Level 2 event model for free. DOM Level 2 events pass much more information to the event handler. And before you ask ... yes, this even works in Internet Explorer, which doesn't natively support the DOM Level 2 event model. Dojo adds a nice layer which emulates the model on IE.

Sweet! That's cross-browser functionality for free. Dojo is really, really good at that.

New Mail and Options - Dialog Boxes

So let's look at the other buttons:

There's nothing here we haven't seen before ... except the call to optionsDialog. This displays a dialog box, which should look like this:

Now this looks like a regular HTML form, and in fact we'll code it as if it were. But ... we'll use a dijit.Dialog to do it. The good news is that unlike HTML forms, a dijit.Dialog acts modally, leaving all the information and page state alone while the user fills in the dialog details. So the server interaction happens in the background.

The code for the dialog box goes at the bottom of our app, just above the /BODY tag, separated away from all the other HTML:

You can look at dijit.Dialog as a mini-form, with Dijit form elements sprinkled into it. Note, we don't do anything with the data here, but a finished app would save the settings and communicate them back to the server.

Andy places the dojo.require's in the header

dojo.require("dijit.form.Button"); 
dojo.require("dijit.Menu");
dojo.require("dijit.Tooltip");
dojo.require("dijit.Dialog");
dojo.require("dijit.form.ComboBox"); 
dojo.require("dijit.form.CheckBox"); 
dojo.require("dijit.form.FilteringSelect");
dojo.require("dijit.form.Textarea");

And step 3 is done. "Wow," Andy thought, "that's a lot less JavaScript than I thought." To tell the truth, there is a lot of JavaScript behind it, but you didn't have to write it. Dojo has it all!

A Compose Mail Widget

Next, Andy needs a Compose Mail window that looks like this:

Hmmmm, composing HTML email looks like it might be a problem. There's that huge toolbar and all those display stuff. Well, to be honest, with Dojo that's the easiest part of this step. Simply write a template like this:

And save it in the file mail/newMail.html on your server. The dijit.Editor widget sets up the word-processor like environment for you, complete with toolbar, accelerator keys, and a fairly full array of HTML tools. The LinkDialog plugin adds an "Add Link..." button to the editor. Wow! It's a 5 line word processor. Andy mentally files this away - it could come in handy for composing his heartfelt speech later!

Using Dijit components is fun in a geeky sorta way. Still, Andy was one of those kids who got bored with Lego's ... until he made new ones with a band saw and a soldering iron.

If there were only one Compose Mail screen at a time, he could model it as a single tab and show it when necessary. But we need more than one. Andy thinks ... if one could just make a Compose Mail widget, then you can create as many instances as you want.

You can do that! And just like you can create widget instances declaratively or programmatically, so you can create new widget classes declratively or programmatically. As you might guess, the declarative way is easier. You simply pull out the dijit.Declaration widget.

Dijit.Declaration defines a widget class using a familiar macro-like template. Let's take a look:

The HTML defined inside the dijit.Declaration tagis dropped in wherever the widget class "mail.newMessage" is requested. You could, in fact, drop one in like this:

You pass parameters to your new widget by using:

• An attribute on the calling side: in our case, we set id="myNewMessage" to pass the parameter "id".
• A ${___} on the declaration side: in our case, we have ${id} marked several places in the definition. These are substituted with myNewMessage in this call.

This declarative usage is neat, but not helpful in our case since we don't know how many newMessage components to create. Instead, we create instances programmatically using the Compose Mail button:

This new code creates a mail.NewMessage programmatically, then creates a Tab out of it and adds it to the TabContainer (specified by the JavaScript variable newTabs)

Add some declarations and a few supplemental variables to the header:

dojo.require("dijit.Declaration");
dojo.require("dijit.Editor");
dojo.require("dijit._editor.plugins.LinkDialog");

// Global var for new mail pane
var paneId=1;
        
// for "new message" tab closing
function testClose(pane,tab){
  return confirm("Are you sure you want to leave your changes?");
}

And now we can compose mail to people.

Mail Progress Bar

The people who run clickdammit.com are cheapskates. Their servers are Pentium Pros bought off Ebay in exchange for some Beanie babies. So Andy knows that users will click "Get Mail" and wonder what's taking so long.

This is a common problem in Web 2.0 applications. Hopefully your servers are faster than Pentium Pros, but even then you can't always be sure when response times will be slow. Since you're not submitting the form, you can't rely on the browser's spinning logo to tell the user something's happening.

Fortunately, Dijit has a progress bar for those situations. Andy doesn't have access to clickdammit's mail server yet, but he decides to sketch out the progress bar and write some Wait loops behind them to simulate delays.

First he places the progress bar where the placeholder text was:

We make this progress bar hidden so it can be called up when needed. At first the progress will be incalculable since we don't know the number of messages to download. That's what "indeterminate=true" shows.

We have already stubbed out fakeDownload() and connected it to the Get Mail button. Now we can actually add some code to it.

var fakeDownload = function(){
	dojo.byId('fetchMail').style.visibility='visible';
	numMails = Math.floor(Math.random()*10)+1;
	dijit.byId('fakeFetch').update({ maximum: numMails, progress:0 });
	dojo.fadeIn({ node: 'fetchMail', duration:300 }).play();
	for (var i=0; i<=numMails; i++){
	    setTimeout(
                      "updateFetchStatus("+i+")",
                      ((i+1)*(Math.floor(Math.random()*100)+400))
            );
	}
}

First we turn on the progress bar, then pick a random number (1 to 10) of emails to download. Now to update the progress bar ... Andy looks up the dijit.ProgressBar widget in the Dijit catalog and finds under Methods:

Update looks good, and he consults the example before writing the update statement.

dojo.fadeIn does what you think. It fades-in an object but turning up the opacity from 0% to 100%. The "300" here is the number of milliseconds fadeIn should take to complete its job. 0.3 seconds sounds small, but it's enough to make the animation noticeable without stopping the proceedings.

Any adds the updateFetchStatus function, which will fire once for every email.

var numMails;
var updateFetchStatus = function(x){
	if (x == 0) {
		dijit.byId('fakeFetch').update({ indeterminate: false });
		return;
	}
	dijit.byId('fakeFetch').update({ progress: x });
	if (x == numMails){
		dojo.fadeOut({ node: 'fetchMail', duration:800,
			// set progress back to indeterminate. we're cheating, because this
			// doesn't actually have any data to "progress"
			onEnd: function(){ 
				dijit.byId('fakeFetch').update({ indeterminate: true });
                                // remove progress bar from tab order
				dojo.byId('fetchMail').style.visibility='hidden'; 
			}
		}).play();
	}
}

dojo.fadeOut looks a lot like fadeIn, but the onEnd property is new. It expects a function as its property. Here we add a function literal that removes the progress bar from the screen. But why put this in onEnd? Why not just put it after play()? Andy tried that first, and found the progress bar would blink out before it had completely faded. That's because fadeOut, like all Dojo animations, runs asynchronously. In other words, it kicks off the fadeOut and starts executing the next statement. FadeOut continues executing. So setting the duration to 800000000 would make the animation slow, but the browser would still be immediately usable.

Finally, we connect a function to ProgressBar's "report" extension point. Remember how we specified report="fakeReport" in the Progress Bar tag? Now we can fill it in. Report gets passed in a percent and expects a string to place on the progress bar.

var fakeReport = function(percent){
    return "Fetching: "+(percent*this.maximum) + " of " + this.maximum + " messages.";
}

Andy clicks on the Get Mail and sits back. It looks darn good! He clicks it a few more times just to make sure. Very nice. We're getting pretty close to a working demo to show off. Just a few more things need to go in place.

Mail Folders and dojo.Data

JSON and dojo.data stores worked pretty well for address book data. Andy wonders whether they would work to send mail and folders too.

Not only is it possible ... you can pass all the data back in one fell swoop. This is possible because ItemFileReadStore and JSON handle heirarchical data with ease. In mail land, you have folders which contain other folders or mail items. In JSON notation, you can model folders like this:

{ 
identifier: 'id',
label: 'label',
items: [
	// Hierarchy of folders

	{ type: 'folder', id: 'mailbox', label:'Folders', folders: [
		{ type: 'folder', id: 'inbox', label:'Inbox', icon:'mailIconFolderInbox' },
		{ type: 'folder', id: 'deleted', label:'Trash', icon:'mailIconTrashcanFull' },
		{ type: 'folder', id: 'save', label:'Save',  folders:[
			{ id: 'work', label:'stuff for work'},
			{ id: 'fun', label:'stuff for fun'}
		]}
	]},

You can see how we nest objects within objects, like the "work" and "fun" folders underneath the "Save" folder. We can model mail like this:

// Flat list of messages (each message lists its folder)

	{ type: 'message', id: 'node1.1',
                  folder: 'inbox', label: "today's meeting", 
                  sender: "Adam Arlen", sent: "2005-12-19",
	          text: "Today's meeting is cancelled.
Let's do it tomorrow instead.

Adam" 
        },
	{ type: 'message', id: 'node1.2',
                  folder: 'inbox', label: "remaining work", 
                  sender: "Bob Baxter", sent: "2005-12-18",
	          text: "Hey, we need to talk about who's gonna do all the left over work.  Pick a day you want to meet: 
"
	},

Now you have three types of objects, delineated by type: address, folder and message. Andy decides to stick them all in one JSON data message. That means only one trip ito the server grabs everything about the user's mail store. Gotta love that!

The actual folder listing looks a lot like the address book code. The getIconClass extension point draws the folder icons:

The "childrenAttr" in the Tree tag does all the sub-folder magic.

One more thing and he'd be ready to show it to Ms. Opulence: connect the folders to messages and the messages to a preview pane. Andy looks at his watch. He's got about 15 minutes before the el stops by his office. If he could catch it and get home early, that'd give him some serious writing and reflecting time. So let's make short work of this, shall we?

The Message List - dojox.Grid

Andy has been studying up on Dojo 1.0, and found one of the great new features - the Dijit grid. A grid is like a mini spreadsheet, or a maxi-HTML-table. You can sort the columns, edit cells, and enable all kinds of cool stuff. It sounds like the perfect container for a message list.

Feeding the Grid

Once you've worked with Dojo awhile, you start to see Grand Unifying Themes. One of them is dojo.data, feeding server-pulled data to different kinds of widgets. Grid is no different. Fortunately, Andy already has the data store defined. And since that data store has messages in it, hierarchically tied to folders, it's a short step to display them. First he adds the separate Grid style sheet:

A grid has two main elements: the model and the structure. The model is the data behind the grid, while the structure is a set of display instructions.

Andy does the model first. We already havy the data in a dojo.data store called mailModel. To make the data source mailStore work with Grid, he declares a dojox.grid.data.DojoData adapter. You can think of it as a pipe where the data flows in, and the appropriately filtered data comes out for use in a grid. When the app initially starts, there is no folder selected. Hence there are no messages to display. Andy decides to initialize the adapter, but issues a query that will return no items. This has performance benefits, as we'll see in a minute.

The structure is a description of the Grid layout. Structures are composed from views, which are little independently scrollable subgrids called views. Our grid is simple, containing only one view. A cell is Grid's name for a column.

var mailView = {
    cells: [[
        {name: 'From', field:'sender',width:"25%"}, 
        {name: 'Subject', field:'label',width:"65%"},
        {name: 'Date', field:'sent',width:"10%"}
    ]]
};

var layout = [ mailView ];

The cells property is a two dimensional JavaScript array, hence the double square brackets. In the Grid section, you'll see how to split large amounts of data into subrows, all selectable as one unit. Here we have just one subrow with a small amount of data.

Wiring up the actual Grid is a snap. The Grid widget does all the work for you:

Clicking a row in this grid will display the appropriate message in the bottom area. So Andy stubs out the call to the onRowClick event, which he'll fill in later.

In the folder tree, Andy connects some Dojo code to the onClick event. Once you know the folder name, you simply build a new adapter, set that as the Grid model, and the grid will automatically populate. The nice thing here is the Mail messages are already loaded in the dojo.data store. Building a new Grid model on top of it re-uses the data with a new query without a server round-trip.

So now clicking a folder displays the message list. It's time to go back and fill in onRowClick for the message. This turns out to be fairly trivial:

function displayMailMessage(evt) {
     var msg = mailGrid.model.getDatum(evt.rowIndex,6);
     dijit.byId("message").setContent(msg);
}

So now he has a message list and a message. Andy looks at his watch. 5 minutes to spare. He can't resist adding one more item - displaying a widget inside a mail message. So he quickly adds a test case to the sample data:

{ type: 'message', id: 'node4.4', folder: 'fun', 
   label: "paint", sender: "Jack Jackson", sent: "2005-12-16", 
   text: "what color is good for the new office?
Let me know soon"
},

And dojo.require's dijit.ColorPalette. Sure enough, displaying the message automagically displays the palette:

Summary

Wow! That's a lot of functionality. In a short amount of code, about 1/2 JavaScript and 1/2 HTML, we have a working email client user interface with:

• Command buttons with icons
• An Options dialog box
• A tabbed interface where you can compose multiple emails at once and quickly switch between them.
• A full HTML-based email format. You can create, edit and read email messages with full, rich formatting.
• An address book and folder list, heirachically arranged with expansion and contraction buttons.
• A message list tied to the folders with a click
• Lots of little user cues - tooltips and a progress meter for downloads

Sure, the server part needs writing. But that can wait until tomorrow, and it shouldn't be too difficult. Find the right words to get a woman to marry you ... now that's difficult. Andy heads out the door for the train

Architecture

Laura, being the agile programmer she is, wants to first build the smallest solution that solves the problem. She sighs, longing for the days of C and network sockets. But JavaScript's security model prohibits peer-to-peer networking, so there's nothing like that.

She looks on the Dojo site and finds the cometd (pronounced comet-d) server. Interesting! It's a lightweight, HTTP-based server with a small footprint. And it is supposed to have good Dojo integration through publish-subscribe events.

Publish-Subscribe

Publish-subscribe is an easy-to-understand model for cross-process communication, and Dojo has it baked in. It effectively promotes loose coupling between components. Suppose you have a tax form similar to Example 1. You have ten dijit.form.CurrencyTextBox's whose contents get added up to a Gross Income, another dijit.form.CurrencyTextBox. How do you keep Gross Income updated? One way is for the component CurrencyTextBox's to call a central procedure for updating:

Because this system is tightly coupled, problems arise:

• If you add an 11th line to total up, you must change the reAdd() procedure.
• If half of the boxes need to send extra onChange events to computeDeductions(), those half need to be changed to call this method.

Granted, this example is contrived because the methods are so small. But the larger your system, the more nightmarish maintenance becomes. It would be nice to have a whiteboard where controls could sign up for events that interest them. This whiteboard could be maintained by a third party to keep the controls from worrying about communication details.

That's the essence of publish-subscribe. Dojo is the whiteboard maintainer. The GrossIncome box then says "I'm interested whenever a box changes." This is called a topic, and we say the GrossIncome box subscribes to that topic. The component boxes agree to publish information on this topic when they change. Here's how it looks like in code:

So the topic "componentChange" is published when any of the component boxes change. Sent along with the topic are message-specific data elements that help the subscriber - oldValue and newValue in this case. Need to find which elements in the event object they are.. The lone subscriber, the GrossIncome box, uses these to adjust the current sum. Now to add a component box, you just add it to the form with the same dojo.publish statement. Very nice.

Publish-Subscribe With Cometd

Cometd effectively extends Dojo publish-subscribe past the browser. Cometd speaks the Bayeaux protocol which itself runs over HTTP. Laura immediately sees the usefulness of this for online support. The client can publish a topic to Cometd containing the message. The operator subscribes to that topic and displays messages on the console. It replies on that same topic. Both operator and client send the userid with the message, so they can ignore the message they themselves send.

The protocol works like this. Assume the client's username is "alex.russell" and operator's username is "operator".

• Operator:
• (Time Marches On...)
• Client: Subscribe to "/chat/demo/alex.russell".
• Client: Publish a message on "/chat/demo/alex.russell": { user: "alex.russell", join: true, chat : "alex.russell has joined the room."}
• Client: Publish a message on "/chat/demo": { user: "alex.russell", joined: "alex.russell"}
• Operator: (Sees message on /chat/demo) Subscribe to "/chat/demo/alex.russell"
• Client: Publish a message on "/chat/demo/alex.russell": { user: "alex.russell", chat : "I have a question about Dojo."}
• Operator: (Sees message on /chat/demo/alex.russell) Publish a message on "/chat/demo/alex.russell": { user: "operator", chat : "Shoot."}
• Client: (Sees message on /chat/demo/alex.russell) Publish a message on "/chat/demo/alex.russell": { user: "alex.russell", chat : "Oh wait, I invented Dojo. Never mind."}
• Client: Unsubscribe to "/chat/demo/alex.russell"
• Client: Publish a message on "/chat/demo/alex.russell": { user: "alex.russell", leave: true, chat : "alex.russell has left the room."}

Although the protocol looks a little "chatty", Laura has designed it with public chat rooms in mind. When those come to pass, users will be able to join arbitrary public chat rooms using this protocol.

This upfront design will payoff - coding will go quite rapidly.

Details for the Impatient

• Cometd Server
• Publish-subscribe events
• dojox.cometd - cometd client support in Dojo
• dijit.form.CurrencyTextBox

The Room Widget

In previous examples, we have built a few widgets with the dojo.Declaration tag. This is a fast way to add functionality, but the problem is sharing it with other pages. Although Laura knows the Operator and Client pages will be different, she senses common elements in the way they chat. So she will define a widget class through JavaScript instead. That way, both pages can use it.

The Widget Skeleton

A widget is a way to tie Dojo API calls into one displayable element. The way Laura designs it, the display is pretty much the same on both sides. The only difference is the container. Here's a cocktail napkin view of the client side:

And the operator side:

To be added once we get the public cometd server up.

The message display area, the input box for messages and the send button are exactly the same. So we can package those up as a widget, which we will call dijit.demos.chat.room. Using a little object oriented analysis, Laura stubs out the object code:

dojo.provide("dijit.demos.chat.room"); 

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

dojo.declare("dijit.demos.chat.Room",
    // All widgets inherit from _Widget, and all templated widgets mix in _Templated
    [dijit._Widget,dijit._Templated],
    {
    
        // Username of client
    _username: null,
    
        // Default room id.  Will become the client's username for our tech support line
    roomId: "public",
    
        // For future expansion into public chat rooms
    isPrivate: false,
    
        // Constant
    prompt: "Name:",
    
    join: function(name){
            // Join a room
    },
    
    _join: function(/* Event */e){
            // Respond to someone joining a room (only operator does this)
    },
    
    leave: function(){ 
            // leave a room
    },
    
    chat: function(text){
            // Send a message
    },
    
    _chat: function(message){
            // Receive a message
    },
    
    startup: function(){ 
            // Required function for a widget.  Called on startup
    },

});

The Widget Template

As we did in Example 1 for i18n, we build a template for the widget. Essentially this template will replace the tag with dojoType="dijit.demos.chat.room"

The placeholders ${id} and ${prompt} look familiar. These are replaced with the properties id and prompt from the widget instance. A few of the properties look unfamiliar, but they all start with the prefix "dojo".

• dojoAttachPoint creates a property in the widget containing the DOM node. For example, the DIV tag with dojoattachpoint="joining" creates a joining property, which you can pick up with "this.joining" in your widget code. You can do with anything you can do with a DOM node, for instance set its styles or CSS class.
• dojoAttachEvent connects an event and DOM node with a function. So dojoAttachEvent="onkeyup: _cleanInput" means "when the onkeyup event happens here, call _cleanInput."

Only one of the "joining" node:

and the "joined" node:

is visible at any one time. That gives the illusion that the "joined" and "joining" nodes toggle back and forth, occupying the same screen real estate. This is a fairly common trick in widget templates.

Starting the Widget

Every widget has extension points that get called during widget creation. The widget class designer can hook into these by providing methods, as we do here with startup():

startup: function(){ 
    this.joining.className='';
    this.joined.className='hidden';
    //this.username.focus();
    this.username.setAttribute("autocomplete","OFF");
    if (this.registeredAs) { this.join(this.registeredAs); } 
    this.inherited("startup",arguments); 
},

this.inherited() acts like Java's super() operator, but more generally. Here it calls dijit._Widget.startup(). This is a good practice to get into for the widget extension points.

Joining and Leaving a Room

Dojo calls the join method upon clicking the Submit button. Just as we outlined on the previous page, it establishes the chat connection with the operator (only the client calls this particular method). "_join" does the same thing in response to keystrokes.

Note how the dojoAttachPoints come in handy here: they make flipping the nodes on and off straightforward.

join: function(name){
    if(name == null || name.length==0){
        alert('Please enter a username!');
    }else{
        if(this.isPrivate){ this.roomId = name; } 
        this._username=name;
        this.joining.className='hidden';
        this.joined.className='';
        this.phrase.focus();
        dojox.cometd.subscribe("/chat/demo/" + this.roomId, this, "_chat");
        dojox.cometd.publish("/chat/demo/" + this.roomId, 
           { user: this._username, join: true, 
             chat : this._username+" has joined the room."}
        );
        dojox.cometd.publish("/chat/demo", { user: this._username, joined: this.roomId });
    }
},

_join: function(/* Event */e){
    var key = (e.charCode == dojo.keys.SPACE ? dojo.keys.SPACE : e.keyCode);
    if (key == dojo.keys.ENTER || e.type=="click"){
        this.join(this.username.value); 
    }
},

Leaving, for the most part, just reverses the join sequence:

leave: function(){ 
    dojox.cometd.unsubscribe("/chat/demo/" + this.roomId, this, "_chat");
    dojox.cometd.publish("/chat/demo/" + this.roomId, 
       { user: this._username, leave: true, 
         chat : this._username+" has left the chat."}
    );

    // switch the input form back to login mode
    this.joining.className='';
    this.joined.className='hidden';
    this.username.focus();
    this._username=null;
},

Sending and Receiving a Message

Finally, the meaty part of the Room widget. Sending is a fairly simple matter over our protocol:

chat: function(text){
    // summary: publish a text message to the room
    if(text != null && text.length>0){
        // lame attempt to prevent markup
        text=text.replace(//g,'>');
        dojox.cometd.publish("/chat/demo/" + this.roomId, { user: this._username, chat: text});
    }
},

Receive is handled by the topic subscriptions, which we connected in join(). The event mediator sends receive() a message, which becomes the parameter "message" here. Then message.data contains the object that the publisher sent over.

_chat: function(message){
    // summary: process an incoming message
    if (!message.data){
        console.warn("bad message format "+message);
        return;
    }
    var from=message.data.user;
    var special=message.data.join || message.data.leave;
    var text=message.data.chat;
    if(text!=null){
        if(!special && from == this._last ){ from="...";
        }else{
            this._last=from;
            from+=":";
        }

        if(special){
            this.chatNode.innerHTML += 
                ""+from+
                " "+text+"
";  
            this._last="";
        }else{
            this.chatNode.innerHTML += 
                ""+from+" "+text+
                "
";
            this.chatNode.scrollTop = this.chatNode.scrollHeight - this.chatNode.clientHeight;    
        }
    }
},

Entering and leaving messages use the alert CSS class to distinguish them from regular chat messages.

There's our bouncing baby widget! Now let's make use of it...

Details for the Impatient

• Creating a Widget Class
• Publish-subscribe events

The Client Page

The client page uses some eye candy from Dojo. (Clients love eye candy!)

Animation

The client chat window can be open and closed at will. Laura decides that the window should fade in and fade out - an easy thing to do with Dojo.

An animation in Dojo terms is the graduated movement of a DOM node from one state to another. A fade-in, for example, is the movement of opacity (the opposite of transparency) from 0% to 100%. Animations cover a set span of time, so you can fade in over the course of milliseconds, seconds, or minutes. In Dojo Animation, the most general form of an animation is a function. Some animations are so popular, like fades and slides, that Dojo packages those functions for you.

The animation for fading in, triggered by the Show button, looks like this:

The fade-in lasts for 400 ms. We hook a snippet of code in front of the animation to set the panel to display:block mode first, turn it on and position it to the top of the screen. This is necessary because opacity only works on an element that's actually displayed ... if it's display:node, as our node starts out as, the fade in won't work at all.

Because the corresponding fade-out for hiding is very similar, we rewrite the extension point to handle both jobs. helpNode.open is true if the chat window is currently open.

Keeping the Window Visible

Of course we don't want the chat window to scroll up as the user scrolls up. So we hook some code into the onScroll event of the window. onScroll is one of those handy Dojo Events. It is actually a front for the DOM Level 2 event of the same name, which Firefox implements in a standard way, and IE in a non-standard way. Well, we don't have to worry about that. That gives Laura more time to be creative.

// this puts our help box in the top/right corner on scroll and show
function _positionIt(evt){
    if (helpNode.domNode.style.display == "block"){
        dojo.style(helpNode.domNode,"top",(dijit.getViewport().t + 4) + "px");
    }
}

var helpNode; 
dojo.addOnLoad(function(){ 
    dojo.parser.parse(dojo.body()); 
    helpNode = dijit.byId('helpPane');
    dojo.connect(window,"onscroll","_positionIt");

    // this is a placeholder for the cometd server, once we get a public one.
    dojox.cometd.init("http://comet.yours.com:9000/cometd"); 
});

_positionIt repositions the window to be 4 pixels from the top of the viewport, which Dijit provides through its handy dijit.viewport function. The four viewport coordinates are kept in properties t, b, l and w (top, bottom, length, width).

dojo.addOnLoad specifies a code snippet to be run after all the DOM nodes have loaded and widgets have been drawn. It's a good place for connecting events, as we've done here with onscroll. Finally, we connect to the cometd server for the chat.

Lastly, Laura needs the operator page...

The Operator Page

The operator, unlike the client, can carry on multiple conversations. So they can subscribe to many chat topics, all called /chat/demo/username for uniqueness. Each conversation will have a different Room widget in a different ContentPane

When a message arrives, it may be a new chat request or an existing conversation. We keep track of this in objects that correspond to conversations. First, the addOnLoad starts subscriptions running:

dojo.addOnLoad(function(){ 
	dojo.parser.parse(dojo.body());

	dojox.cometd.init("http://comet.sitepen.com:9000/cometd"); 
	dojox.cometd.subscribe("/chat/demo",control,"_getAlert");

});

The control object is an overall controller for operator conversations. Here's a skeleton:

var control = {
    _chats: {},
    _getAlert: function(e){
    },

    _privateChat: function(e){
    }
};

Coversation records are kept in the _chats object, which will be a hash of username keys with current conversations. Through our subscribe() above, _getAlert will get any messages over the public topic /chat/demo. It will then either create a new conversation and tabbed pane or simply return:

_getAlert: function(e){
    // Ignore all control messages where we already have a conversation registered, 
    // or messages bound for someone else.
    if (!this._chats[(e.data.user)] && (operator != e.data.user)){
        dojox.cometd.subscribe("/chat/demo/"+e.data.joined,this,"_privateChat");

        // Create a tab called chatWithUsername and insert it into the tabbed container
        var tabNode = document.createElement('div');
        tabNode.id = "chatWith" + e.data.user; 
        var chatNode = document.createElement('div');
        chatNode.id = e.data.user + "Widget";
        tabNode.appendChild(chatNode);
        var newTab = new dijit.layout.ContentPane({
            title: e.data.user,
            closable: true
        },tabNode);
        dijit.byId('tabView').addChild(newTab);

        // Create an associated Room object
        var chat = new dijit.demos.chat.Room({
            roomId: e.data.joined,
            registeredAs: operator
        },chatNode);
        chat.startup();

        // And record this conversation
        this._chats[(e.data.user)]=true;
    }
},

The subscription to /chat/demo/username passes received messages to the proper ContentPane:

_privateChat: function(e){
    var thisChat = dijit.byId(e.data.user+"Widget") || false;
    if (thisChat) { thisChat._chat(e); }
}

Laura calls over one of her team members and shows him the chat function. On separate PC's they play with it for about 15 minutes or so, trading war stories and jokes. It feels pretty nice to have a working system built this quickly and with so little code. Laura no longer misses C.

Form Widget

Although you're not required to place Dijit form elements in a dijit.form.Form, doing so gets you some nice methods and extension points to use.

CheckBox, RadioButton, ToggleButton

dijit.form.CheckBox, dijit.form.RadioButton, and dijit.form.ToggleButton capture binary user-choices. Unlike command buttons, which do some action on being pressed, these buttons are more for form data. ToggleButtons can be used on Toolbars - the Bold button being the classic example - so they act a little like a data button, a little like a command button.

Examples

CheckBoxes in dijit are very intuitive and easy to use. Markup constructs for check boxes is the same as html but dojo provides more control and styling options than a conventional check box. The following example creates a CheckBox:

Are you a Developer

dijit.form.ToggleButton works very similarly to a checkbox, but requires including the "dijit.form.Button" module.

RadioButtons in dijit are also easy to create and use as the following example shows:

Metallica Extreme Slayer

The RadioButton class is declared in the CheckBox.js file, hence you need to dojo.require() only dijit.form.CheckBox for RadioButtons to work.

Accessibility

Keyboard

Tabbing moves through each form element, however, for radio buttons, tabbing will only go to the currently selected item in the radio group.

ComboBox

The ComboBox is a hybrid between a SELECT combo box and a text field. Like a SELECT, you provide a list of acceptable values. Unlike SELECT, and like a text box, the user can ignore all the choices and type whatever they want. This is especially good for open-ended multiple choice questions.  Rather than having two fields - a combo box and an Other text box - you can use just one field.

Note that SELECT's always have value/description pairs, e.g. the OPTION's value attribute and the OPTION's body text. ComboBoxes do not. They only pass their displayed text - just like a text box.

Examples

Using inlined data with the ComboBox is very much like using a native <select> tag:

California Illinois New York Texas

Name and autocomplete are passed through to the HTML. The value attribute enables you to set the default value. The option tags do not have hidden submit values; to use a hidden value, change your ComboBoxes to FilteringSelects.

Important: IE7 only uses the selected attribute of an option tag and ignores the value attribute on the select tag. For best results, set both the selected attribute on the default option and the value attribute on the select.

dojo.Data-Enabled ComboBox

ComboBox, FilteringSelect, Tree and Grid are dojo.data-Enabled widgets. This means rather than specifying all the data in the page - the OPTION's or tree nodes - you can have dojo.data fetch them from a server-based store. The unified dojo.data architecture, can get its data from various places - databases, web services, etc.. See the dojo.data manual section for complete details.

The code:

... looks like a widget, but it's not. (Only dojoTypes from the module dijit.___ are widgets). This tag takes advantage of dojo.parser, which creates JavaScript objects by using standard HTML. You can read about Dojo.parser at Understanding the Parser in Part 3.

For this example, we'll use a fixed JSON data store. You can download it from states.txt below. Here's an excerpt:

The following example makes use of our data store:

jsId is the name of the global variable that the store is assigned to. url can be used to suck data out of particular URL, perhaps a web service. Instead of using the url attribute, you can embed your data directly (as is common in traditional server-side programming) using the data attribute.

Accessibility

Keyboard

Known Issues (updated for 1.1)

JAWS 8 and Window-Eyes 6 may fail to read an option when it becomes highlighted. In Dojo 1.1 the Combobox was updated so that JAWS 9 will speak "editable combo" when the Combobox gets focus. However, there are some issues reading the highlighted choice. Generally JAWS 9 with Firefox 2 will only speak the part of the word that is currently selected in the textbox. For example, if you are working with a ComboBox containing the US state names and you type in an "I" to filter the list of states. If the user arrows down and highlights "Iowa" in the drop down list, "Iowa" will be displayed in the textbox with the "owa" portiion selected. JAWS 9 will speak, "owa" rather than "Iowa". This is not an issue with Firefox 3 and JAWS 9.

FilteringSelect

FilteringSelect is like an HTML SELECT tag, but is populated dynamically. It works very nicely with very large data sets because it can load and page data as needed. It also resembles ComboBox, but does not allow values outside of the provided ones.

When the user tries to submit invalid input (say if they choose an option, and the legal options change) the user gets a warning message, but the Select keeps text box input as is and also keeps the last valid submit value. If the user selects the text box and presses Escape on the keyboard, the text box reverts to the last valid value, corresponding to the hidden value. This change guarantees that you will always get a valid submit value.

Examples

First, here is a FilteringSelect with inlined data:

California Illinois New York Texas

As with ComboBox, has a value attribute. Unlike ComboBox, this value refers to the value attribute of the <option> tag. For example, if you set the value to AL, the text "Alabama" will appear in the text box on load. If you want to change the value attribute programmatically, use

Like ComboBox FilteringSelect is dojo.data-enabled. As with all dojo.data stores, you can add an identifier field to the top level of your data. The value of the identifier field tells the store which field in your data contains the submit value. Here's an example from states.txt:

This code shows an identifier set to abbreviation. The identifier instructs the dojo.data store to set the submit value of the items in this store to the value of the attribute named abbreviation. In this example, the first item has a field named abbreviation with a value of AL. If one of your users selected that item in your FilteringSelect, the form would submit AL to your server.

Here's the corresponding FilteringSelect

The net result of the identifier is that you can easily set the submit attribute of any number of Selects using the same data without actually adding extra attributes to the Selects.

Accessibility

Keyboard

Known Issues

JAWS 8 and Window-Eyes 6 may fail to read an option when it becomes highlighted.

InlineEditBox (0.9)

InlineEditBox is better described as a widget wrapper, which takes a child widget declared in markup and makes it inline-editable. This widget acts like a <div> tag when not in edit mode. When the contained rendered text is clicked, the widget enters an edit mode. In this mode, the previously displayed text is hidden, and another widget capable of editing text is made visible in its place.

Examples

The outermost span is the InlineEditBox. The inner input tag is the TextBox widget. When a user loads the page, they see the text "Edit me - I trigger the onChange callback". If the user clicks the text, a TextBox widget containing the text "Edit me - I trigger the onChange callback" appears. When the user changes the value and clicks away, the TextBox disappears and the TextBox's contents appear inline.

InlineEditBox supports the textarea mode through the Textarea widget. By simply adding a Textarea inside the InlineEditBox HTML tag, you add inline-editing to the Textarea widget. Furthermore, by adding renderAsHtml=true, users can enter HTML into the Textarea and have it appear inline as rich text. :

I'm one big paragraph. Go ahead and <i>edit</i> me. <b>I dare you.</b> The quick brown fox jumped over the lazy dog. Blah blah blah blah blah blah blah ...

The outermost span in this code is the InlineEditBox. The inner textarea tag is the Textarea widget. When a user loads the page, they see the paragraph of rich text. If the user clicks the text, a Textarea widget containing the paragraph in plain text form appears. When the user changes the value and clicks away, the Textarea disappears and the Textarea's contents appear inline.

InlineEditBox can make any arbitrary widget that has a text value, or has the methods get/setDisplayedValue, inline. DateTextBox is an example of such a widget. This code shows a DateTextBox made inline in HTML:

The InlineEditBox can wrap around any widget that implements the following interface:

The contained widget's setTextValue() method is called with the previously displayed text. When the Save button is pressed, the editing widget's getTextValue() method is called to retrieve the new text. After which, the editing widget is hidden, and the returned text is displayed. The focus method allows the editing widget to intelligently set focus to an appropriate node.

Accessibility

General Behavior

Note that since InlineEditBoxes may be used on the page without a traditional label element, the developer should add a title attribute in order to provide a description that is available to screen reader users. The title will also be displayed by the browser when the user places the mouse over the element.

Keyboard

If the widget is closed.

TextBox with autoSave specified and the TextBox is open:

Textarea with autoSave specified and the Textarea is open:

TextBox without autoSave specified, the TextBox is open, keyboard focus is in the edit field:

Textarea without autoSave specified, the Textarea is open, keyboard focus is in the edit field:

Known Issues

• See the Comment for the Enter key in the information for autoSaving Text Areas above.
• Ticket 3910: When Inline Text Boxes are opened, all the text should be selected.
• On Firefox 2, the user must press the Tab key twice with focus in an textarea before keyboard focus moves to the next widget. This is a permanent restriction on Firefox 2. This is because the Dojo text area is implemented using the Firefox editor component in an iframe. This editor component implements usage of the tab key within the editor to indent text and shift-tab to outdent text. There is no keyboard mechanism in Firefox to move focus out of the editor. So, the dijit editor traps the tab key in the editor and sets focus to the editor iframe. From there pressing tab again will move to the next focusable item after the editor.

Screen Reader Issues

The InlineEditBox is implemented as a button. Since these are intended to be used "in-line" within text there is often no label element associated with the underlying control. For this reason, developers are encouraged to add a title attribute to InlineEditBoxes. The Window-Eyes screen reader will speak the title as part of the button description. JAWS has an option to speak different attributes on an button. A JAWS user may need to use the insert-v command to modify the behavior to speak the button title when working with Dojo InlineEditBoxes.

NumberSpinner

The Number Spinner, a familiar widget in GUI interfaces, makes integer entry easier when small adjustments are required. The down and up arrow buttons "spin" the number up and down. Furthermore, when you hold down the buttons, the spinning accelerates to make coarser adjustments easier.

Example

Accessibility (added for 1.1 but true for 1.0 as well)

Keyboard

Slider

A slider is a scale with a handle you can drag up/down or left/right to select a value. Calling dojo.require("dijit.form.Slider") provides dijit.form.HorizontalSlider, dijit.form.VerticalSlider and all the rule and label classes.

Examples

One way you could show the user the value of your Slider is to create a textbox that the Slider fills when the user moves the Slider. The following code fills in a simple textbox called horizontalSliderValue.

You can point the handleSrc image to wherever you want. If you want to use the default handle image, just remove the handleSrc.

For a horizontal slider, you can use the HorizintalRule and HorizontalRuleLabels to create your ruler marks programmatically, reducing the amount of data being transferred over the wire:

1.  
2. 20%
3. 40%
4. 60%
5. 80%
6.  

1. 0%
2. 50%
3. 100%