Prototype JavaScript framework - Ajax

Ajax.Response

2007-12-24T00:41:00Z

The object passed as the first argument of all Ajax requests callbacks.

This is a wrapper around the native xmlHttpRequest object (or it’s ActiveX counterpart). It normalizes cross-browser issues while adding support for JSON via the responseJSON and headerJSON properties.

Properties of the `Ajax.Response` object

Property	Type	Description
`status`	`Number`	The HTTP status code sent by the server.
`statusText`	`String`	The HTTP status text sent by the server.
`readyState`	`Number`	The request’s current state. `0` corresponds to `"Uninitialized"`, `1` to `"Loading"`, `2` to `"Loaded"`, `3` to `"Interactive"` and `4` to `"Complete"`.
`responseText`	`String`	The text body of the response.
`responseXML`	`document Object` or `null`	The XML body of the response if the content-type of the request is set to `application/xml`. `null` otherwise.
`responseJSON`	`Object`, `Array` or `null`	The JSON body of the response if the content-type of the request is set to `application/json`. `null` otherwise.
`headerJSON`	`Object`, `Array` or `null`	Auto-evaluated content of the `X-JSON` header if present. `null` otherwise. This is useful to transfer small amounts of data.
`request`	`Object`	The request object itself (an instance of `Ajax.Request` or `Ajax.Updater`).
`transport`	`Object`	The native `xmlHttpRequest` object itself.

Methods of the `Ajax.Response` object

Method	Type	Description
`getHeader(name)`	`String` or `null`	Returns the value of the requested header if present. `null` otherwise. Does not throw errors on undefined headers like it’s native counterpart does.
`getAllHeaders()`	`String` or `null`	Returns a string containing all headers separated by a line break. Does not throw errors if no headers are present like it’s native counterpart does.
`getResponseHeader(name)`	`String`	Returns the value of the requested header if present. Throws an error otherwise. This is just a wrapper around the `xmlHttpRequest` object’s native method. Prefer it’s shorter counterpart `getHeader`.
`getAllResponseHeaders()`	`String`	Returns a string containing all headers separated by a line break. Throws an error otherwise. This is just a wrapper around the `xmlHttpRequest` object’s native method. Prefer it’s shorter counterpart `getAllHeaders`.

Ajax.Responders

2007-01-12T22:06:00Z

Ajax.Responders.register(responder)
Ajax.Responders.unregister(responder)

A repository of global listeners notified about every step of Prototype-based AJAX requests.

Sometimes, you need to provide generic behaviors over all AJAX operations happening in the page (through Ajax.Request, Ajax.Updater or Ajax.PeriodicalUpdater).

For instance, you might want to automatically show an indicator when an AJAX request is ongoing, and hide it when none are. You may well want to factor out exception handling as well, logging those somewhere on the page in a custom fashion. The possibilities are plenty.

To achieve this, Prototype provides Ajax.Responders, which lets you register (and if you wish to, unregister later) responders, which are objects with properly-named methods. These names are the regular callback names, and your responders can implement any set of interest.

For instance, Prototype automatically registers a responder that maintains a nifty variable: Ajax.activeRequestCount. This contains, at any time, the amount of currently active AJAX requests (those created by Prototype, anyway), by monitoring their onCreate and onComplete events. The code for this is fairly simple:


Ajax.Responders.register({
  onCreate: function() {
    Ajax.activeRequestCount++;
  },
  onComplete: function() {
    Ajax.activeRequestCount--;
  }
});

All callbacks in the life-cycle are available; actually, onCreate is only available to responders, as it wouldn’t make a lot of sense to individual requests: you do know when your code creates them, don’t you? It is triggered even before the XHR connection is opened, which makes it happen right before onUninitialized.

Unregister: remember the reference…

As always, unregistering something requires you to use the very same object you used at registration. So if you plan on unregistering a responder, be sure to define it first, then pass the reference to register, and finally, when the time comes, to unregister.

Ajax

2006-12-05T21:42:00Z

Prototype offers three objects to deal with AJAX communication, which are listed below. With Prototype, going Ajaxy is downright simple! All three objects share a common set of options, which are discussed separately.

The articles below provide you with several examples. The Learn section also features a more narrative, tutorial-style article.

Ajax Options

2006-11-18T18:08:00Z

This details all core options (shared by all AJAX requesters) and callbacks.

All requester object in the Ajax namespace share a common set of options and callbacks. Callbacks are called at various points in the life-cycle of a request, and always feature the same list of arguments. They are passed to requesters right along with their other options.

Common options

Option	Default	Description
`asynchronous`	`true`	Determines whether `XMLHttpRequest` is used asynchronously or not. Since synchronous usage is rather unsettling, and usually bad taste, you should avoid changing this. Seriously.
`contentType`	`'application/x-www-form-urlencoded'`	The `Content-Type` header for your request. You might want to send XML instead of the regular URL-encoded format, in which case you would have to change this.
`encoding`	`'UTF-8'`	The encoding for your request contents. It is best left as is, but should weird encoding issues arise, you may have to tweak it in accordance with other encoding-related parts of your page code and server side.
`method`	`'post'`	The HTTP method to use for the request. The other widespread possibility is `'get'`. As a Ruby On Rails special, Prototype also reacts to other verbs (such as `'put'` and `'delete'` by actually using `'post'` and putting an extra `'_method'` parameter with the originally requested method in there.
`parameters`	`''`	The parameters for the request, which will be encoded into the URL for a `'get'` method, or into the request body for the other methods. This can be provided either as a URL-encoded string or as any `Hash`-compatible object (basically anything), with properties representing parameters.
`postBody`	None	Specific contents for the request body on a `'post'` method (actual method, after possible conversion as described in the `method` opt ion above). If it is not provided, the contents of the `parameters` option will be used instead.
`requestHeaders`	See text	Request headers can be passed under two forms: As an object, with properties representing headers. As an array, with even-index (0, 2…) elements being header names, and odd-index (1, 3…) elements being values. Prototype automatically provides a set of default headers, that this option can override and augment: `X-Requested-With` is set to `'XMLHttpRequest'`. `X-Prototype-Version` provides Prototype's current version (e.g. 1.5.0). `Accept` defaults to `'text/javascript, text/html, application/xml, text/xml, /'` `Content-type` is built based on the `contentType` and `encoding` options.
`evalJS`	true	Automatically evals the content of `Ajax.Response#responseText` if the content-type returned by the server is one of the following: `application/ecmascript`, `application/javascript`, `application/x-ecmascript`, `application/x-javascript`, `text/ecmascript`, `text/javascript`, `text/x-ecmascript`, or `text/x-javascript` and the request obeys SOP. If you need to force evalutation, pass `'force'`. To prevent it altogether, pass `false`.
`evalJSON`	true	Automatically evals the content of `Ajax.Response#responseText` and populates `Ajax.Response#responseJSON` with it if the content-type returned by the server is set to `application/json`. If the request doesn't obey SOP, the content is sanitized before evaluation. If you need to force evalutation, pass `'force'`. To prevent it altogether, pass `false`.
`sanitizeJSON`	`false` for local requests, `true` otherwise.	Sanitizes the content of `Ajax.Response#responseText` before evaluating it.

Common callbacks

When used on individual instances, all callbacks (except onException) are invoked with two parameters: the XMLHttpRequest object and the result of evaluating the X-JSON response header, if any (can be null).

For another way of describing their chronological order and which callbacks are mutually exclusive, see Ajax.Request.

Callback	Description
`onCreate` (v1.5.1)	Triggered when the `Ajax.Request` object is initialized. This is after the parameters and the URL have been processed, but before first using the methods of the XHR object.
`onComplete`	Triggered at the very end of a request's life-cycle, once the request completed, status-specific callbacks were called, and possible automatic behaviors were processed.
`onException`	Triggered whenever an XHR error arises. Has a custom signature: the first argument is the requester (i.e. an `Ajax.Request` instance), the second is the exception object.
`onFailure`	Invoked when a request completes and its status code exists but is not in the 2xy family. This is skipped if a code-specific callback is defined, and happens before `onComplete`.
`onInteractive`	(Not guaranteed) Triggered whenever the requester receives a part of the response (but not the final part), should it be sent in several packets.
`onLoaded`	(Not guaranteed) Triggered once the underlying XHR object is setup, the connection open, and ready to send its actual request.
`onLoading`	(Not guaranteed) Triggered when the underlying XHR object is being setup, and its connection opened.
`onSuccess`	Invoked when a request completes and its status code is undefined or belongs in the 2xy family. This is skipped if a code-specific callback is defined, and happens before `onComplete`.
`onUninitialized`	(Not guaranteed) Invoked when the XHR object was just created.
`on`XYZ	With XYZ being an HTTP status code for the response. Invoked when the response just completed, and the status code is exactly the one we used in t he callback name. Prevents execution of `onSuccess` / `onFailure`. Happens before `onComplete`.

Responder callbacks

When used on responders, all callbacks (except onException and onCreate) are invoked with three parameters: the requester (i.e. the corresponding "instance" of Ajax.Request) object, the XMLHttpRequest object and the result of evaluating the X-JSON response header, if any (can be null). They also execute in the context of the responder, bound to the this reference.

Callback	Description
`onCreate`	Triggered whenever a requester object from the `Ajax` namespace is created, after its parameters where adjusted and its before its XHR connection is opened. This takes two arguments: the requester object and the underlying XHR object.
`onComplete`	Triggered at the very end of a request's life-cycle, once the request completed, status-specific callbacks were called, and possible automatic behaviors were processed.
`onException`	Triggered whenever an XHR error arises. Has a custom signature: the first argument is the requester (i.e. an `Ajax.Request` instance), the second is the exception object.
`onInteractive`	(Not guaranteed) Triggered whenever the requester receives a part of the response (but not the final part), should it be sent in several packets.
`onLoaded`	(Not guaranteed) Triggered once the underlying XHR object is setup, the connection open, and ready to send its actual request.
`onLoading`	(Not guaranteed) Triggered when the underlying XHR object is being setup, and its connection opened.
`onUninitialized`	(Not guaranteed) Invoked when the XHR object was just created.

Ajax.PeriodicalUpdater

2006-11-18T18:07:00Z

new Ajax.PeriodicalUpdater(container, url[, options])

Periodically performs an AJAX request and updates a container’s contents based on the response text. Offers a mechanism for “decay,” which lets it trigger at widening intervals while the response is unchanged.

This object addresses the common need of periodical update, which is used by all sorts of “polling” mechanisms (e.g. in an online chatroom or an online mail client).

The basic idea is to run a regular Ajax.Updater at regular intervals, monitoring changes in the response text if the decay option (see below) is active.

Additional options

Ajax.PeriodicalUpdater features all the common options and callbacks, plus those added by Ajax.Updater. It also provides two new options that deal with the original period, and its decay rate (how Rocket Scientist does that make us sound, uh?!).

Option	Default	Description
`frequency`	`2`	Okay, this is not a frequency (e.g 0.5Hz), but a period (i.e. a number of seconds). Don’t kill me, I didn’t write this one! This is the minimum interval at which AJAX requests are made. You don’t want to make it too short (otherwise you may very well end up with multiple requests in parallel, if they take longer to process and return), but you technically can provide a number below one, e.g. 0.75 second.
`decay`	1	This controls the rate at which the request interval grows when the response is unchanged. It is used as a multiplier on the current period (which starts at the original value of the `frequency` parameter). Every time a request returns an unchanged response text, the current period is multiplied by the decay. Therefore, the default value means regular requests (no change of interval). Values higher than one will yield growing intervals. Values below one are dangerous: the longer the response text stays the same, the more often you’ll check, until the interval is so short your browser is left with no other choice than suicide. Note that, as soon as the response text does change, the current period resets to the original one.

To better understand decay, here is a small sequence of calls from the following example:


new Ajax.PeriodicalUpdater('items', '/items', {
  method: 'get', frequency: 3, decay: 2
});

Call#	When?	Decay before	Response changed?	Decay after	Next period	Comments
1	00:00	2	n/a	1	3	Response is deemed changed, since there is no prior response to compare to!
2	00:03	1	yes	1	3	Response did change again: we “reset” to 1, which was already the decay.
3	00:06	1	no	2	6	Response didn’t change: decay augments by the `decay` option factor: we’re waiting longer now…
4	00:12	2	no	4	12	Still no change, doubling again.
5	00:24	4	no	8	24	Jesus, is this thing going to change or what?
6	00:48	8	yes	1	3	Ah, finally! Resetting decay to 1, and therefore using the original period.

Disabling and re-enabling a `PeriodicalUpdater`

You can pull the brake on a running PeriodicalUpdater by simply calling its stop method. If you wish to re-enable it later, just call its start method. Both take no argument.

Beware! Not a specialization!

Ajax.PeriodicalUpdater is not a specialization of Ajax.Updater, despite its name. When using it, do not expect to be able to use methods normally provided by Ajax.Request and “inherited” by Ajax.Updater, such as evalJSON or getHeader. Also the onComplete callback is hijacked to be used for update management, so if you wish to be notified of every successful request, use onSuccess instead (beware: it will get called before the update is performed).

Ajax.Updater

2006-11-18T18:06:00Z

new Ajax.Updater(container, url[, options])

Performs an AJAX request and updates a container’s contents based on the response text.

Ajax.Updater is a specialization of Ajax.Request: everything about the latter is true for the former. If you’re unfamiliar with Ajax.Request, go read its documentation before going ahead with this one.

A simple example


new Ajax.Updater('items', '/items', {
  parameters: { text: $F('text') }
});

A note about timing

The onComplete callback will get invoked after the update takes place.

Additional options

Since the goal of Ajax.Updater is specifically to update the contents of a DOM element (container) with the response text brought back by the AJAX request, it features a couple of new options, in addition to the common options set. These are:

Option	Default	Description
`evalScripts`	`false`	This determines whether `<script>` elements in the response text are evaluated or not.
`insertion`	None	By default, `Element.update` is used, which replaces the whole contents of the container with the response text. You may want to instead insert the response text around existing contents. Prior to version 1.6.0, you just needed to pass a valid `Insertion` object for this, such as `Insertion.Bottom`. As of Prototype 1.6.0, this notation is deprecated. Simply pass either `'top'`, `'bottom'`, `'before'` or `'after'` as a string instead.

In the following example, we assume that creating a new item through AJAX returns an XHTML fragment representing only the new item, which we need to add within our list container, but at the bottom of its existing contents. Here it goes:


new Ajax.Updater('items', '/items', {
  parameters: { text: $F('text') },
  insertion: Insertion.Bottom
});

About `evalScripts` and defining functions

If you use evalScripts: true, any <script> block will be evaluated. This does not mean it will get included in the page: they won't. Their content will simply be passed to the native eval() function. There are two consequences to this:

The local scope will be that of Prototype's internal processing function. Anything in your script declared with var will be discarded momentarily after evaluation, and at any rate will be invisible to the remainder of the page scripts.
If you define functions in there, you need to actually create them, otherwise they won't be accessible to the remainder of the page scripts. That is, the following code won't work:


// This kind of script won't work if processed by Ajax.Updater:
function coolFunc() {
  // Amazing stuff!
}

You will need to use the following syntax:


// This kind of script WILL work if processed by Ajax.Updater:
coolFunc = function() {
  // Amazing stuff!
}

That’s a common trickster, biting beginners in the ankle. So watch out!

Single container, or success/failure alternative?

The examples above all assume you’re going to update the same container whether your request succeeds or fails. There may very well be times when you don’t want that. You may want to update only for successful requests, or update a different container on failed requests.

To achieve this, you can pass an object instead of a DOM element for the container parameter. This object must exhibit a success property, whose value is the container to be updated upon successful requests. If you also provide it with a failure property, its value will be used as the container for failed requests.

In the following code, only successful requests get an update:


new Ajax.Updater({ success: 'items' }, '/items', {
  parameters: { text: $F('text') },
  insertion: Insertion.Bottom
});

The next example assumes failed requests will feature an error message as response text, and will go on to update another element with it, probably a status zone.


new Ajax.Updater({ success: 'items', failure: 'notice' }, '/items', {
  parameters: { text: $F('text') },
  insertion: Insertion.Bottom
});

Ajax.Request

2006-11-18T18:05:00Z

new Ajax.Request(url[, options])

Initiates and processes an AJAX request.

This object is a general-purpose AJAX requester: it handles the life-cycle of the request, handles the boilerplate, and lets you plug in callback functions for your custom needs.

In the optional options hash, you usually provide a onComplete and/or onSuccess callback, unless you're in the edge case where you're getting a JavaScript-typed response, that will automatically be eval'd.

For a full list of common options and callbacks, see Ajax Options.

The only proper way to create a requester is through the new operator. As soon as the object is created, it initiates the request, then goes on processing it throughout its life-cyle.

A basic example


var url = '/proxy?url=' + encodeURIComponent('http://www.google.com/search?q=Prototype');
// notice the use of a proxy to circumvent the Same Origin Policy.

new Ajax.Request(url, {
  method: 'get',
  onSuccess: function(transport) {
    var notice = $('notice');
    if (transport.responseText.match(/href="http:\/\/prototypejs.org/))
      notice.update('Yeah! You are in the Top 10!').setStyle({ background: '#dfd' });
    else
      notice.update('Damn! You are beyond #10...').setStyle({ background: '#fdd' });
  }
});

Request life-cycle

Underneath our nice requester objects lies, of course, XMLHttpRequest. The defined life-cycle is as follows:

Created
Initialized
Request sent
Response being received (can occur many times, as packets come in)
Response received, request complete

As you can see in Ajax options, Prototype's AJAX objects define a whole slew of callbacks, which are triggered in the following order:

onCreate (this is actually a callback reserved to AJAX global responders)
onUninitialized (maps on Created)
onLoading (maps on Initialized)
onLoaded (maps on Request sent)
onInteractive (maps on Response being received)
onXYZ (numerical response status code), onSuccess or onFailure (see below)
onComplete

The two last steps both map on Response received, in that order. If a status-specific callback is defined, it gets invoked. Otherwise, if onSuccess is defined and the response is deemed a success (see below), it is invoked. Otherwise, if onFailure is defined and the response is not deemed a sucess, it is invoked. Only after that potential first callback is onComplete called.

A note on portability

Depending on how your browser implements XMLHttpRequest, one or more callbacks may never be invoked. In particular, onLoaded and onInteractive are not a 100% safe bet so far. However, the global onCreate, onUninitialized and the two final steps are very much guaranteed.

`onSuccess` and `onFailure`, the under-used callbacks

Way too many people use Ajax.Request in a similar manner to raw XHR, defining only an onComplete callback even when they're only interested in "successful" responses, thereby testing it by hand:


// This is too bad, there's better!
new Ajax.Request('/your/url', {
  onComplete: function(transport) {
    if (200 == transport.status)
      // yada yada yada
  }
});

First, as described below, you could use better "success" detection: success is generally defined, HTTP-wise, as either no response status or a "2xy" response status (e.g., 201 is a success, too). See the example below.

Second, you could dispense with status testing altogether! Prototype adds callbacks specific to success and failure, which we listed above. Here's what you could do if you're only interested in success, for instance:


new Ajax.Request('/your/url', {
  onSuccess: function(transport) {
      // yada yada yada
  }
});

Automatic JavaScript response evaluation

If an ajax request follows the Same Origin Policy and it's response has a JavaScript-related content-type, the content of the responseText property will automatically be passed to eval

What this means is, you don't even need to provide a callback to leverage pure-JavaScript AJAX responses. That's pretty cool, wouldn't you say? The list of JavaScript-related MIME types handled by Prototype is:

application/ecmascript
application/javascript
application/x-ecmascript
application/x-javascript
text/ecmascript
text/javascript
text/x-ecmascript
text/x-javascript

The MIME type string is examined in a case-insensitive manner.

Methods you may find useful

Instances of the Request object provide several methods that can come in handy in your callback functions, especially once the request completed.

Is the response a successful one?

The success() method examines the XHR's status property, and follows general HTTP guidelines: unknown status is deemed successful, as is the whole 2xy status code family. It's a generally better way of testing your response than the usual 200 == transport.status.

Getting HTTP response headers

While you can obtain response headers from the XHR object, using its getResponseHeader method, this makes for slightly verbose code, and several implementations may raise an exception when the header is not found. To make this easier, you can use the Ajax.Response#getHeader method, which just delegates to the longer version and returns null should an exception occur:


new Ajax.Request('/your/url', {
  onSuccess: function(response) {
    // Note how we brace against null values
    if ((response.getHeader('Server') || '').match(/Apache/))
      ++gApacheCount;
    // Remainder of the code
  }
});

Evaluating JSON headers

Some backends will return JSON not as response text, but in the X-JSON header. In which case, you don't even need to evaluate the returned JSON yourself, as Prototype automatically does so and passes it as the headerJSON property of the Ajax.Response object. Note that if there is no such header or its contents is invalid, this property will be set to null.


new Ajax.Request('/your/url', {
  onSuccess: function(transport) {
    transport.headerJSON
  }
});

Prototype JavaScript framework - Ajax

Ajax.Response

Properties of the Ajax.Response object

Methods of the Ajax.Response object

Ajax.Responders

Unregister: remember the reference…

Ajax

Ajax Options

Common options

Common callbacks

Responder callbacks

Ajax.PeriodicalUpdater

Additional options

Disabling and re-enabling a PeriodicalUpdater

Beware! Not a specialization!

Ajax.Updater

A simple example

A note about timing

Additional options

About evalScripts and defining functions

Single container, or success/failure alternative?

Ajax.Request

A basic example

Request life-cycle

A note on portability

onSuccess and onFailure, the under-used callbacks

Automatic JavaScript response evaluation

Methods you may find useful

Is the response a successful one?

Getting HTTP response headers

Evaluating JSON headers

Properties of the `Ajax.Response` object

Methods of the `Ajax.Response` object

Disabling and re-enabling a `PeriodicalUpdater`

About `evalScripts` and defining functions

`onSuccess` and `onFailure`, the under-used callbacks