Hack 50. Use Prototype s Ajax Tools with Your Application

Hack 50. Use Prototype's Ajax Tools with Your Application

Use an open source software library to handle XMLHttpRequest.

This hack uses the Prototype library's Ajax.Request object to communicate with a backend server, rather than our own. The first step in implementing this hack is to download Prototype from http://prototype.conio.net. (This step may not be necessary; certain frameworks, such as Ruby on Rails, come bundled with the Prototype library.)

Now import the library via a script tag in the web page:

<script src="/books/4/254/1/html/2/js/prototype.js" type="text/javascript"></script> <script src="/books/4/254/1/html/2/js/mylib.js" type="text/javascript"></script> 

The second imported file, mylib.js, contains some custom code the hack will use. Let's put both files in an application directory called js.

This hack requests that the user enter some information in a text field. Then, when the user clicks outside the field or presses Tab, the application connects with a server component using Prototype's Ajax.Request object. The hack then displays the server response in the textarea beneath the entry field as soon as the server returns the call. Figure 6-1 shows what the web page looks like in the Safari browser.

Figure 6-1. Responding to user interaction with Prototype

Figure 6-2 shows what it looks like when the user enters a name in the text field, then clicks somewhere else on the page. The textarea beneath the text field shows the server name, the posted data, the version of Prototype we are using, and the value of the X-Requested-With request header.

Prototype includes this header with Ajax requests, which is a nice feature for when the server component checks whether a request originates from XMLHttpRequest [Hack #59]. Beware, though, because a determined hacker can easily include an X-Requested-With header in order to impersonate this type of request.

Figure 6-2. Connecting to the server using Ajax.Request

Here is the code in mylib.js. It uses various Prototype extensions, including the Ajax.Request object:

window.onload=function(  ){     if($("name_info")) {         $("name_info").onblur=function(  ){             if($F("name_info")){                 _url="http://localhost:8080/hacks/proto";                 showInfo(_url);             }         }     } }; function showInfo(go_url){     if($("display_area") && go_url){         var xmlHttp= new Ajax.Request(go_url, {method: "post",                 parameters: Form.serialize(document.forms[0]),                 onComplete:function(  ){             if(xmlHttp.responseIsFailure(  )) {                 var sts = xmlHttp.transport.status ? xmlHttp.                 transport.status : "undefined";                 $("display_area").value=                 "XMlHttpRequest returned response status "+sts;                 document.getElementById("msg").innerHTML=                 "HTTP response and server information; "+                 "response status="+                 xmlHttp.transport.status;             } else {                 $("display_area").value=xmlHttp.transport.responseText;                 document.getElementById("msg").innerHTML=                 "HTTP response and server information; "+                 "response status="+                 xmlHttp.transport.status;             }         }});     } }

The code uses window.onload to set up the web page's interactive behavior. The text field's onblur event handler executes when the keyboard focus enters and then exits the field (when the user presses Tab or clicks somewhere else on the page).

$("name_info") is a handy Prototype shortcut for document.getElementById('name_info'). $F("name_info") is another shortcut for accessing a text field's or another kind of element's value. Its parameter is either the element's id or an existing element reference, as in:

var n = $("name_info");
//displays the value of the 'name_info' text field
alert($F(n) );

The code then uses a Prototype shortcut to determine if the text field has a value. If it does, the code calls show_info( ). $F("name_info") returns the value of the text field, whose id attribute is name_info.

The URL that the code passes show_info( ) is the address of our server component. The return value from this component ends up in the textarea. But how is the URL sent in the first place? We'll look at that next.

Request Object to Go

Prototype contains an object called Ajax.Request. The code creates this object with the new JavaScript keyword, then considers the job almost finished. You do not have to deal with the XMLHttpRequest nuances, except for creating a callback to handle the server response:

var xmlHttp = new Ajax.Request(go_url, {method: "post",               parameters: Form.serialize(document.forms[0]),               onComplete:function(  ){     if(xmlHttp.responseIsFailure(  )) {         var sts = xmlHttp.transport.status ? xmlHttp.                 transport.status : "undefined";         $("display_area").value=                 "XMlHttpRequest returned response status "+sts;         document.getElementById("msg").innerHTML=                 "HTTP response and server information; response status="+                 xmlHttp.transport.status;     } else {         $("display_area").value=xmlHttp.transport.responseText;         document.getElementById("msg").innerHTML=                 "HTTP response and server information; response status="+                 xmlHttp.transport.status;     } }});

You can also use the syntax function(request){...} (notice that request is the first callback parameter). For example:

onComplete:function(request){
    $("display_area").value=request.responseText;

The first parameter, go_url, is a variable pointing to the server component location. This seems to work best with a relative URL format, as in /hacks/pack_ajax, without the protocol and host information. The method: "post" part is a reminder to hack writers and readers of what kind of HTTP request the code sends; POST is the default, and this explicit parameter is not actually necessary if the code is not using GET.

The hack passes the parameters to the POST request using a Prototype method. The following line:

parameters: Form.serialize(document.forms[0])

generates a chunk of data formatted for posting to a server, based on the form elements' current values (as in name_info=Bruce%20Perry&display_area=&ag=20-29).

The onComplete callback parameters place the response text into the textarea with the code:

onComplete:function(  ){     $("display_area").value=xmlHttp.transport.responseText;

The transport property of Ajax.Request returns the underlying XMLHttpRequest object, from which the code derives the server response in a textual format.

You can get the HTTP status code of the response with xmlHttp.transport.status.

The code also calls an Ajax.Request method called responseIsFailure( ) to determine if the request resulted in a response error. This bit of prototype.js code illustrates what the method is doing:

responseIsSuccess: function(  ) {     return this.transport.status == undefined            || this.transport.status == 0            || (this.transport.status >= 200 && this.transport.status < 300); }, responseIsFailure: function(  ) {     return !this.responseIsSuccess(  ); }