Documenting prototype.js for AJAX

Wednesday, October 5th, 2005 at 13:05 +0000 (UTC) by Alexander Kirk

As the prototype.js library lacks documentation and I recommend to use the down cut version for AJAX, I thought it might be useful to document how to use the AJAX related functions.

A "normal" AJAX callback

When you just want to do a post-back to the server (for example to store some data the user has just changed) you'd use the following piece of code:




A simple corresponding PHP script (store.php) would look like this:

< ?php
if (!isset($_POST["value"])) {
die("no value given!");
}
$db = mysql_connect();
mysql_select_db("test");
mysql_query("INSERT INTO table (value) VALUES ('" + addslashes($_POST["value"]) + "')");
mysql_close();
echo "successful";
?>

The value the user entered in the prompting box will be stored to a MySQL database. The magic happens in line 2 of the function store(): new Ajax.Request will do an HTTP POST to the given script at the first parameter (store.php) with the parameters given in the second argument. The yet unusual notations within curly brackets denotes a hash (also called associative array) that stores key/value pairs. Here the pair parameters (key) and '&value=' + value (value) are stored. Other possible key/parameter functions can be found at the preliminary documentation of prototype.js by Sergio Pereira.

This brings up a problem common to AJAX applications: you explicitly need to inform the user about what happened, or if it failed. This can be done via an Event handler. The most useful one might be onComplete. It is inserted like this:


function store() {
value = prompt("Give me a value, please.");
new Ajax.Request("store.php", {
parameters: '&value=' + value,
onComplete: function (req) {
if (req.responseText == "successful") {
alert("Your value has been stored successfully");
} else {
alert("Something went wrong when storing your value");
}
}
});
}

This will display an appropriate alert box depending a successful status message by the script. In near future I will describe how to use the Ajax.Updater feature which allows to easily modify your existing page to instantly display results of a query.

, , ,

5 Responses to “Documenting prototype.js for AJAX”

  1. clem Says:

    thanks for the example. Should be btw.

  2. clem Says:

    the script anchor should be with type="text/javascript" and not text.

  3. Alexander Kirk Says:

    Yes of course, thank you.

  4. Jon Says:

    Are there still plans to describe using the Ajax.Updater feature?

  5. Vikas Says:

    Hi, i need example of ajax updater how it is work using Post method in J2ee aplication. I have seen lot example in Php but could not get throught that examples. So if u tell how to use the Ajax updater that will help me most.