Ajax.Updater

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:


// 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
});