ajax jqueryapi,jQuery.ajaxTransport()
A transport is an object that provides two methods, send and abort, that are used internally by $.ajax() to issue requests. A transport is the most advanced way to enhance $.ajax() and should be used only as a last resort when prefilters and converters are insufficient.
Since each request requires its own transport object instance, transports cannot be registered directly. Therefore, you should provide a function that returns a transport instead.
Transports factories are registered using $.ajaxTransport(). A typical registration looks like this:
1
2
3
4
5
6
7
8
9
10
11
12
$.ajaxTransport( dataType, function(options, originalOptions, jqXHR){
if( /* transportCanHandleRequest */ ) {
return {
send: function(headers, completeCallback){
// Send code
},
abort: function(){
// Abort code
}
};
}
});
where:
options are the request options
originalOptions are the options as provided to the $.ajax() method, unmodified and, thus, without defaults from ajaxSettings
jqXHR is the jqXHR object of the request
headers is an object of (key-value) request headers that the transport can transmit if it supports it
completeCallback is the callback used to notify Ajax of the completion of the request
completeCallback has the following signature:
1
function(status, statusText, responses, headers){}
where:
status is the HTTP status code of the response, like 200 for a typical success, or 404 for when the resource is not found.
statusText is the statusText of the response.
responses (Optional) is An object containing dataType/value that contains the response in all the formats the transport could provide (for instance, a native XMLHttpRequest object would set responses to { xml: XMLData, text: textData } for a response that is an XML document)
headers (Optional) is a string containing all the response headers if the transport has access to them (akin to what XMLHttpRequest.getAllResponseHeaders() would provide).
Just like prefilters, a transport's factory function can be attached to a specific dataType:
1
2
3
$.ajaxTransport( "script", function(options, originalOptions, jqXHR){
// Will only be called for script requests
});
The following example shows how a minimal image transport could be implemented:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
$.ajaxTransport( "image", function(s){
if ( s.type === "GET" && s.async ) {
var image;
return {
send: function(_ , callback){
image = new Image();
function done(status){
if ( image ) {
var statusText = ( status === 200 ) ? "success" : "error",
tmp = image;
image = image.onreadystatechange = image.onerror = image.onload = null;
callback( status, statusText, { image: tmp } );
}
}
image.onreadystatechange = image.onload = function(){
done( 200 );
};
image.onerror = function(){
done( 404 );
};
image.src = s.url;
},
abort: function(){
if ( image ) {
image = image.onreadystatechange = image.onerror = image.onload = null;
}
}
};
}
});
Handling Custom Data Types
The jQuery Ajax implementation comes with a set of standard dataTypes, such as text, json, xml, and html.
Use the converters option in $.ajax().
The unminified jQuery source itself includes a list of default converters, which effectively illustrates how they can be used:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
// List of data converters
// 1) Key format is "source_type destination_type"
// (a single space in-between)
// 2) The catchall symbol "*" can be used for source_type
converters: {
// Convert anything to text
"* text": window.String,
// Text to html (true = no transformation)
"text html": true,
// Evaluate text as a json expression
"text json": jQuery.parseJSON,
// Parse text as xml
"text xml": jQuery.parseXML
}
When you specify a converters option globally in $.ajaxSetup() or per call in $.ajax(), the object will map onto the default converters, overwriting those you specify and leaving the others intact.
For example, the jQuery source uses $.ajaxSetup() to add a converter for "text script":
1
2
3
4
5
6
7
8
9
10
11
jQuery.ajaxSetup({
accepts: {
script: "text/javascript, application/javascript"
},
contents: {
script: /javascript/
},
converters: {
"text script": jQuery.globalEval
}
});