Prototype JavaScript framework

A class that performs an Ajax request and updates a container’s contents with the contents of the response.

Ajax.Updater is a subclass of Ajax.Request built for a common use-case.

Example

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

This example will make a request to the URL /items (with the given parameters); it will then replace the contents of the element with the ID of items with whatever response it receives.

Callbacks

Ajax.Updater supports all the callbacks listed in the Ajax section. Note that the onComplete callback will be invoked after the element is updated.

Additional options

Ajax.Updater has some options of its own apart from the common options described in the Ajax section:

• evalScripts (Boolean; defaults to false): Whether <script> elements in the response text should be evaluated.
• insertion (String): By default, Element.update is used, meaning the contents of the response will replace the entire contents of the container. You may instead insert the response text without disrupting existing contents. The insertion option takes one of four strings — top, bottom, before, or after — and inserts the contents of the response in the manner described by Element#insert.

About `evalScripts` and defining functions

If you use evalScripts: true, any <script> block will be evaluated. This does not mean it will be evaluated in the global scope. In other words:

• The evaluation scope will be that of Prototype's internal processing function. Anything in your script declared with the var keyword will be discarded momentarily after evaluation, and will be invisible to any other scope.
• If any <script> blocks inside Ajax responses define functions, they will need to be assigned to properties of the window object — not declared with the function keyword.

For example, this won't work:

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

Instead, use the following syntax:

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

Single container, or success/failure split?

The examples above all assume you’re going to update the same container whether your request succeeds or fails. Instead, 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 have a success property whose value identifies the container to be updated on 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: 'bottom'
});

This next example assumes failed requests will deliver an error message as response text — one that should be shown to the user in another area:

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