This page is part of the Prototype JavaScript framework documentation.
Overview | (...)

The Prototype Ajax.Updater object makes an out of band browser HTTP request. The request can be either synchronous or asynchronous, though almost all calls made using this would be asynchronous. //todo: another example using POST method.

Syntax

  new Ajax.Updater(container, url, options);
 // make a HTTP request to the specified URL and update the 'container' element.

Note: to only update a div on success, you may optionally substitute a property list for a simply element id (ie {success:’div_name’} instead of ‘div_name’)

Options

Hint: If you have set evalScripts:true the script you call (the url parameter) must return a header of ‘Content-Type: text/javascript’ else the browser will not execute it.

Examples

Basic usage:

  new Ajax.Updater('mydiv', '/foo/bar', {asynchronous:true});
  // places result text in the browser object with the id 'mydiv': <div id='mydiv'></div>

Usage with options:

 new Ajax.Updater('mydiv', '/foo/bar', {onComplete:function(){ new Effect.Highlight('mydiv');},asynchronous:true, evalScripts:true});
 // this will evaluate any scripts in <script></script> blocks. Also it will hightlight mydiv on complete.

[...edit me and add more examples...]

Usage with server-side script:

Put this in the same directory as your HTML, and configure your server to run x.cgi scripts:

date.cgi:

#!/bin/bash

echo 'Content-type: text/plain'
echo ''
date

Create this HTML page:
date.html:

<script src="/scripts/prototype.js" type="text/javascript"></script>

<script>
var ajax = new Ajax.Updater(
         'datestr',        // DIV id (XXX: doesnt work?)
         'date.cgi',        // URL
         {                // options
         method:'get',
             onComplete: showResponse
             });

function showResponse(req)
{
$('datestr').innerHTML = req.responseText;
}

</script>

date is now: <div id="datestr">n/a</div>

Or like this :
date2.html:

<script src="/scripts/prototype.js" type="text/javascript"></script>

<script language="JavaScript" type="text/javascript">
var ajax;
function mydate() {
 ajax =  new Ajax.Updater(
         'datestr',        // DIV id must be declared before the method was called
         'date.cgi',        // URL
         {                // options
         method:'get'             
             });

}
</script>

date is now: <div id="datestr">n/a</div>

<script language="JavaScript" type="text/javascript">
    mydate();
</script>

Usage as out-of-band form submit:

Ajax.Updater can be used to submit a form and insert the results into the page, all without a refresh. This works for all form elements except files.

See Ajax.Request for Ajax calls that don’t expect to return rendered data.

Alternative out-of-band form submit:

Instead of using the onSubmit property of the form itself, use a simple button’s onClick value, and have the form’s onSubmit return false. This will stop users from being able to hit return and submit the form, but if you are trying to combine effects or functions (like resetting the form after the Updater finishes, as in the example) this may provide a working solution. Combining certain functions inside the onSubmit seems to create a few problems.

<form id="myform" action="/action/here" method="post" onsubmit="return false;">
<input type="text" name="myinput" />
<input type="button" value="Submit!" onclick="$('changeme').innerHTML = 'Refreshing...'; new Ajax.Updater('changeme', 'processmyform.php', {asynchronous:true, parameters:Form.serialize('myform')});$('myform').reset();$('myinput').activate();return false;" 
</form>

<div id="changeme">
</div>

Note for response containing javascript function declaration

When you have some javascript contained in the server side response, you have to use the evalScripts:true option of the Ajax object.
If you have some function declared in the response be warned that they wont be accessible at all unless you assign them to variables.
The reason for this is that the script is not appended to the page but evaluated, and this won’t create the function at all.

Invalid function definition response example :

<script>
  //this won't work You MUST assign the function to a variable 
  function myresponsefunc(){
    ..do something..
  }
</script>
<a href="javascript:myresponsefunc()">do my func</a>

working function definition response example:

<script>
  //this one should work properly.
  myresponsefunc = function(){
    ..do something..
  }
</script>
<a href="javascript:myresponsefunc()">do my func</a>

Simple AJAX Form Validation Example

Hi, i try to do this code with Ajax.Request but maybe my XP restricts some request, don’t know but it wasn’t work . So,
i realize the example with Ajax.Update that let me post here my work ;-)

The script is divide in two files : in client-side => ‘NICOWEB.verifPseudo Get.html’ , one server-side ‘get.verifierPseudo Scriptaculous.php’ .

Another Example of Practical Usage

If your site regularly uses Ajax.Updater to view pages, it may be wise to implement something like the following:

function Request(page)
{
    document.getElementById('content').innerHTML = 'Loading...';
    new Ajax.Updater('content', 'pages/' + page + '.php', {asynchronous:true, evalScripts:true});
}

The above example shows how an elementary function can be used to replace the need to write out long calls to Ajax.Updater. One can now simply write “Request(‘index’);” to create a new instance of Ajax.Updater and load ‘pages/index.php’ into the main content window.

Description of ‘NICOWEB.verifPseudo Get.html’

This file contains a html form who ‘onBlur’ test the value enter by the user and send an Ajax.Updater on the server side script.

=> sorry no example available, impossible to insert a controlled html image ;-)
Try at this url :
Online NICOWEB example

You like the “loginDiposnibility” example ? You might love the new Nicoweb.fr prototype.js online example at : CSS Beautifier Post
I hope you enjoy this one like the others ;)

Get another example in the usage of Ajax.Updater at Nicoweb.Auction-Bidder
You can almost try Nicoweb.ajaxStore

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title>NICOWEB w/ Scriptaculous or Scriptaculous presented by NICOWEB</title>
<script language="javascript" type="text/javascript" src="js/prototype.js"></script>
<script type="text/javascript" language="javascript">
/* NICOWEB : 07/08/2006 :: script ajax prototype de vérification de disponibilité pseudo submate */
var imgPseudo = "";
function formVerifierDisponibilitePseudo (idImg)
{
    var pseudoToTest =  $('pseudo').value;
    imgPseudo = idImg;

    if (pseudoToTest != "")
    {
            alert('let\'s start the ajax process with "'+pseudoToTest+'".');
          /*new Ajax.Request("http://ns34.hosteur.com/~learnc/espaceemploi/ajax/get.verifierPseudoScriptaculous.php?pseudo"+pseudoToTest, { method: 'get', asynchronous: true, onSuccess:succesRetourAjax, onFailure:erreurRetourAjax} );*/

            new Ajax.Updater('retour','http://ns34.hosteur.com/~learnc/espaceemploi/ajax/get.verifierPseudoScriptaculous.php?pseudo='+pseudoToTest,{ method:'get' , onComplete: succesRetourAjax, onFailure: erreurRetourAjax});
    }
    else
    {
        alert('oops, broken.')
        $(idImg).src = 'http://ns34.hosteur.com/~learnc/espaceemploi/ajax/images/champNonValide.gif';
        return true;
    }
}

function succesRetourAjax (t)
{
    alert(t.responseText);
    if (t.responseText == "succes")
    {
        alert('you can use this pseudo (ndr : test version).');
        $(imgPseudo).src = 'http://ns34.hosteur.com/~learnc/espaceemploi/ajax/images/champValide.gif';
    }
    else
    {
        alert('you can\'t use this pseudo (ndr : test version).');
        $(imgPseudo).src = 'http://ns34.hosteur.com/~learnc/espaceemploi/ajax/images/champNonValide.gif';
    }
}

function erreurRetourAjax (t)
{
    alert('Error ' + t.status + ' -- ' + t.statusText);
    alert('you can\'t user this pseudo (ndr : test version).');
    $(imgPseudo).src = 'http://ns34.hosteur.com/~learnc/espaceemploi/ajax/images/champNonValide.gif';
}
/*  NICOWEB : 07/08/2006 :: fin script ajax prototype de vérification de disponibilité pseudo submate */
</script>

</head>
<body>
<div id="retour"></div>
<table>
    <tr><td colspan="2"><input type="button" name="test" value="other"/></td></tr>
    <tr>
      <td>Enter a pseudo and test his disponibility :</td>
      <td>
          <input name="pseudo" type="text" id="pseudo" value="" class="input" onBlur="formVerifierDisponibilitePseudo('imgPse');"/>
          <img src="http://ns34.hosteur.com/~learnc/espaceemploi/ajax/images/champNonValide.gif" alt="nicoweb/scriptaculous icone champ non valide" id="imgPse" />
      </td>
  </tr>
  <tr><td colspan="2"><input type="button" name="test" value="other"/></td></tr>
  <tr><td colspan="2">NICOWEB NOTES :: in the test version you can't user 'nicoweb', 'nicoweb.fr', 'bertelle nicolas', 'saved', 'ganjaman', 'feliz' as pseudo.<br/>All others are welcome ;-)</td></tr>
</table>

</body>
</html>

Description of ‘ajax/verifierPseudo Scriptaculous.php’

This file, in this test version, compare the value enter by the user with values sotcked in an php array.
If the value is not present function return true else function return false.
The result is control by the javascript functions “succesRetour Ajax” and “erreurRetour Ajax” that changes
the value of control ajax return image ‘imgPse’.

<?
/*
    * 08/08/2006 00:34am
    * ajax/verifierPseudoScriptaculous.php
    * test ajax file, no connection to bdd to preserve my bandwidth ;-)
*/
$tPseudo = array("nicoweb","nicoweb.fr","bertelle nicolas","saved","ganjaman","feliz");
$retour = "";

if ($_GET['pseudo'] != "")
{
    $pseudo = $_GET['pseudo'];
    if (in_array($pseudo,$tPseudo)) { $retour = ""; echo $retour; }
    else { $retour = "succes"; echo $retour; }
}
else { $retour = ""; echo $retour; }

?>

Hope that code extraction can give wings to someone, help others, wish you best with scriptaculous ;-)

Category: Prototype, Stub