Documenting prototype.js for AJAX

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.

ajax, introduction, tutorial, prototype.js