jQuery.ajaxTransport()

jQuery

previous page next page

jQuery.ajaxTransport()

Categories: Ajax > Low-Level Interface

jQuery.ajaxTransport( dataType, handler(options, originalOptions, jqXHR) ) Returns: undefined

Description: Creates an object that handles the actual transmission of Ajax data.

  • version added: 1.5jQuery.ajaxTransport( dataType, handler(options, originalOptions, jqXHR) )

    • dataType
      Type: String
      A string identifying the data type to use
    • handler(options, originalOptions, jqXHR)
      Type: Function()
      A handler to return the new transport object to use with the data type provided in the first argument.

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( 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 reponses 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
31
32
33
34
35
36
37
38
39
 
                                

                                  

                                    $.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 $.ajaxSetup() to augment or modify the data type conversion strategies used by $.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
15
16
17
18
 
                                

                                  

                                    
                                      // 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
                                  

                                

                                

                                  

                                      }
                                  

                                

                                

                                  

                                    });
 POWERED BYHERONOTE
previous page start next page