Internet Explorer 5 and 6 were the first browsers to implement XMLHttpRequest, and they did so using an ActiveX object:^[29]

var requester = new ActiveXObject("Microsoft.XMLHTTP");

Every other browser that supports XMLHttpRequest (including Internet Explorer 7) does so without using ActiveX. A request object for these browsers looks like this:

var requester = new XMLHttpRequest();

We can easily reconcile the differences between the two methods of object creation using a try-catch statement, which will automatically detect the correct way to create an XMLHttpRequest object:

try
{
  var requester = new XMLHttpRequest();(1)
}
catch (error)(2)
{
  try
  {
    var requester = new ActiveXObject("Microsoft.XMLHTTP");(3)
  }
  catch (error)
  {
    var requester = null;
  }
}

A try statement allows you to try out a block of code, but if anything inside that block causes an error, the program won’t stop execution entirely; instead, it moves onto the catch statement and runs the code inside that. As you can see in Figure 8.2, the whole structure is like an if-else statement, except the branch taken is conditional on any errors occurring.

Figure 8.2. The logical structure or a try-catch statement

We need to use a try-catch statement to create ActiveX objects because an object detection test will indicate that ActiveX controls are still available even if a user has disabled them (though your script will throw an error when you actually try to create an ActiveX object).

Here’s what happens in the code above:

if (requester == null)
{
  code for non-Ajax clients
}
else
{
  code for Ajax-enabled clients
}

Thankfully, the significant differences between browser implementations of XMLHttpRequest end with its creation. All of the basic data communication methods can be called using the same syntax, irrespective of the browser in which they’re running.

Once we’ve created an XMLHttpRequest object, we must call two separate methods—open and send—in order to get it to retrieve data from a server.

open initializes the connection and takes two required arguments, with several optionals. The first argument is the type of HTTP request you want to send (GET, POST, DELETE, etc.); the second is the location from which you want to request data. For instance, if we wanted to use a GET request to access feed.xml in the root directory of a web site, we’d initialize the XMLHttpRequest object like this:

requester.open("GET", "/feed.xml", true);

The URL can be either relative or absolute, but due to cross-domain security concerns the target must reside on the same domain as the page that’s requesting it.

The third argument of open is a Boolean that specifies whether the request is made asynchronously (true) or synchronously (false). A synchronous request will freeze the browser until the request has completed, disallowing user interaction in the interim. An asynchronous request occurs in the application’s background, allowing other scripts to run and the user to access the browser at the same time. I recommend you use asynchronous requests; otherwise, you run the risk of users’ browsers locking up while they wait for a request that has gone awry. open also has optional fourth and fifth arguments that specify the user’s name and password for authentication purposes when a password-protected URL is requested.

Once open has been used to initialize a connection, the send method activates that connection and makes the request. send takes one argument that allows you to send encoded data along with a POST request, in the same format as a form submission:

requester.open("POST", "/query.php", true);
requester.setRequestHeader("Content-Type",
    "application/x-www-form-urlencoded");
requester.send("name=Clark&[email protected]");

To simulate a form submission using a GET request, you need to hard-code the names and values into the open URL, then execute send with a null value:

requester.open("GET",
    "query.php?name=Clark&[email protected]", true);
requester.send(null);

Internet Explorer doesn’t require you to pass any value to send, but Mozilla browsers will return an error if no value is passed; that’s why null is included in the above code.

Once you’ve called send, XMLHttpRequest will contact the server and retrieve the data that you requested. In the case of an asynchronous request, the function that created the connection will likely finish executing while the retrieval takes place. In terms of program flow, making an XMLHttpRequest call is a lot like setTimeout, which you’ll remember from Chapter 5.

We use an event handler to notify us that the server has returned a response. In this particular case, we’ll need to handle changes in the value of the XMLHttpRequest object’s readyState property, which specifies the status of the object’s connection, and can take any of these values:

We can monitor changes in the readyState property by handling readystatechange events, which are triggered each time the property’s value changes:

requester.onreadystatechange = readystatechangeHandler;

function readystatechangeHandler()
{
  code to handle changes in XMLHttpRequest readystate
}

readyState increments from 0 to 4, and the readystatechange event is triggered for each increment. However, we only really want to know when the connection has completed (that is, readyState equals 4), so our handling function needs to check for this value.

Upon the connection’s completion, we also have to check whether the XMLHttpRequest object successfully retrieved the data, or was given an HTTP error code such as 404 (page not found). You can determine this from the request object’s status property, which contains an integer value. A value of 200 is a fulfilled request; you should check for it—along with 304 (not modified)—as these values indicate successfully retrieved data. However, status can take as a value any of the HTTP codes that servers are able to return, so you may want to write some conditions that will handle some other codes. In general, however, you’ll need to specify a course of action for your program to take if the request is not successful:

requester.onreadystatechange = readystatechangeHandler;

function readystatechangeHandler()
{
  if (requester.readyState == 4)
  {
    if (requester.status == 200 || requester.status == 304)
    {
      code to handle successful request
    }
    else
    {
      code to handle failed request
    }
  }
}

Instead of assigning a function that’s defined elsewhere as the readystatechange event handler, you can declare a new, anonymous (unnamed) function inline:

requester.onreadystatechange = function()
{
  if (requester.readyState == 4)
  {
    if (requester.status == 200 || requester.status == 304)
    {
      code to handle successful request
    }
    else
    {
      code to handle failed request
    }
  }
}

The advantage of specifying the readystatechange callback function inline like this is that the requester object will be available inside that function via a closure. If the readystatechange handler function is declared separately, you’ll need to jump through hoops to obtain a reference to the requester object inside the handling function.

If you’ve made a successful request, the next logical step is to read the server’s response. Two properties of the XMLHttpRequest object can be used for this purpose:

In simple cases, plain text works perfectly well as a means of transmitting and handling the response, so the XMLHttpRequest object doesn’t exactly live up to its name. When we’re dealing with more complex data structures, however, XML can provide a convenient way to express those structures:

<?xml version="1.0" ?>
<user>
  <name>Doctor Who</name>
  <email>[email protected]</email>
</user>
<user>
  <name>The Master</name>
  <email>[email protected]</email>
</user>

responseXML allows us to access different parts of the data using all the DOM features with which we’re familiar from our dealings with HTML documents. Remember that data contained between tags is considered to be a text node inside the element in question. With that in mind, extracting a single value from a responseXML structure is reasonably easy:

var nameNode =
    requester.responseXML.getElementsByTagName("name")[0];
var nameTextNode = nameNode.childNodes[0];
var name = nameTextNode.nodeValue;

The name variable will now take as its value the first user’s name: "Doctor Who".

We can use the data contained in the XML to modify or create new HTML content, updating the interface on the fly in the manner that has become synonymous with Ajax.

The main downside of using XML with JavaScript is that a fair amount of work can be involved in parsing XML structures and accessing the information we want. However, an alternative way to use the XMLHttpRequest object is to remove this data processing layer and allow the server to return HTML code, all ready to insert into your page. This approach is taken by libraries such as Prototype, in which HTML is delivered with a MIME type of text/html and the value of responseText is automatically inserted into the document using innerHTML, overwriting the contents of an existing element.

As with any use of innerHTML, this technique suffers from the disadvantages we discussed in Chapter 4, but it can certainly be a viable option if your circumstances require it.

Prototype’s approach to handling Ajax calls basically represents the archetype for other libraries. It gives you access to an Ajax object, which offers a couple of methods with which to make requests.

We start a basic Ajax request by calling new Ajax.Request and passing it a number of parameters in the form of an object literal. When you specify an onComplete function, it will automatically be called once the server call has successfully completed:

var requester = new Ajax.Request("library.php",
    {
      method: "get",
      parameters: "dewey=005",
      onComplete: writeUpdate
    });

function writeUpdate(requestObject)
{
  document.getElementById("container").childNodes[0].nodeValue =
      requestObject.reponseText;
}

That code can be further shortened by replacing Ajax.Request with Ajax.Updater. The second method assumes that you will place the contents of responseText directly inside an HTML element (the most common Ajax operation), and allows you to specify the ID of that element. Thus, it circumvents the need for you to create your own callback function:

var requester = new Ajax.Updater("container", "library.php",
    {
      method: "get",
      parameters: "dewey=005",
    });

That’s very succinct!

To use Dojo’s Ajax handler, we just call dojo.io.bind with an object literal that contains the appropriate parameters:

dojo.io.bind(
    {
      url: "library.php?dewey=005",
      load: writeUpdate,
      mimetype: "text/plain"
    });

function writeUpdate(type, data, event)
{
  document.getElementById("container").childNodes[0].nodeValue =
      data;
}

There are a couple of tricks with the Dojo Ajax implementation. Specifying mimetype inside the object literal determines what type of data Dojo will pass to your load function when the request is completed (text or XML). The load function receives three arguments:

As with everything in jQuery, Ajax functionality is available as part of the $ object. $.ajax lets you specify an all-too-familiar object literal with the particular configuration you require for the call:

$.ajax(
    {
      type: "GET",
      url: "library.php",
      data: "dewey=005",
      success: writeUpdate
    });

function writeUpdate(data)
{
  document.getElementById("container").childNodes[0].nodeValue =
      data;
}

Again, with jQuery, as with Dojo, either responseXML or responseText will be passed directly to the success function—the property that’s passed will depend upon the MIME type of the data returned from the server.

In true Yahoo! UI style, the name that Yahoo! has given to its Ajax object (which it calls a Connection Manager) is rather verbose, but in most other respects it’s similar to what we’ve seen so far:

var handlers = {
  success: writeUpdate
}

YAHOO.util.Connect.asyncRequest(
    "GET",
    "library.php",
    handlers,
    "dewey=005"
);

function writeUpdate(requestObject)
{
  document.getElementById("container").childNodes[0].nodeValue =
      requestObject.reponseText;
}

The handlers variable allows you to specify both the handler function for a successful Ajax request, and the function to be called when an error occurs. These functions are passed a full XMLHttpRequest object, rather than just the data.

MooTools based its Ajax handler on the one that comes with Prototype, so both handlers have similar syntax. MooTools’ handler even has the shortcut for placing the returned data directly into an element without specifying a callback function:

var requester = new Ajax("library.php?dewey=005",
    {
      method: "get",
      onComplete: writeUpdate;
    });

requester.request();

function writeUpdate(requestObject)
{
  document.getElementById("container").childNodes[0].nodeValue =
      requestObject.reponseText;
}

The one difference between these two libraries is that the MooTools object doesn’t automatically send the request once it has been initialized; you have to call request when you want to send it.

If you wish to use the element insertion shortcut, the code looks like this:

var requester = new Ajax("library.php?dewey=005",
    {
      method: "get",
      update: "container";
    });

requester.request();

The update property takes the ID of the element whose contents you wish to update.