Painless JavaScript Using Prototype

Get your Web 2.0 On

"Finally!" you're thinking, "He's got on to what we really want to know about." Yes, I've left it to the end to get into Prototype's AJAX helpers, because they're built on top of all the other stuff we've been going through, and it helps to understand Prototype's form serialization, observers and insertions when we talk about AJAX.

AJAX, in case you've been buried in a very deep hole for the past couple of years, refers to using the browser's XMLHttpRequest object (or equivalent) to communicate with the server without reloading the page. Prototype smoothes over most of the detail, but it's still good to get a bit of background on XMLHttpRequest, which you'll find in this article by Cameron Adams.

So, now you're all pumped to get some Web 2.0 action, let's look in to a really simple AJAX request:

new Ajax.Request("hello.php", {    
 onSuccess : function(resp) {    
   alert("The response from the server is: " + resp.responseText);    
 },    
 onFailure : function(resp) {    
   alert("Oops, there's been an error.");    
 },    
 parameters : "name=Fred"    
});

The Ajax.Request constructor takes a URL and an options object. In this case, we're sending a parameter (name) to hello.php, and alerting its response (or alerting an error if it doesn't work). It's worth taking the time to get familiar with what options are available; here's an overview of the options, along with their defaults:

Prototype adds a custom HTTP header to all its AJAX requests so that your server application can detect that it's an AJAX call, rather than a normal call. The header is:

X-Requested-With: XMLHttpRequest

Here's an example PHP function used to detect an AJAX call:

function isAjax() {    
 return isset($_SERVER['HTTP_X_REQUESTED_WITH']) &&    
     $_SERVER ['HTTP_X_REQUESTED_WITH']  == 'XMLHttpRequest';    
}

Using this approach, you can write AJAX applications that work even if the user is using an old browser or has JavaScript disabled, but that's a whole other article...

Using Form.serialize to Pass Data to Ajax.Request

As we've seen above, the parameters option is used to pass a URL-encoded string of variables. If the data you need to send is set by a form, as it is with most AJAX applications, you can simply use Form.serialize to generate a URL-encoded string from all of your form fields and pass that into the parameters option like so:

function addComment(e) {    
 // submit the form using Ajax    
 new Ajax.Request("comment.php", {    
   parameters : Form.serialize(this),    
   onSuccess : updateComment    
 });    
 Event.stop(e);    
}    
   
Event.observe($("commentform"), "submit", addComment, false);

Writing AJAX Event Handlers

In the example above, onSuccess and onFailure are two examples of AJAX event handlers. Event handler functions given in the options object of an Ajax.Request call are given one argument, which is the XMLHttpRequest object for that AJAX call. I normally call this argument response or resp. You can use this argument to get the response from the server like so:

function successHandler(resp, jsonObj) {    
 // returns the response from the server as raw text    
 resp.responseText    
 // returns the response as an XML document that you can navigate with the DOM    
 resp.responseXML    
 // alert some property of the returned JSON    
 alert(jsonObj.name);    
}

Remember, though, that resp is just the XMLHttpRequest object, so all of those properties are available.

You can send data as JSON from your server by adding the JSON data to the X-JSON response header. This will then automatically be evaluated by Prototype, and sent as the second argument.

The Ajax.Updater and Ajax.PeriodicalUpdater

Many AJAX operations simply involve updating some HTML on your page with HTML returned from the server. The Ajax.Updater object wraps Ajax.Request and simplifies this common use case for us. Here's a simple example:

new Ajax.Updater("mydiv", "hello.php", {    
 parameters : "name=Fred",    
 onFailure : function(resp) {    
   alert("Oops, there's been an error.");    
 }    
});

The above snippet would simply replace the contents of the element whose ID was "mydiv" with whatever content was returned from the server. Ajax.PeriodicalUpdater is similar, but makes the Ajax call repeatedly at an interval that you set:

new Ajax.PeriodicalUpdater("mydiv", "hello.php", {    
 // initial number of seconds interval between calls    
 frequency : 1,    
 decay : 2    
});

The decay option allows you to give your server a bit of a break if it's returning a lot of identical responses. Essentially, every time PeriodicalUpdater makes a request, it compares the results with what the server returned last time. If the values are the same, it multiplies the interval by the decay value. So, for the above example, it would make the next request two seconds later, then four seconds later, and so on, until it received a different result from the server. At that point, the interval would be reset to one second.

AJAX with Responders

AJAX responders allow you to register global event handlers that are triggered for each and every AJAX request that happens on the page. They're very useful for managing applications with large amounts of AJAX activity. For instance, you can use them to show a standard loading animation whenever an AJAX request is happening:

Ajax.Responders.register({    
 onCreate : showLoader,    
 onComplete : hideLoader    
});

If you are looking for some working examples of AJAX with Prototype, try this article.

Where to Next?

As we've seen through this article, Prototype not only is useful on its own, but provides an excellent starting point for writing other, more specialized libraries. That's exactly what a growing number of people have been doing.

Script.aculo.us and Moo.fx

Thomas Fuchs' script.aculo.us is getting a lot of attention at the moment for its whiz-bang effects and clever UI widgets. It was originally part of the core Prototype library, but soon grew out of control and broke free of its parent.

Using Prototype as a basis, script.aculo.us specialises in providing a rich user experience through animated effects, simple to use drag and drop functionality, and powerful UI components. There's a nice Wiki on the site, with a rapidly growing store of quality documentation to help you get started, and examples pages to get your creative juices flowing. As script.aculo.us is getting rather large in file size, it's been split into several files, so your users won't have to download the whole library just so you can use a few slide effects. However, even the individual files are pretty bulky.

If you're after some simple effects, I'd really recommend Moo.fx. It's only 3k in size, and gives you some toggling slide and fade effects that, often, are all that's required in a simple AJAX application. It's also a great starting point if you want to write your own effects. Have a look at the code to see a great example of programming using Prototype's Object.extend to provide simple inheritance. Valerio is obviously very focused on keeping his script file sizes down, so he even has a 'lite' version of Prototype (chopped to around 10k), and a lean version of Ajax.Request, which I find myself using more often than the full Prototype library. It's definitely worth a look.

Behaviour

Behaviour is a great addition to your DOM scripting toolkit that allows you to use CSS selectors to add behaviour to your documents. Here's a sample of what it allows you to do:

Behaviour.register({    
 "#comment_form form" : function(el) {    
   // catch form submission and complete with XHR if possible    
   el.onsubmit = function() {    
     Form.disable(this);    
     new Ajax.Request(this.action, {    
       method: this.method,    
       postBody: Form.serialize(this),    
       onComplete: updateComments});    
     return false;    
   };    
 }    
});

Read more about this over at the Behaviour site. It's now possible to achieve a similar type of thing using the brand new $$ function discussed earlier, so this may eventually become redundant.

jQuery

jQuery is a compact little library that plays well with Prototype and creates a superhero version of the $ function that can take XPath and CSS 3 selectors. It couples that capability with some extremely clever method chaining approach that makes for very concise code. Watch out for this one.

Wrap up

Prototype is a powerful piece of kit when it comes to adding some DOM scripted spice to your web applications. Unfortunately, its capabilities and tools have grown at a much faster rate than its documentation! We've managed to cover every corner of Prototype in this article, but not every method. I hope, though, that you now know where to go to get the extra information you need.

If you want to know more try Ronnie Roller's prototypedoc.com, a resource that keeps up with the growing body of Prototype documentation. Have fun!