Prototype - AJAX Updater() Method

This AJAX Ajax.Updater performs an AJAX request and updates a container's contents based on the response text.

Ajax.Updater is a specialization of Ajax.Request.

Syntax

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

Return Value

An AJAX Ajax.Updater object.

Ajax.Updater features all the Common Options and callbacks, plus those added by Ajax.Updater()..

There are two more options specific to this method −

Option	Description
evalScripts	Default value is false. This determines whether <script> elements in the response text are evaluated or not.
insertion	Default value is 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.

Option

Description

evalScripts

Default value is false.

This determines whether <script> elements in the response text are evaluated or not.

insertion

Default value is 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.

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

Example

Following is the example to show the usage of Ajax.Updater to update system time. Each time is getting added at the bottom −

<html>
   <head>
      <title>Prototype examples</title>
      <script type = "text/javascript" src = "/javascript/prototype.js"></script>
      
      <script>
         function insertTime() {
            new Ajax.Updater('datetime', '/cgi-bin/timer.cgi', {
               method: 'get', 
               insertion: Insertion.Bottom
            });
         }
      </script>
   </head>

   <body>
      <p>Click update button many time to see the result.</p>
      <br />
 
      <div id = "datetime">Date & Time</div>
      <br />
      <br />
      <input type = "button" value = "Update" onclick = "insertTime();"/>
   </body>
</html>

Here is the content of timer.cgi.

#!/usr/bin/perl

print "Content-type: text/html\n\n";

$datetime = localtime;
print $datetime;
print "<br />";

Output

Single Container, or success/failure Alternative ?

Let us assume that in the above example, 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.

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

prototype_ajax_tutorial.htm