Take Command with Ajax

Do you want to build more dynamic, responsive, desktop-like web applications like Gmail and Google Maps? Then this article is for you! It guides you through the Ajax basics and through the process of building a simple Ajax application.

That application is named WebConsole, a browser interface for executing system commands for which you’d usually need shell access. There are also short examples of using the Ajax functionality of two popular JavaScript libraries—jQuery and YUI.

In this article, first published in 2005 and recently updated, I’ll explain the creation of one simple, reusable JavaScript function for making HTTP requests. Then, I’ll apply that function in the creation of a simple application.

Although there are some YUI and jQuery examples, the article is not a tutorial on a specific Ajax library. Instead, it aims to give you more hands-on information about making HTTP requests, so that you’re in a better position when evaluating such libraries or deciding to go on your own.

A Simple HTTP Request Example

Let’s first revise the flow of making an HTTP request in JavaScript, and handling the response. This is just a quick example to refresh your memory. For all the spicy details, see SitePoint’s introductory article, “Ajax: Usable Interactivity with Remote Scripting.”

There are three basic steps:

1. Create an XMLHttpRequest object.


2. Assign a callback function to handle the HTTP response.


3. Make (send) the request.

Let’s see an example where we’ll request a simple HTML document, test.html, which only contains the text “I’m a test.” We’ll then alert() the contents of the test.html file:

<button id="mybutton">Make a request</button>

<script type="text/javascript">

var http_request = false;

function makeRequest(url) {

  if (window.XMLHttpRequest) { // Mozilla, Safari, IE7...
      http_request = new XMLHttpRequest();
  } else if (window.ActiveXObject) { // IE6 and older
      http_request = new ActiveXObject("Microsoft.XMLHTTP");
  }
  http_request.onreadystatechange = alertContents;
  http_request.open(‘GET’, url, true);
  http_request.send(null);

}

function alertContents() {
  if (http_request.readyState == 4) {
      if (http_request.status == 200) {
          alert(http_request.responseText);
      } else {
          alert(‘There was a problem with the request.’);
      }
  }
}

document.getElementById(‘mybutton’).onclick = function() {
  makeRequest(‘test.html’);
}

</script>

Here’s how this example works:

1. The user clicks the “Make a request” button.


2. This calls the makeRequest() function with a parameter: the name of an HTML file in the same directory. In this case, it’s test.html.


3. The request is sent.


4. The onreadystatechange event fires and the execution is passed to alertContents().


5. alertContents() checks if the response was received and, if it’s okay, then alert()s the contents of the test.html file.

Test the example for yourself, and view the test file.

The Problem

The above example worked just fine, but there’s one thing we need to improve before we’re ready for prime time. The improvement is to code a reusable request function that handles all the boring and repetitive object creation and request/response stuff, while leaving the presentational part to other functions, which are request-agnostic and deal with the result only, regardless of its source.

In the example above, we needed a global variable, http_request, that was accessible by both the makeRequest() and alertContents() functions, which is not good in terms of reusability and also risks naming collisions. Ideally, makeRequest() should perform the request and alertContents() should just present the result; neither function needs know about or require the other.

Here’s the code for our reusable request function:

function makeHttpRequest(url, callback_function, return_xml)
{
 var http_request, response, i;

 var activex_ids = [
   ‘MSXML2.XMLHTTP.3.0’,
   ‘MSXML2.XMLHTTP’,
   ‘Microsoft.XMLHTTP’
 ];

 if (window.XMLHttpRequest) { // Mozilla, Safari, IE7+...
   http_request = new XMLHttpRequest();
   if (http_request.overrideMimeType) {
     http_request.overrideMimeType(‘text/xml’);
   }
 } else if (window.ActiveXObject) { // IE6 and older
   for (i = 0; i < activex_ids.length; i++) {
     try {
       http_request = new ActiveXObject(activex_ids[i]);
     } catch (e) {}
   }
 }

 if (!http_request) {
   alert(‘Unfortunately your browser doesn’t support this feature.’);
   return false;
 }

 http_request.onreadystatechange = function() {
   if (http_request.readyState !== 4) {
       // not ready yet
       return;
   }
   if (http_request.status !== 200) {
     // ready, but not OK
     alert(‘There was a problem with the request.(Code: ‘ + http_request.status + ‘)’);
     return;
   }
   if (return_xml) {
     response = http_request.responseXML;
   } else {
     response = http_request.responseText;
   }
   // invoke the callback
   callback_function(response);
 };

 http_request.open(‘GET’, url, true);
 http_request.send(null);
}

This function receives three parameters:

• the URL to get
• the function to call when the response is received
• a flag if the callback function expects an XML document (true) or plain text (false, default)

This function relies on two JavaScript capabilities in order to wrap and isolate the request object nicely. The first is the ability to define new functions (called anonymous functions) on the fly, like this:

http_request.onreadystatechange = function() {...}

The other trick is the ability to invoke callback functions without knowing their names in advance; for example:

var callmeback = alert;
callmeback(‘test’); // alerts ‘test’

Note how the name of the callback function is passed without any quotes.

You can easily make the function even more reusable by allowing the HTTP request method as well as any query string to be passed as parameters to the function and then used in calls to open() and send() methods. This will also allow you to make POST requests in addition to the GETs it was originally intended to perform.

Another capability of the function is the handling of response codes other than 200, which could be handy if you want to be more specific and take appropriate actions depending on the type of the success/error code returned.

The Simple Example Revisited

Now let’s redo the previous example in which the contents of a test.html file were alert()ed. This time, by employing our shiny new reusable request function, the revised versions of the two functions used will be much simpler:

function alertContents(text) {  
  alert(text);  
}  

function makeRequest(url) {  
  makeHttpRequest(url, alertContents);  
}

As you can see, alertContents() is simply presentational: there are no states, readyStates, or HTTP requests flying around whatsoever.

Since these functions are now just one-liners, we can in fact get rid of them entirely, and change the function call instead. So the whole example will become:

<button id="mybutton">Make a request</button>
<script type="text/javascript">
 document.getElementById(‘mybutton’).onclick = function() {
   makeHttpRequest(‘test.html’, alert);
 }
</script>

Yes, it’s that easy! View the example and full source code (available through our old friend View Source).