Page 1 of 2
The jQuery approach to Ajax is built on the jqXHR object which wraps the XmlHttpRequest object that the browser provides. It isn't often that you need delve this deeply into jQuery Ajax, but when you do nothing else will do.
Now Available as a Print Book:
You can buy it from:
USA and World Amazon.com
I The Core UI
- Understanding jQuery (Book Only)
- The DOM And Selectors
- CSS Selectors
- The jQuery Object (Book Only)
- Advanced Filters - Traversing The DOM
- Modifying DOM Objects
- Creating And Modifying The DOM
- jQuery Data
- Function Queues
- jQuery UI
- jQuery UI Custom Control - Widget Factory
- jQuery - Easy Plugins
- Getting Started With QUnit Testing
The companion volume will be available as a book very soon:
Just jQuery: Events, Async & Ajax
- Reinventing Events
- Working With Events (coming soon)
- Asynchronous Code (coming soon)
- Consuming Promises
- Using Promises (coming soon)
- Ajax the Basics - get
- Ajax the Basics - post
- Ajax - Advanced Ajax To The Server
- Ajax - Advanced Ajax To The Client
- Ajax - Advanced Ajax Transports And JSONP
- Ajax - Advanced Ajax The jsXHR Object
- Ajax - Advanced Ajax Character Coding And Encoding
The jqXHR Object
The jqXHR object, or jq(uery)XmlHttpRequest object, is one of the low level features of using jQuery Ajax that at first can mostly be ignored. However, it keeps popping up as it is passed in as a parameter to most of the Ajax event handlers and Promise methods. When you first start using jQuery Ajax you can just treat it as an object that has a number of useful properties that tell you about the nature of the request.
In fact, the jqXHR object is a wrapper for the native XMLHttpRequest object that the browser creates to make an Ajax request. It isn't just a wrapper it extends the native object where necessary and stands in for it when a transport is used that isn't based on the XMLHttpRequest object.
This is an important point because Ajax proper is based on the XMLHttpRequest object that the browser provides and this implements the HTTP transport needed between the client and the server. However as we saw in the previous chapter jQuery can make use of other more general transport objects which are not strictly Ajax and certainly don't make use of the browsers XMLHttpRequest object. In this case the transport has to create a jqXHR object that provides as many properties and methods as possible.
In addition to wrapping the XMLHttpRequest object the jqXHR object is also a Promise which means it can be used to handle asynchronous requests more logically.
An older set of methods - success, error and complete are still supported but don't use them as they are being deprecated - see later for more details.
The jqXHR object also provides the following properties and methods:
The connection has not started
|The data is sent
|headers and status are available.
responseText holds partial data.
|The operation is complete.
The HTTP result code.
The HTTP result text.
responseText when the underlying request responded with xml and/or text, respectively
replaces the named header with the value given. This can only be used from the beforeSend function - see later.
Returns a single string with all of the headers
overrides the mimetype header. This can only be used in the beforeSend function.
returns a string with the named header
This can be used to set callbacks for any HTTP result code. It has to be set in the beforeSend function - see later.
Aborts the transfer - if this is possible.
If you look at the specification of the native XMLHttpRequest object you will discover that it has many more advanced options. However these are not supported by the jsXHR object because they do not work on all browsers. The list of properties and methods is likely to expand as the newer features spread to the majority of browsers.
However if you want to try to set a field on the native XMLHttpRequest you can use the xhrFields option.
xhrField=object of key value pairs
sets the fields named as keys in the object to the value specified.
sets the timeout field to 1000 ms. In most cases you should use the option provided by jQuery rather than setting the native field but this is useful if you need to modify any non-standard fields.
If you really want to do advanced things you can even make use of the xhr option to provide a function that will create a custom XMLHttpRequest object.
Set to a function that returns a custom XMLHttpRequest object.
In most cases this is only useful in creating an enhanced native XMLHttpRequest object.
One of the confusing aspects of the jsXHR object is that many of its properties and methods are available as options in the main Ajax function call.
In most cases which you use is a matter of convenience and preference and, most importantly, exactly where in the Ajax request the actions are carried out. Setting jsXHR properties and using its methods generally happens at a later stage in the request and therefore tends to override what has been set using the Ajax request options.
As well as being able to set options when you make an Ajax call you can also pre-specify all of the options as defaults using the AjaxSetup method.
sets the default for the url property to mysite.com. Now if an Ajax call, any Ajax call, is started without an explicit url option it will request data from mysite.com.
That is you can set defaults for all Ajax options which apply to all Ajax methods - ajax, get, post etc. - unless they are overridden by explicit option values.
The jQuery documentation argues that this isn't a good idea because it might change the way that Ajax requests are handled from third party plugins and so on but sometimes this is what you want to do. So rather then avoiding the use of ajaxSetup you should consider very carefully how to use it. Always specify every option that your Ajax call relies on and don't simply accept defaults that you might later change.
Normally any defaults you set using ajaxSetup can be overridden by explicitly set options at the time of the call - however using beforeSend and the jsXHR object you can enforce many of the defaults - as explained in the next section
Called just before the Ajax transport is started so that you can modify any aspect of the request.
You can change the properties of the jsXHR object any time you have access to it but often you need to add code to the beforeSend function to modify it just before the Ajax request gets underway i.e. when jsXHR.readyState==0.
Notice that at this early stage many of the properties and methods that use data set by the response are either null or undefined. For example, if you try to access say status or statusText you will find they are undefined.
One reason for using the beforeSend function it to modify options and jsXHR properties after they have been set by the Ajax call. For example:
sets the url property to "process.php" no matter what the Ajax request originally asked for.
Using the beforeSend function you can override any choices made at the Ajax call by setting them later in the request sequence. By setting beforeSend in ajaxSetup you can enforce your choices for all Ajax requests without having to set it as part of the options in each Ajax call:
The beforeSend approach has a number of common applications which we'll now explore.