Ajax is an acronym for “Asynchronous JavaScript and XML”, a technology employed to send and receive data on the fly. It can be used to update sections of a website from any number of remote sources, send data to the server and pass responses back and forth, all without ever refreshing the web page.

Having been versed on some essential Dojo methods, we’ll move on the the bread and butter of Ajax: XMLHttpRequest (or XHR for short). Dojo has several XHR methods available using common HTTP verbs: POST, GET, PUT, and DELETE.

To prepare, we need to create a file with some text to load in. Create a file named sample.txt in your js/ folder with sample text:

And modify the skeleton.html to have some basic markup and style:

Getting data

The first stepping stone is dojo.xhrGet, which will return the contents of a GET call on a URL. The XHR methods share a lot of common parameters. Most important are the url: (our destination) and handleAs: (how we handle what is coming back). When the data arrives, it will be passed the the load: function we define:

You will notice we’ve combined techniques above. The content will fade out, be replaced by the received data, and fade back in using methods we’ve learned to this point. It was almost too easy.

A single handle argument can be used instead of load and error, handling both success and failure cases in a common function:

XHR has limitations. The big one being that url is not cross-domain. You can’t submit the request outside of the current host (e.g. to url:”http://google.com”). It is a known limitation and a common mistake when getting excited about Ajax. Dojo provides alternatives like dojo.io.iframe and dojo.io.script for more advanced usage.

A full list of XHR parameters is available at the Dojo XHR API page. We are only going to skim the surface here.

Sending Data

All Dojo XHR methods are bi-directional. The only difference is the method. Using dojo.xhrPost, we use the POST method, embedding the data in the request (as opposed to the query string as with dojo.xhrGet). The data can be set directly as an object passed to the content parameter:

Or more commonly, conveniently converted from a form parameter. First, make a simple unobtrusive form in the skeleton.html:

Then, add in some JavaScript to submit the form by using dojo.connect to listen to the onSubmit event, and post the contents of the form to an alternate URL:

An example alternate-submit.php would look like:

Object Data

Getting text back from the server is nice, but the really great stuff comes when you start passing JavaScript objects around. Using a different handleAs: attribute, we can alter how Dojo handles the response data. Make a new file named simple-object.json to load:

We’ll target our xhrPost url: to the new file, and supply a handleAs: "json" parameter to convert the response data to an actual object we can use:

This allows us to send literally any kind of data back and forth across the wire, without ever interrupting the user experience.

Dojo’s widget system is called Dijit. Dijits are the official, accessible, themed components shipped with the Dojo Toolkit. It has its own namespace, and likewise its own collection of utility functions:

Using Dijits

There are two ways to make Dijits: via markup, or programatically. The markup route breaks W3C validation because Dojo conveniently uses customized attributes in the markup to configure the widget. If this concerns you, it can all be done with script. We’ll do both. (Note: Dojo 1.6 adds support for HTML5 data attributes making the validation point moot).

Start by making a new skeleton file, including a couple changes for Dijit styling: the default theme claro’s CSS, and setting to enable it:

Dijit uses Dojo’s package system to track dependencies via dojo.require. Simply call in the modules you need in a script tag. For instance, to use a dijit.Dialog and dijit.form.Button, you need the following calls:

From markup

You can specify all the attributes needed to setup your widget directly in markup, the most important being the dojoType. The Dojo parser finds the dojoType attribute, and turns the node into a Dijit with the matching classname. title is a common attribute used by many widgets with headings:

If parseOnLoad is true, the widgets will be created, then dojo.ready code will be executed. If you want to execute code before widgets are parsed, set parseOnLoad:false, and put your code inside a dojo.ready function as before. Issuing the command dojo.parser.parse(); will create the widgets when you are ready.

From JavaScript

The same results can be achieved using valid HTML and JavaScript. Our markup is simple, valid HTML:

And our script is standard Dojo code. We pass all the attributes as an object into our constructor, and tell it to use the node “sampleNode” for its content. All Dijits (or declared classes) can be created using the JavaScript new function.

When the button is clicked, you should see the word “clicked” in your Firebug (or Firebug Lite) console.

Manipulating The Widget

With our dialog successfully loaded and parsed (no errors were thrown, and the content of the Dialog is hidden), we need to explore some of the ways to manipulate the widgets. The function dijit.byId gives us a reference to our widget. The dijit.Dialog has an id of sampleNode.

To make the button the button control the dialog, modify the button’s onClick attribute to do more than print text:

If using the programmatic method, modify the lines that create the button:

The dijit.Dialog inherits from a dijit.layout.ContentPane which provides a few content-handling methods, including setHref. Add a new button outside the dialog with a new onClick function:

Or programatically by adding another button to our HTML:

And an additional new call:

Adding an id attribute to the paragraph inside the Dialog is an easy way to demonstrate another useful Dijit tool, dijit.getEnclosingWidget, to find which widget contains a passed domNode: