Asynchronous JavaScript Part 5 - The JSquared AJAX Object

In my previous post in this series, I introduced some of my thoughts on AJAX. I will now go into detail as to how to use the JSquared AJAX object.

The AJAX object just like ADIJ is an instance based object. That is to say that for each AJAX request you wish to make, you create an instance of the object and then call a method on it to send the request. The same object can be reused or new instances can be created.

The AJAX object will require certain parameters to be provided and generally it is easiest to do so in the constructor, however, the object has methods for setting these values later.

Only one parameter is required and that is the URL the request is going to. The full list of parameters is:

URL - must be provided either in the constructor or using the setUrl method
method - the HTTP verb to be used for the request. Defaults to GET
onSuccess - the callback function if the request is successful
onFail - the callback function if the request fails
scope - the scope in which to run the onSuccess or onFail handler (the scope sets the value of this within the callback function). Defaults to the handler function itself
timeoutLength - the maximum time to wait for a server response to the request before timing out the request and calling the onFail handler. Defaults to 12 seconds
headers - an array of objects containing key and value pairs which are the additional headers to add to the request

Each of these parameters can be set once the object is created using a method.

To send the request, simply call the send method:

var myAjaxRequest = new J2.AJAX( {url: "myAJAXUrl.html"} );

myAjaxRequest.send();

The send method accepts an argument which is the string of data to add to the request. This argument is optional.

As you can clearly see, the parameters are passed into the constructor as a JavaScript object using object notation.

If you provide an onSuccess handler, that will be called if the request completes successfully and will have the AJAX object passed in as the first argument to the function. This will allow all the properties of the request to be accessed.

If the request should fail, the onFail handler will be called. The first argument passed to the fail handler is the AJAX object. The second argument will be the failure code. The code can then be examined by comparing it against the value of the AJAX failure codes object which looks as follows:

J2.AJAX.FailureCodes = {

    general: "xx1",

    unauthorised: 401,

    notFound: 404,

    timeout: 408,

    server: 500   

}

If you do not provide an onSuccess or onFail handler, then the object will simply do nothing - there will be no error shown.

Once again, I have to say that it is as simple as that. This is a really powerful but easy to use AJAX object.

This is the end of the series on Asynchronous JavaScript. I will be writing more about the other features of JSquared in the near future.