By Dave Crane

The standard way to do Ajax is to use the XMLHttpRequest object, known as XHR by its friends. Use XHR directly, or via one of the helpful Ajax libraries such as Prototype or jQuery. How do we use XHR "by hand"? To start with, we need to get a reference to it:

if (window.XMLHttpRequest) {
    xhr = new XMLHttpRequest();
  } else if (window.ActiveXObject) {
    xhr = new ActiveXObject("Microsoft.XMLHTTP");
  }

We can then open a connection to a URL:

xhr.open(
    "GET",
    "my-dynamic-content.jsp?id="
    +encodeURI(myId),
    true
  );

Specify a callback function to receive the response:

xhr.onreadystatechange = function(){
    processReqChange(req);
  }

and then send the request:

xhr.send(null);

The server may be busy, or the network may be slow. We don't want to sit around doing nothing until the response arrives, and because we've assigned the callback function, we don't have to. That's the five-minute guide for the impatient. For those who like to know the details, we've listed the fuller details of the XHR object below.

To make use of the XHR to its fullest, we recommend you become familiar with the workings of the HTTP protocol. Using Ajax, you have much more control over HTTP than with classic web app development.

HTTP is a stateless request-response protocol.

• Both request and response contain headers and an optional body, which is free text.
• Only a POST request contains a body.
• A request defines a verb or method.
• The Mime type of request and response can be set by the header Content-type

Common HTTP Verbs

99% of the time, you'll only need GET and POST. Many other verbs are used by WebDAV, Subversion over HTTP, and other niche applications, but not all web servers will understand them.

If you're using the increasingly popular REST approach to web services, the HTTP verb is used to indicate the type of operation being performed. The most commonly used HTTP verbs in REST map onto the CRUD (create, read, update, delete) approach:

Common Mime Types

Setting the right mime type for your request and response is good manners it's also vital to get the app to behave correctly!

• Always set async to true when calling open(). Synchronous Ajax requests block the browser UI, giving the stop-start behaviour we were trying to get away from in the first place!
• XHR can be fussy about order of setting-up. Always set the callback handler before calling send()
• To send HTML-form like data
  • Use encodeURI() to encode all data values
  • Set the mime-type of the request to application/x-www- form-urlencoded
• Set the response mime type to application/xml or text/xml if you want to use the responseXML property

Handling the Response

We've assigned a callback handler function to our XHR object. This function will get called several times as the response comes in. Typically, we only want to parse the response once it has fully arrived, i.e. the readyState is complete.

xhr.onreadystatechange=function(){
    if (xhr.readyState==4){
      if (xhr.status==200){
        parseResponse(xhr);
      }else{
        //handle the HTTP error...
      }
    };
  };

XHR ReadyState Values

So, what might the parseResponse() method look like? We have a lot of freedom in the types of response we send. Let's look at some of the common ones.

Handling a HTML Response

The server can send pre-assembled HTML content, which we just stitch into the web page.

<table class='item selected'>
<tr>
<td rowspan='3' valign='top'><div class='itemIcon'><img
src='../images/kmoon.png'></div></td>
<td class='itemTitle'>The Moon on a
Stick</td>
</tr>
<tr>
<td valign='top'>What every project
manager wants - and they want it yesterday!
<br/><br/><i>NB: Stick not included.</i></td>
</tr>
<tr>
<td><div class='price'>$365.00</div></td>
</tr>
</tr>
</table>

function parseResponse(xhr){
  var div=document
    .getElementById("myDiv");
  div.innerHTML=xhr.responseText;
}

Handling a JSON Response

JSON is a simple text-markup that's extremely easy for JavaScript to digest! It doesn't come so naturally to server-side languages, but there are JSON libraries for most servers these days'see http://www.json.org. Most Ajax libraries now provide support for JSON.

{
  imgSrc: "kmoon.png",
  title: "The Moon on a Stick",
  description: "What every project manager wants 
        - and they want it yesterday!<br/><br/><i>
        NB:     Stick not included.</i>",
  price: "365.00"
}

function parseResponse(xhr){
  var jsonObj=eval(
   "("
   +xhr.responseText
   +")"
  );
  setImgSrc(jsonObj.imgSrc);
  setTitle(jsonObj.title);
}

Handling an XML Response

XML is a more natural fit for most server technologies. XHR supports XML by giving us the responseXML property, but parsing this using the DOM is hard work.

<item imgSrc="kmoon.png" price="365.00">
  <title>The Moon on a Stick</title>
  <description><![CDATA[What every project manager wants
         - and they want it yesterday!<br/><br/><i>NB: 
         Stick not included.</i>]]></description>
</item>

function parseResponse(xhr){
  var xmlDoc=xhr.responseXML;
  var item=xmlDoc.getElementsByTagName('item')[0];
  var imgSrc=item.getAttribute('imgSrc');
  var title=item.getElementsByTagName('title')[0]
    .firstChild.data;
  setImgSrc(imgSrc);
  setTitle(title);
}

Some browsers also support XPath as a more pleasant way to parse XML. Sarissa and mozXPath.js both provide cross-browser XPath support.

<item imgSrc="kmoon.png" price="365.00">
  <title>The Moon on a Stick</title>
  <description><![CDATA[What every project manager wants 
        - and they want it yesterday!<br/><br/><i>NB: 
        Stick not included.</i>]]></description>
</item>

function parseResponse(xhr){
  var xmlDoc=xhr.responseXML;
  var imgSrc=xmlDoc.selectSingleNode('/item/@imgSrc').value;
  var title=xmlDoc.selectSingleNode
          ('/item/title/text()').value;
  setImgSrc(imgSrc);
  setTitle(title);
}

Handling a JavaScript Response

Another approach to Ajax is to generate scripts on the server, and send them to the client to be evaluated. Care should be taken here to define a suitably high-level API on the client against which the generated script is to run, otherwise tight coupling between server and client code can result.

setImgSrc("kmoon.png");
setTitle("The Moon on a Stick");

function parseResponse(xhr){
  eval(xhr.responseText);
}

Handling Mixed Responses

Some Javascript libraries allow mixing of these dialects of Ajax within a single response. The Prototype Ajax.Updater, for example, can accept a response as HTML, into which <script> tags are embedded. The script will be extracted and evaluated, while the rest of the content is embedded into a target DOM element.

Does Ajax only affect the client-side? Certainly not! Particularly if your server is responding with data rather than HTML fragments, you'll want to refactor to some extent.

Dumb client and thick client above are extremes. In between, there is a thinner (but still intelligent) client, that will suffice in many cases. No single model is right for all cases. Try out these rules of thumb:

• To add small Ajax features to an existing app, stick with the thin client approach. Thick client is for complex, line-of-business app replacements.
• Your client-side code is visible, and runs on somebody else's machine. Don't expose details of your business tier. Keep it coarse-grained.
• Some functionality MUST be kept on the server, such as data validation. Simple, fast validation on the client is an addition, not a replacement!
• Treat your client-side code well. Use the patterns and practises that you would use on the server to keep your code clean and maintainable.
• Most projects have a legacy system behind them. How can you introduce Ajax with minimal disruption? Does it speak XML, or generate HTML from components? Can you re-use that?

Toolkits and frameworks will make your life easier in several ways:

• Providing tried-and-tested solutions to common problems
• Abstracting away cross-browser incompatibilities and annoyances
• Providing higher level abstractions such as ready-made UI widgets and networking stacks

However, it's a jungle out there, with many different types of toolkits on the market. Let's divide them into broad families.

Client-side vs. Server-side

Some toolkits are JavaScript-only, others include a back-end system too. Client-side toolkits will give more flexibility, but may require more work on the server-side too.

High-level vs. Low-level

JavaScript is a flexible language, and some toolkits are geared towards enhancing the language itself in a variety of ways. Others are more concerned with higher-level issues such as simplifying XHR, or providing drop-in widgets such as trees, tables and drag-and-drop.

Some Popular Ajax Toolkits

We haven't time to show you how to make Ajax calls with all of these toolkits, but let's pick two of the most popular: Prototype and jQuery.

The Basics: Making an Ajax Request

new Ajax.Request(
  "my-dynamic-content.jsp",
  { method: "post",
    params: { id: myId },
    onComplete: function(response){
      parseResponse(response);
    }
  }
);

$.post(
  "my-dynamic-content.jsp",
  { id: myId },
  function(xhr){
    parseResponse(xhr);
  }
);

• No need to create your own XHR object
• Use high-level, meaningful callbacks rather than onreadystatechange
• Sensible defaults provided for all the options you don't want to specify yourself

Loading HTML Content Into a DOM Node

new Ajax.Updater(
  $("myDomNode"),
  "my-dynamic-content.jsp",
  { method: "post",
    params: { id: myId }
  }
);

$("#myDomNode").load(
  "my-dynamic-content.jsp",
  { id: myId }
);

• No need to provide a callback function at all

Working With JSON Responses

new Ajax.Request(
  "my-dynamic-content.jsp",
  { method: "post",
    params: { id: myId },
    onComplete: function(response,json){
      alert(json.someProperty);
    }
  }
);

$("#myDomNode").load(
  "my-dynamic-content.jsp",
  { id: myId }
);

• JSON response returned to our callback already parsed

JavaScript is a loosely-typed scripting language with support for object-oriented and functional programming styles. Although it looks like Java and C-family languages, it's quite different under the hood. Here are a few survival tips to get you through your first serious encounter with this language:

• Objects can be extended at runtime with new properties. Think of Javascript objects as associative arrays.
• Functions are first-class objects, and can be passed as arguments into other functions (see the numerous callback functions earlier).
• JavaScript functions support closures. That is, variables that are in scope when a function is defined can still be referenced inside the function, even if it is invoked later.

Ajax User Interfaces

Before Ajax, the UI was nearly always delivered as declarative HTML, and the Document Object Model, or DOM, was only used in moderation. With Ajax'especially single-page applications' the DOM can play a much bigger role.

Working with the DOM is a two-stage process:

• Finding the elements we want to work with
• Modifying their contents or reorganizing them

Finding DOM Elements

The DOM standard itself gives us a few basic tools to work with. Enterprising JavaScript library developers have built on top of these to provide a much richer set of functionality.

The id attribute is often too specific'adding one to each element we may need to locate becomes tedious, and clutters the markup. Tag names, on the other hand, are not specific enough to be useful in many cases. The most common solution is to use CSS classes to locate elements. We can make these as specific or general as we need.

Finding DOM Elements Using Prototype

Examples

$("myList")		selects the element with id=myList
.select("li.new")		selects all DOM elements of type <LI> with CSS class new within subtree beneath myList
$("widget")		selects element with id="widget"
.down("img div.handle",2)		internally returns list of all tags that are children of a DIV with CSS class handle, and returns the second one

Finding DOM Elements Using jQuery

Examples

$("div")		select all nodes by tag type
$("#myList")		select by unique id
$("ul#myList li.new")		complex CSS selector

Modifying the DOM

Again, the DOM standard gives us a basic set of tools to work with, and browser vendors have effectively standardized a few more.

Modifying the DOM with Prototype

Prototype favors the use of innerHTML to modify the DOM. It enhances this with the Insertion namespace, and, more recently, an insert method on the DOM element class itself.

Prototype provides no support for building DOM elements programmatically, but the Scriptaculous library adds a DOMBuilder object to the mix.

Modifying the DOM with jQuery

jQuery is based around selecting sets of DOM elements, and it provides methods for manipulating sets of DOM elements in bulk. (These can be used on sets of one element too!) The methods here all operate on a set of DOM nodes returned from a selector.

Both jQuery and Prototype (and its sister Scriptaculous) tend towards a style of UI called Unobtrusive Javascript, in which the content of the page is declared as HTML, and subsequently made interactive. Selectors play an important role in this approach, in locating the elements to which to add behavior. There is an alternative approach to developing Ajax UIs, much more akin to desktop application development, in which the DOM elements are created programmatically by javascript components, which the designer then wires together using layouts and containers. Qooxdoo and Ext2 are both examples of this style of UI development.

In an ideal world, choosing the right framework makes development a breeze, but in practice, you'll need to go under the hood from time to time to figure out what's going on. We recommend the following tools to keep your Ajax development on track.