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.

Asynchronous JavaScript Part 4 - AJAX (a quick introduction)

In the previous 3 parts of this series on asynchronous JavaScript, I have talked at length about ADIJ. I suggest starting at part 1 to catch up!

AJAX is a term which has been bastardised to describe any sort of interactive behaviour in a web page. A number of years ago, these interactions were known as dHTML (dynamic HTML). Neither AJAX nor dHTML perfectly describe these types of interactions, but I prefer the latter name.

AJAX to me should mean Asynchronous JavaScript and XML. This is not perfect as it is often the case that XML is not appropriate and sometimes JavaScript, JSON, HTML or even plain text is required instead. Nonetheless, the acronym AJAX still has one definite meaning to me!

For the purposes of this post and the remainder of this series I will use it to mean any form of asynchronous HTTP request whose response will be handled using JavaScript code whatever form that response takes.

AJAX is a very useful and powerful technique invented by Microsoft for Outlook Web Access and later adopted by other browser vendors. When used in a fairly light touch manner, AJAX techniques can give the user a greatly enhanced experience.

AJAX involves sending an HTTP request to a web server and getting a response asynchronously which is handled in JavaScript. This means more data can be requested from the server or passed to the server without the user seeing the web page refresh.

An asynchronous request happens in the background - it allows other operations to be performed whilst the HTTP cycle is completed. You provide a callback function to the AJAX object which is called once the HTTP cycle is complete. I wont go into more detail around implementation and what it all means as there are many excellent tutorials already written. The W3Schools has one of their own.

Using AJAX it is possible do things such as post a form or update the content of a web page without the user going through a page refresh cycle. This makes the web page seem more like an application and can make it better for users to interact with.

Of course, JSquared has an AJAX component which is extremely simple to use yet offers flexibility and power. In part 5 of this series, I will walk through the AJAX object and then discuss how to use it.