This week’s installment of Dojo Goodness demonstrates dojo.xhrGet, an easy way to sprinkle some AJAX into your application and one of the biggest staples in Dojo. (In case the “xhr” part of that API call is a curve ball, it simply refers to the XMLHttpRequest object.) The xhrGet function streamlines the work entailed in issuing a GET request to the server, is included in Base, and is intuitive to use in that you pass it some descriptive keyword arguments; the default behavior is to issue an asynchronous request.

Here’s the basic boilerplate:


dojo.xhrGet({
    url : "localresource.json",
    handleAs : "json",
    load : function(response, ioArgs) {
        /* Handle a successful callback here */
        return response;
    },
    error : function(response, ioArgs) {
        /* Handle any errors that occur here */
        return response;
    }
});

Assuming you have a resource on your server called localresource.json that returns back some JSON, you can access it via the load function’s response parameter just like any other JavaScript object since handleAs was configured accordingly. If an error were to occur either in the call to the server or in the load function itself, the error handler kicks in to give you a place to take care of the mess. The ioArgs parameter can be used to inspect info such as the original request that was sent to the server.

Let’s go ahead and kick the tires a bit. First, store the following file somewhere locally:


<html>
    <head>
        <title>Easy AJAX!</title>
        <script
            type="text/javascript"
            src="http://o.aolcdn.com/dojo/1.0/dojo/dojo.xd.js"
            djConfig="isDebug:true"
        ></script>

        <script type="text/javascript">
            dojo.addOnLoad(function() {

               dojo.xhrGet({
                    url : "localresource.json",
                    handleAs : "json",
                    load : function(response, ioArgs) {
                        // inspect the response and ioArgs...
                        console.log(response, ioArgs);

                        //do some stuff with the response...
                        console.log(response.foo);
                        console.log(response.bar);
                        console.log(response.baz);

                        //uncomment to cause an error and see the error handler kick in.
                        //console.log(response.foo.bar.baz);
                    },
                    error : function(response, ioArgs) {
                        console.log("An error occurrerd.", response, ioArgs);
                    }
                });

            });
        </script>
    </head>
    <body>
        Nothing to see here. Check the console...
    </body>
</html>

Next, store the following simple structure in a file called localresource.json, and place it alongside the HTML file:


{
    'foo' : 1,
    'bar' : 2,
    'baz' : 3
}

When you load up the HTML file, you should see some activity in Firebug related to the GET request and the console.log functions where we treat the response parameter as an ordinary JavaScript object.

All in all, that’s the basic story for injecting some AJAX into an existing app. Hopefully, you agree that it should have been that easy.

Of course, GET requests aren’t all you can do. Referencing Dojo’s official API, there’s also a variety of other XHR functions including xhrPut, xhrPost, rawXhrPut, rawXhrPost, and as of version 1.1, a general-purpose xhr function that allows you to pass in the request type, which might be useful for HEAD requests among other things.

For complete coverage of the entire I/O subsystem in Dojo, be sure to check out my upcoming book. There’s an entire chapter devoted to virtually every topic related to server side communication, which includes IFRAME transports, JSONP, JSON-RPC, and more.

As always, leave feedback below if there is a topic that you’d like to see in an upcoming column. It can be something as simple as what we talked about today or something as complex as using an ill-documented DojoX subproject. (In other words, you might just be able to get some free consulting out of this column if you are sneaky enough…)