This tutorial is for Dojo 1.6 and may be out of date.
Up to date tutorials are available.
Ajax with Dojo
Ajax has become a fundamental technique for creating dynamic, usable web applications. In this tutorial, you'll learn about the Dojo Toolkit's Ajax communication methods, including basic XHR concepts, how to customize your Ajax calls, handling multiple types of data, and strategies for cross-domain JSON gathering (JSONP).
Getting Started
Since Ajax is used throughout the numerous classes and widgets found in Dojo, Dijit, and DojoX, Ajax capabilities are baked right into the base dojo object via dojo.xhrGet
and dojo.xhrPost
methods. That means that there are no extra dojo.require
statements needed to use Ajax — simply including Dojo within the page enables quick Ajax coding! Here's a sample usage of dojo.xhrGet
:
// The "xhrGet" method executing an HTTP GET dojo.xhrGet({ // The URL to request url: "get-message.php", // The method that handles the request's successful result // Handle the response any way you'd like! load: function(result) { alert("The message is: " + result); } });
The code above executes an Ajax request to get-message.php, which returns a plain text message and alerts it to the user via the load function we specified. What if there's an error though? Or the response is XML or JSON? What if there's form data we want to send to the server? No problem — dojo.xhrGet
and dojo.xhrPost
allow for complete request customization.
Customizing an Ajax Request
Web developers need flexibility in Ajax requests to accomplish different tasks. Reasons for using Ajax calls include, but are not limited to:
- Loading static data from the server
- Accessing XML or JSON data from a web service
- Sending form data to the server
- Refreshing content on a page
Obviously, one type of request cannot accommodate all Ajax goals. Through customization of the request, dojo.xhrGet
and dojo.xhrPost
can handle each of the situations presented above. Customization of the request takes place in each method's single argument: an object containing request properties and desired values. Let's review the most-used request options available:
- url - The URL to make the request to.
- handleAs - A string representing the form of data we expect returned. Possible formats include: "text" (the default), "json", "javascript" (fragments to load and execute), and "xml".
- timeout - Time in milliseconds before considering the request a failure. The error handler is triggered.
- content - A key-value object containing data to provide to the server. Depending on use of
xhrGet
orxhrPost
, this data will either be translated to the query string or set as the post body. - form - A utility option which populates the content option from keys and values in a form. If you don't specify a URL, and are using this option, it will try to use the URL as specified in the form's "action" property. Also, if you specify any content, it will override anything in the form, so typically you'll use either content or form, but not both.
The options above manage how the request is sent, but what about the response? The answer to that lies in three handler functions, often referred to as callback functions or just callbacks, which are also provided to the request object:
- load(response, ioArgs) - The callback that fires when the request successfully completes. The first argument of load is the result of the request in the format designated by the handleAs option.
- error(errorMessage) - The callback that fires when the request fails. The first argument is the error message, if available.
- handle(response, ioArgs) - The callback that fires regardless of request success or failure.
Callbacks are important in handling data from the returned from the request and knowing their success or failure. The load or error method is called first, depending on result, and the handle callback fires next.
Examples: dojo.xhrGet and dojo.xhrPost
The following are some very common uses of dojo.xhrGet
and dojo.xhrPost
.
Refresh a Node's Content
// Using dojo.xhrGet, as very little information is being sent dojo.xhrGet({ // The URL of the request url: "get-content.php", // The success callback with result from server load: function(newContent) { dojo.byId("contentNode").innerHTML = newContent; }, // The error handler error: function() { // Do nothing -- keep old content there } });View Demo
Check a Username's Availability
// Local var representing the node to be updated var availabilityNode = dojo.byId("availabilityNode"); // Using dojo.xhrGet, as very little information is being sent dojo.xhrGet({ // The URL of the request url: "check-username.php", // Allow only 2 seconds for username check timeout: 2000, // Send the username to check base on an INPUT node's value content: { username: dojo.byId("usernameInput").value.toLowerCase() }, // The success callback with result from server load: function(result) { if(result == "available") { availabilityNode.innerHTML = "Username available!"; } else { availabilityNode.innerHTML = "Username taken! Please try another."; } } });View Demo
Send a Contact Form Submission
// Local var representing if the form has been sent at all var hasBeenSent = false; // Local var representing node to be updated var messageNode = dojo.byId("messageNode"); // Using dojo.xhrPost, as the amount of data sent could be large dojo.xhrPost({ // The URL of the request url: "submission.php", // No content property -- just send the entire form form: dojo.byId("contactForm"), // The success handler load: function(response) { messageNode.innerHTML = "Thank you for contacting us!"; }, // The error handler error: function() { messageNode.innerHTML = "Your message could not be sent, please try again." }, // The complete handler handle: function() { hasBeenSent = true; } });View Demo
What is JSON?
JSON (JavaScript Object Notation) is an outstanding data format to use with Ajax requests, because it allows for complex data structures to be passed from server to client. This includes basic stringsnumbers, and booleans, as well as arrays and objects. Better yet, Dojo's xhr methods parse the JSON-formatted response from the server and provide you with a JavaScript object, allowing you to access the object's properties directly with no effort. Here's a sample dojo.xhrGet
call to retrieve and use JSON from the server:
// Using dojo.xhrGet, as we simply want to retrieve information dojo.xhrGet({ // The URL of the request url: "get-news.php", // Handle the result as JSON data handleAs: "json", // The success handler load: function(jsonData) { // Create a local var to append content to var content = ""; // For every news item we received... dojo.forEach(jsonData.newsItems,function(newsItem) { // Build data from the JSON content += "<h2>" + newsItem.title + "</h2>"; content += "<p>" + newsItem.summary + "</p>"; }); // Set the content of the news node dojo.byId("newsContainerNode").innerHTML = content; }, // The error handler error: function() { dojo.byId("newsContainerNode").innerHTML = "News is not available at this time." } });View Demo
The JSON standard has been in use for several years and is used by many API creators. Most server-side languages provide methods for JSON encoding and decoding so that server-side objects can be easily converted to objects usable by JavaScript within your page. For example, PHP uses functions called json_encode
and json_decode
to handle JSON data.
JSONP and dojo.io.script
One fundamental limitation of Ajax technology is that requests are restricted to the current domain. You cannot, for example, request content from dojotoolkit.org from your own website using dojo.xhrGet
. There is a reliable method of retrieving JSON from another domain called JSONP. JSONP's workflow is as follows:
- A
script
node is created. - The
script
node's "src" attribute value is set to a URL we provide, with the content/paramaters that we establish in our call, including the name of a callback function to execute upon return. - The
script
node is appended into the DOM, causing the browser to make a request for the URL built up in the prior step. - The server outputs JSON based on our request, wrapped with the callback function we specified.
- The browser then executes the code sent back, handing over the server's response to our callback function.
Dojo's approach to making a JSONP request lives within the dojo.io.script
module. The get
method of dojo.io.script
accepts the same options as dojo.xhrGet
, along with an additional callbackParamName
option, which represents the callback function to be fired when the server sends back the JSON data. The callbackParamName
is not something that you make up, but that the service offering you JSON provides to you, so check with the documentation of the service you're accessing to get this value.
The following snippet uses dojo.io.script
to retrieve JSON directly from Twitter:
// dojo.io.script is an external dependency, so it must be required dojo.require("dojo.io.script"); // When the resource is ready dojo.ready(function() { // Use the get method dojo.io.script.get({ // The URL to get JSON from Twitter url: "http://search.twitter.com/search.json", // The callback paramater callbackParamName: "callback", // Twitter requires "callback" // The content to send content: { q: "dojo" // Searching for tweets about Dojo }, // The success callback load: function(tweetsJson) { // Twitter sent us information! // Log the result to console for inspection console.info("Twitter returned: ",tweetsJson); // Output the tweets to a DOM element // Or output a "no tweets" message var message = ""; // If there were tweets returned... if(tweetsJson.results && tweetsJson.results.length) { // Start the list message += "<ul>"; // For every tweet returned dojo.forEach(tweetsJson.results,function(tweet) { message += "<li>" + tweet.from_user + " said: " + tweet.text + "</li>"; }); //End the list message += "</ul>"; } else { // Output "no tweets" message message = "No tweets about Dojo were available."; } // Output message to DOM dojo.byId("tweetsHolder").innerHTML = message; } }); });View Demo
Notice that we don't have to manually build up any URLs or set up this callback function or anything. The dojo.io.script
module makes it easy for us to use the approaches we already know for Ajax, while working in a cross-domain fashion!
Keep in mind, the provider we're working with must provide a JSONP API — we can't use dojo.io.script
to just pull arbitrary information from any server we want.
Best Practices for Ajax and dojo.xhr*
Like any type of technology, it's important to keep best practices in mind when creating your Ajax requests:
- GET requests should be used for simply retrieving data from the server. POST requests are optimal when sending form data, or large sets of data, to the server.
- It's advised to always provide an error callback function. Don't assume that your request will be successful.
- Use console statements during debugging to ensure the options you're sending are correct, and that the response you receive in your callback is the correct format.
- From a user experience perspective, it's helpful to provide some type of indicator during Ajax requests so that the user knows something is happening.
Conclusion
The Dojo Toolkit alleviates the cross-browser complexity of Ajax and delivers an easy to use API with dojo.xhrGet
and dojo.xhrPost
. Dojo also provides dojo.script.io
to allow cross-domain JSONP calls. dojo.xhrGet
and dojo.xhrPost
return a dojo.Deferred
object which make handling Ajax requests even more powerful! This new concept about Ajax request handling can be found here.
dojo.xhr* Resources
Looking for more detail about Dojo's Ajax methods? Check out these great resources:
- dojo.xhrGet and dojo.xhrPost API Documentation
- dojo.io.script API Documentation
- dojo.xhrGet and dojo.xhrPost Reference Guides