PhpRiot
Become Zend Certified

Prepare for the ZCE exam using our quizzes (web or iPad/iPhone). More info...


When you're ready get 7.5% off your exam voucher using voucher CJQNOV23 at the Zend Store

Eight Weeks of Prototype: Week 5, Ajax with Prototype

Handling the Ajax Response

Now that you know how to specify the callbacks for particular events that occur when performing an Ajax request, I will show you write to write the callback handler.

All of these callbacks are passed an instance of Ajax.Response as the first argument. This object contains information about the request, such as the HTTP status code that resulted from the request, and any response data sent back. Full details about this class can be found at http://prototypejs.org/api/ajax/response.

My own preference is to call this parameter transport. Whatever you call it, be consistent. Functions should be self-documenting, so you should be easily able to determine what the function is used for by its name and the naming of its arguments.

In writing a handler we are typically concerned with the response data. Typically we want to use this data somehow on the current page, whether it's text, HTML, JSON or XML. Because of this, when writing a response handler we are really only concerned with the onSuccess handler, since onFailure occurs only if something went wrong with the request.

Even if the Ajax request resulted in some error condition in your application, if the Ajax request succeeded you then need to handle your application error in the onSuccess handler.

Note: An Ajax request doesn't have to return any data. Some operations involve you simply sending data to the server for it to process, without requiring any response. You don't really need any success or failure handlers if you don't care about the response.

The most commonly used values that are available in the transport variable are as follows:

  • status: The HTTP response code. An example of reading this value is shown in listing 8.
  • statusText: The text that corresponds to the response code, as sent by the server. Since different servers may send a slightly different string for certain response codes, you shouldn't rely on this value.
  • responseText: This is any data that is sent back from the request as a string.
  • responseXml: If data was sent from the server in XML format (with the correct content type header of text/xml), this variable contains the response as a document object.
  • responseJSON: If the data was sent back from the server in JSON format, you can read the data from this array. In the next section I will show you how to do this. Note that the response from the server must use the application/json content type header.

You can read any of these properties from the first argument that is sent to the request handlers. In the previous section I called this variable transport.

Listing 9 shows identical functionality to the Ajax.Updater example in Listing 3, however, in this example we read the responseText variable and update the element accordingly. This example uses the same example HTML, shown in Listing 2.

Listing 9 Populating an element using the responseText property (listing-9.html)
<html>
    <head>
        <title>Populating an element using the responseText property</title>
        <script type="text/javascript" src="/js/prototype.js"></script>
    </head>
    <body>
        <div>
            <input type="button" value="Click Me!" id="myButton" />
        </div>
 
        <script type="text/javascript">
            function onAjaxSuccess(transport)
            {
                $('myButton').up().update(transport.responseText);
            }
 
            function onButtonClick(e)
            {
                var options = {
                    method    : 'get',
                    onSuccess : onAjaxSuccess
                };
 
                new Ajax.Request('listing-02.html', options);
            }
 
            $('myButton').observe('click', onButtonClick);
        </script>
    </body>
</html>

In This Article