XHR
This object is for cross-browser XMLHttpRequest handling. It is essentially a wrapper object which provides functionality for controlling timeout, abortion, retry etc.
The XHR object provides a clean and easy way for doing asyncronous requests using the familiar event assignment for the various readystates. The object should be downloaded it its entirety and not as separate functions/methods.
General Usage
When the object is loaded an anonymous function is run once to setup the factory method for creating new XMLHttpRequests. Having this feature allows us to detect whether XMLHttpRequests are supported by the client
1 // Does the browser support XMLHttpRequests? 2 if (XHR.isEnabled()) 3 alert('XHR supported. You are good to go'); 4 else 5 alert('Your browser does not support XHR');
After verifying that we can indeed use XMLHttpRequests we can instantiate a new XHR object using the constructor
1 // Create a new XHR object (not a request yet) 2 // which has a default timeout of 30 seconds 3 // and 2 retries 4 var myXHR = new XHR(30000,2);
Now we have a XHR object which we can use to send any number of requests. You don't have to instantiate more than one XHR object for the entire session, but you can if you like to keep things separate.
The XHR object has a counter property which increments each time you send a new request. No matter how many XHR objects you have they will all share the same counter. You can use this for debugging or just for an informational purpose.
To setup a new request we can do the following
1 // The function getFromServer will send a request to 2 // some server and fetch some data 3 function getFromServer() { 4 } 5 // To avoid polluting the global namespace we store our XHR 6 // object as a property of the function itself. 7 getFromServer.xhr = new XHR(30000,2); 8 // When the resonse is ready we want the 9 // handleResponse function to...handle the response 10 getFromServer.xhr.onreadystateloaded = handleResponse;
The XHR object is now ready to be opened and send. This works the same way as handling the native XMLHttpRequest object
1 function getFromServer() { 2 // Open the XHR for an asyncronous request 3 getFromServer.xhr.open('GET','http://www.myserver.com/aFile.ext',true); 4 // Send the request 5 getFromServer.xhr.send(null); 6 }
When the request enters readystate 4 (loaded) the onreadystateloaded handler is executed and control is passed to the handleResponse function. If a timeout for more than 30 seconds occured during transmission the request would be resend twise before stopping.
When the handleResponse function is executed the XHR object takes on the value of 'this' meaning that 'this' is a reference to the XHR object not the XMLHttpRequest object.
The handleResponse function can still access the true XMLHttpRequest object through the reference XHR.req as shown below
1 // 'this' refers to the XHR object 2 // 'this.req' refers to the XMLHttpRequest object 3 function handleResponse() { 4 // Get response text 5 alert(this.req.responseText); 6 }
Like you set the onreadystateloaded handler you may set the following handlers as well
1 function myFunction() { 2 // Create XHR obejct with a timeout of 10 seconds and a 3 // max. of 4 retries 4 var xhr = new XHR(10000,4); 5 // Set onreadystateopen handler 6 // Fires when readystate changes to 1 7 xhr.onreadystateopen = function () { ... }; 8 // Set onreadystatesend handler 9 // Fires when readystate changes to 2 10 xhr.onreadystatesend = function () { ... }; 11 // Set onreadystaterecieving handler 12 // Fires when readystate changes to 3 13 xhr.onreadystaterecieving = function () { ... }; 14 // Set onreadystateloaded handler 15 // Fires when readystate changes to 4 16 xhr.onreadystateloaded = function () { ... }; 17 // Set ontimeout handler 18 // Fires if the request times out 19 xhr.ontimeout = function () { ... }; 20 // Set onabort handler 21 // Fires if the request is aborted 22 xhr.onabort = function () { ... }; 23 // Set onretry handler 24 // Fires if the request is retried 25 xhr.onretry = function () { ... }; 26 }
Note that the onabort handler is fired before each invocation of the ontimeout handler
Finally the XHR provides the following methods
1 // Create XHR obejct 2 var xhr = new XHR(); 3 // Force retry of request 4 xhr.retry(); 5 // Force abortion of request 6 xhr.abort();
All other methods like setRequestHeader etc. are mapped directly to the XMLHttpRequest object.
