Eight Weeks of Prototype: Week 5, Ajax with Prototype

Event Callbacks

The next part of specifying the request options is to specify the functions that should be called when certain events occur. These are included in the options array just as above, except each value should be either a function or the name of a function to call. In the next section I'll show you how to create these functions.

The following list shows the most common callbacks that you will use. There are others available, but not all are available on all browsers. You can find a full list of these at http://prototypejs.org/api/ajax/options.

• onSuccess: This callback is triggered when a request is completed and the HTTP response code is in the 200s. In the past I have seen a lot of code utilizing XmlHttpRequest that checks specifically for a response code of 200, whereas this isn't necessarily the response code that will be returned. With onSuccess, this is not a problem.
• onFailure: This callback is triggered when a request completes but the HTTP response code is not in the 200s. For instance, if a 404 File Not Found error occurs then this callback would be used.
• onComplete: Regardless of whether a request is deemed to have succeeded or failed, this callback is triggered upon completion of a request. This is the final callback to be triggered. In other words, if you specify onSuccess or onFailure, then onComplete will be used after that.

Listing 6 shows an example of specifying these callbacks in the request options. Each callback accepts the response object (an instance of Ajax.Response) as the first argument. I will cover how to specifically use this response in the next section.

function onRequestSuccess(transport)
{
    // handle the response
}
 
function onRequestFailure(transport)
{
    // handle the response
}
 
function onRequestComplete(transport)
{
    // handle the response
}
 
var url     = '/url/to/request';
var options = {
    method : 'post',
    parameters : {
        name    : 'Quentin',
        country : 'Australia'
    },
    onSuccess  : onRequestSuccess,
    onFailure  : onRequestFailure,
    onComplete : onRequestComplete
};
 
new Ajax.Request(url, options);

As an alternative to using onSuccess and onFailure, you can handle specific HTTP response codes. For instance, if you wanted a different handler for a 404 error to a 403 error, you could achieve this easily by specifying the on404 callback and on403 callbacks. You can use any HTTP code, in the format of onXYZ (where XYZ is the response code).

Note however that if you do this, the onFailure or onSuccess callback will not be used for that response code. As an alternative, you may wish to manually check for the response code and act accordingly from within either the onFailure or onSuccess callback.

Listings 7 and 8 show example of two different ways of handling response codes. In the first example, I have specified the on403 and on404 callbacks, while in the second I check the transport.status value to determine the code.

var url     = '/url/to/request';
var options = {
    /* other parameters if required */
    on403 : function(transport) { ... },
    on404 : function(transport) { ... }
};
 
new Ajax.Request(url, options);

function onRequestFailure(transport)
{
    switch (transport.status) {
        case 403:
            // 403 specific handler
            break;
 
        case 404:
            // 404 specific handler
    }
}
 
var url     = '/url/to/request';
var options = {
    /* other parameters if required */
    onFailure : onRequestFailure
};
 
new Ajax.Request(url, options);

Typically you will only ever need to use the onSuccess and onFailure handlers to do something with an Ajax response (although if you're lazy you may not even bother with the onFailure). Typically you won't really need to use the onComplete or other callbacks.

In the next section I will show how to actually do something useful with the callback handlers.

• Next: Handling the Ajax Response