Keeping track of progress

An XHR instance informs you of its progress through the ready state handler. This handler is established by assigning a reference to the function to serve as the ready handler to the onreadystatechange property of the XHR instance.

Once the request is initiated via the send() method, this callback will be invoked numerous times as the request makes transitions through its various states. The current state of the request is available as a numeric code in the readyState property (see the description of this property in table 10.1). That’s nice, but more often than not, you’re only interested in when the request completes and whether it was successful or not. Frequently you’ll see ready handlers implemented using the idiom shown in the next listing.

Listing 10.2. Ready state handlers written to ignore all but the DONE state

This code ignores all but the DONE state (state with value of 4), and once that has been detected, it examines the value of the status property to determine whether the request succeeded or not. The HTTP specification defines all status codes in the 200 to 299 range as success and those with values of 300 or above as various types of failure or redirection.

Now let’s explore dealing with the response from a completed request.

Getting the response

Once the ready handler has determined that the readyState is complete and that the request completed successfully, you can retrieve the body of the response from the XHR instance.

Despite the moniker Ajax (where the X stands for XML), the format of the response body can be any text format; it’s not limited to XML. The response to Ajax requests could be plain text, an HTML fragment, or any data represented using the JavaScript Object Notation (JSON) format.

Regardless of its format, the body of the response is available via the responseText property of the XHR instance (assuming that the request completes successfully). If the response indicates that the format of its body is XML by including a content type header specifying a MIME type of text/xml or application/xml or a MIME type that ends with +xml, the response body will be parsed as XML. The resulting DOM will be available in the responseXML property. JavaScript (and jQuery itself, using its selector API) can then be used to process the XML DOM.

At this point, you might want to review the diagram of the whole process shown in figure 10.1. In this short overview of Ajax, we’ve identified the following pain points that page authors using Ajax need to deal with:

• Instantiating an XHR object requires browser-specific code.
• Ready handlers need to sift through a lot of uninteresting state changes.
• The response body needs to be dealt with in numerous ways, depending on its format.

The remainder of this lesson will describe how jQuery’s Ajax methods and utility functions make Ajax a lot easier (and cleaner) to use on your pages. There are a lot of choices in the jQuery Ajax API, and we’ll start with some of the simplest and most-used tools.