Wrapping XMLHTTPRequestthe Ajax Object

prototype.js defines an Ajax object designed to simplify the development of your JavaScript code when building Ajax applications. This object has a number of classes that encapsulate the code you need to send server requests, monitor their progress, and deal with the returned data.

Ajax.Request

Ajax.Request deals with the details of creating an instance of the XMLHTTPRequest object and sending a correctly formatted request. Calling it is straightforward:

[View full width]

var myAjax = new Ajax.Request( url, {method: 'post', parameters: mydata, onComplete:
 responsefunction} );

In this call, url defines the location of the server resource to be called, method may be either post or get, mydata is a serialized string containing the request parameters, and responsefunction is the name of the callback function that handles the server response.

Tip

The second argument is constructed using a notation often called JSON (JavaScript Object Notation). The argument is built up from a series of parameter:value pairs, the whole contained within braces. The parameter values themselves may be JSON objects, arrays, or simple values. JSON is popular as a data interchange protocol due to its ease of construction, ease of parsing, and language independence. You can find out more about it at http://www.json.org.

The onComplete parameter is one of several options corresponding to the possible values of the XMLHTTPRequest readyState properties, in this case a readyState value of 4 (Complete). You might instead specify that the callback function should execute during the prior phases Loading, Loaded, or Interactive, by using the associated parameters onLoading, onLoaded, or onInteractive.

There are several other optional parameters, including

asynchronous:false

to indicate that a server call should be made synchronously. The default value for the asynchronous option is true.

Ajax.Updater

On occasions when you require the returned data to update a page element, the Ajax.Updater class can simplify the task. All you need to do is to specify which element should be updated:

var myAjax = new Ajax.Updater(elementID, url, options);

The call is somewhat similar to that for Ajax.Request but with the addition of the target element's ID as the first argument. The following is a code example of Ajax.Updater:

<script>
  function updateDIV(mydiv)
  {
      var url = 'http://example.com/serverscript.php';
      var params = 'param1=value1&param2=value2';
      var myAjax = new Ajax.Updater
               (
               mydiv,
               url,
               {method: 'get', parameters: params}
               );


  }
</script>
<input type="button" value="Go"
onclick="updateDIV(targetDiv)">
<div id="targetDiv"></div>

Once again, several additional options may be used when making the call. A noteworthy one is the addition of

evalscripts:true

to the options list. With this option added, any JavaScript code returned by the server will be evaluated.

Ajax.PeriodicalUpdater

The Ajax.PeriodicalUpdater class can be used to repeatedly create an Ajax.Updater instance. In this way you can have a page element updated after a certain time interval has elapsed. This can be useful for such applications as a stock market ticker or an RSS reader because it ensures that the visitor is always viewing reasonably up-to-date information.

Ajax.PeriodicalUpdater adds two further parameters to the Ajax.Updater options:

• frequency The delay in seconds between successive updates. Default is two seconds.

• decay The multiplier by which successive delays are increased if the server should return unchanged data. Default value is 1, which leaves the delay constant.

Here's an example call to Ajax.PeriodicalUpdater:

var myAjax = new Ajax.PeriodicalUpdater(elementID, url, {frequency: 3.0, decay: 2.0});

Here we elected to set the initial delay to 3 seconds and have this delay double in length each time unchanged data is returned by the server.