Урок - jQuery.ajaxTransport()

Группа вКонтакте
Лицензия: Лицензия Creative Commons.

Метод jQuery.ajaxTransport() создает объект для обработки Ajax-запроса.

Синтаксис метода jQuery.ajaxTransport().

jQuery.ajaxTransport( dataType, handler(options, originalOptions, jqXHR) )

где

  • dataType - строка, определяющая тип используемых данных.
  • handler(options, originalOptions, jqXHR) - обработчик возвращающий новый transport-объект для использования в соответсвии с указанным параметром dataType.
  • options - параметры запроса.
  • originalOptions - параметры предоставляемые методу, не измененные и без параметров ajaxSettings.
  • jqXHR - jqXHR-объект текущего запроса.

Описание метода jQuery.ajaxTransport().

Transport-объект предоставляет два метода send и abort, которые используются в jQuery.ajax() для выполнения запроса. Transport - наиболее продвинутый способ, для улучшения работы jQuery.ajax() и должен использоваться в качестве крайнего  средства, когда префильтров(prefilters) и преобразователей (converters) не достаточно.

Так как каждый запрос имеет свой собственный экземпляр Transport-объекта, транспорт не может быть зарегистрирован сразу. Такми образом следует предоставить функцию, которая возвращает transport.

Фабрика (Factory) для Transport-объекта регистрируется с помощью метода ajaxTransport(). Типичный пример выглядит следующим образом:

$.ajaxTransport( function( options, originalOptions, jqXHR ) {
    if( /* проверяем может ли transport-объект обрабатывать указанный запрос */ ) {
        return {
            send: function( headers, completeCallback ) {
                //    код для обработчика send
            },
            abort: function() {
                //    код для обработчика abort
            }
        };
    }
});

где

  • options - параметры запроса
  • originalOptions - параметры предоставляемые методу, не измененные и без параметров ajaxSettings.
  • jqXHR - jqXHR-объект текущего запроса.
  • headers - JavaScript-объект (массив), для указания заголовков запроса, для передачи transport-объектом, если есть поддержка.
  • completeCallback - функция обратного вызова, используется для уведомления AJAX о завершении запроса.

completeCallback имеет следующий синтаксис:

function( status, statusText, responses, headers ) {}

где

  • status - статус HTTP-кода ответа, как например 200 для успешного запроса или 404 в случае, если ресурс не найден.
  • statusText - строка, параметр statusText из ответа.
  • responses - необязательный параметр, объект, содержащий dataType/value, который содержит ответ по всех форматах, который может обеспечить transport-объект (например, собственный XMLHttpRequest-объект будет установлен  в {xml: XMLData, text: textData} для ответа содержащий XML-документ)
  • headers - необязательный параметр, строка, содержащая все заголовки ответа, если transport имеет к ним доступ (схоже с XMLHttpRequest.getAllResponseHeaders())

Также как и префильтры, фабрику (factory) transport-объектов можно пиркрепить к конкретному типу данных (dataType):

$.ajaxTransport( "script", function( options, originalOptions, jqXHR ) {
    //    будет вызван только для запросов script
});

В следующем примере показана реализация минимальными средствами для типа данных image:

$.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;
                }
            }
        };
    }
});

Обработка пользовательских типов данных.

В реализация AJAX в jQuery имеется набор стандартных типов данных, таких как text, JSON, XML и HTML. Используйте параметр converters в jQuery.ajaxSetup(), чтобы дополнить или изменить метод обработки типа данных , используемых в jQuery.ajax().

Не минимизированный исходный код jQuery включает в себя список стандартных конвертеров (converters), которые иллюстрируют методы использования:

// Список преобразователей данных
// 1) формат ключа(key): "исходный_тип конечный тип"
// (разделенные одиночным пробелом)
// 2) Символ "*" может быть использован для исходного_типа, объединяя все типы данных
converters: {
    // Преобразование всего к text
    "* text": window.String,
    // Текст в html (true = без трансформации)
    "text html": true,
    // Рассматривает text как json
    "text json": jQuery.parseJSON,
    // Разбирает text как xml
    "text xml": jQuery.parseXML
}

Когда вы указываете параметр converters глобально в jQuery.ajaxSetup() или для каждого вызова jQuery.ajax(), объект будет вызываться конверторами по умолчанию, заменив те, которые переопределены и оставив остальные не тронутыми.

Например в исходниках jQuery используется jQeury.ajaxSetup(), что бы добавить конвертор "text script".

jQuery.ajaxSetup({
    accepts: {
        script: "text/javascript, application/javascript"
    },
    contents: {
        script: /javascript/
    },
    converters: {
        "text script": jQuery.globalEval
    }
});