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:

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