В этой главе мы уже рассмотрели некоторые функции jQuery и пример использования, который продемонстрировал, насколько упрощает жизнь разработчиков библиотека jQuery, благодаря которой отпадает потребность писать сопутствующий код, не относящийся непосредственно к решению задачи.

Здесь мы рассмотрим все функции и события Ajax, имеющиеся в библиотеке и составляющие API jQuery по работе с асинхронными запросами. В табл. 7.2 приведен список функций Ajax-подсистемы в jQuery.

Функции для работы с Ajax

jQuery.ajax

Функция предназначена для организации Ajax-запросов и представляет собой самый активный элемент jQuery API, но в то же время самый низкоуровневый. jQuery.ajax принимает один-единственный параметр — структуру данных, которая описывает все, что необходимо для организации асинхронного запроса. Структура данных может содержать следующие поля:

□ async — булево значение, определяющее, будет ли запрос асинхронным. По умолчанию async=true;

□ beforeSend — определяет функцию, которая будет вызвана перед отправкой асинхронного запроса. Этой функции передается единственный параметр текущий объект XMLHttpRequest;

□ cache — позволяет управлять кэшированием страниц, по умолчанию установлено cache=true;

□ complete — определяет функцию, которая вызывается в момент завершения запроса, в том числе в случае неудачного запроса. В функцию передается два параметра: текущий объект XMLHttpRequest и строка, которая указывает статус завершения запроса;

□ contentType — определяет строковое значение типа данных запроса (HTTP-заголовок content-type). По умолчанию значение устанавливается в application/x-www-form-urlencoded;

□ data — данные, представленные объектом или строкой, которые должны быть отправлены на сервер вместе с запросом;

□ dataFilter — определяет функцию, которая вызывается для полученных в результате запроса данных. Подразумевается, что данная функция проведет проверку данных и приведет их в безопасный для использования на стороне клиента вид. Функция принимает два параметра: собственно принятые с сервера данные и строковое значение типа данных;

□ dataType — строка, определяющая тип данных, который ожидается в результате запроса. В зависимости от некоторых условий по умолчанию значение этого параметра устанавливается в "xml" или "html";

□ error — определяет функцию, которая будет вызвана в случае возникновения какой-либо ошибки при выполнении асинхронного запроса. Функция принимает три параметра: текущий объект XMLHttpRequest, строку с описанием типа ошибки и опциональный объект с описанием исключения, если оно было вызвано;

□ global — булево значение, которое определяет, должно ли выполнение этого запроса быть глобальным, что приводит к реагированию на него функций, или вызов не должен вызывать глобальные события. По умолчанию global=true;

□ ifModified — булево значение, которое указывает, что запрос должен считаться только тогда, когда возвращенные данные отличаются с момента прошлого запроса. По умолчанию ifModified=false;

□ password — строка, содержащая пароль, который будет использован в случае, когда производится запрос с обязательной аутентификацией;

□ processData — булево значение, которое определяет, необходимо ли производить обработку отправляемых данных из объектного представления в строковое. По умолчанию установлено processData=true;

□ success — определяет функцию, которая будет вызвана в случае, если запрос успешно завершится. Функция принимает два параметра: объект, содержащий полученные от сервера данные, и строковое значение, указывающее статус результата запроса;

□ timeout — числовое значение, которое определяет время ожидания ответа от сервера, по истечении которого запрос будет считаться завершившимся с ошибкой;

□ type — строка, определяющая типа запроса (GET или POST), по умолчанию type="GET";

□ url — строка, определяющая адрес, к которому отправляется запрос. По умолчанию подразумевается текущая страница;

□ username — строка, определяющая имя пользователя, которое будет использовано в случае, когда производится запрос с обязательной аутентификацией;

□ xhr — определяет функцию, которая должна создавать объект XMLHttpRequest. По умолчанию функция создает такой объект через ActiveXObject, если это возможно, если нет, то используется объект XMLHttpRequest. Вы можете переопределить эту функцию для собственной реализации создания объекта XMLHttpRequest.

Как можно заметить, функция jQuery.ajax обладает очень большим количеством настроек. Однако, в связи с тем, что практически все они имеют значения по умолчанию, использование jQuery.ajax не представляет собой особой сложности. Так, далее представлен вариант запроса значения даты и времени с сервера с помощью jQuery.ajax:

<script type="text/javascript">

  function GetTime() {

    $.ajax({

      url: 'Home/GetTime',

      success: function(result) {

        $('#timeText').text('Bpeмя на сервере: ' + result);

      },

      dataType: 'text'

    });

  }

</script>

При всем перечисленном количестве возможных параметров для функции jQuery.ajax использование ее не вызывает труда. Достаточно указать всего лишь три параметра: адрес, обработчик результата и ожидаемый тип результата. Этого достаточно в нашем случае для простейшего асинхронного запроса.

load

Данная функция применяется для уже готового результата селектора jQuery и предназначена для того, чтобы запросить с сервера HTML-код и внедрить его в выбранные ранее объекты. Функция содержит три параметра:

□ url — строка адреса для запроса на сервер. Данная строка может содержать любой допустимый селектор для фильтрации результатов запроса. Например, строка "Home/GetTime span.timeData" отправит запрос по адресу Home/GetTime, но результат запроса будет отфильтрован — из него будет выбран элемент (или элементы) span с CSS-классом timeData;

□ data (необязательно) — параметры запроса, которые следует отправить на сервер. Параметры могут быть представлены в двух видах. В первом случае, когда параметр представлен в виде строки, формируется GET-запрос. Во втором случае, когда параметры представлены в виде объектов и пар "ключ/значение", формируется POST-запрос;

□ callback (необязательно) — определяет функцию, которая будет вызвана после завершения запроса, удачного либо нет. Функция содержит три параметра: текст ответа, тип данных ответа и объект XMLHttpRequest.

Следующий пример загрузит значение времени в элемент с индентификатором timeText:

<script type="text/javascript">

  function GetTime() {

    $('#timeText').load('Home/GetTime');

  }

</script>

Как можно убедиться, асинхронный запрос и изменение значения элемента HTML-разметки уместилось всего в одной строке. Это крайне удобно в ряде случаев.

jQuery.get и jQuery.post

Данные функции являются упрощенными и более высокоуровневыми вариантами функции jQuery.ajax. Каждая из функций принимает четыре параметра:

□ url — строка адреса для запроса на сервер;

□ data (необязательно) — данные для отправления на сервер;

□ callback (необязательно) — определяет функцию, которая вызывается после завершения выполнения асинхронной операции;

□ type (необязательно) — строка, определяющая тип ожидаемых данных с сервера. Может принимать одно из следующих значений: "xml", "html", "script","json", "jsonp" или "text".

Применение этих функций вместо более комплексной jQuery.ajax оправдано в большинстве случаев. Различие между jQuery.get и jQuery.post только одно: первая выполняет GET-запрос, вторая — POST.

jQuery. getJSON

Функция jQuery.getJSON предназначена для упрощения работы с данными в формате JSON и получения их через Ajax. jQuery.getJSON поддерживает также работу с JSONP. Функция содержит три знакомых нам параметра:

□ url — строка адреса для запроса на сервер. Для сайтов, которые поддерживают JSONP, в этом параметре можно указать параметр callback=?, чтобы иметь возможность обратиться с Ajax-запросом к домену, отличному от текущего домена сервера;

□ data (необязательно) — параметры, которые необходимо отправить на сервер;

□ callback (необязательно) — определяет функцию, которая должна быть вызвана после завершения запроса.

Использование jQuery.getJSON оправдано в случаях, когда реализуется взаимодействие с сервером, в котором достоверно известно, что обмен данными будет производиться только на базе формата JSON.

jQuery.getScript

Функция jQuery.getScript предназначена для асинхронных запросов, результатами которых являются JavaScript-фрагменты кода. После получения такого фрагмента jQuery.getScript выполняет полученный код. Функция содержит всего два параметра:

□ url — строка адреса для запроса на сервер;

□ callback (необязательно) — определяет функцию, которая должна быть вызвана после завершения запроса, загрузки и выполнения JavaScript-фрагмента.

Использование jQuery.getScript не является самым распространенным вариантом асинхронных запросов. Однако эта функция может быть полезна в тех случаях, когда требуется динамически подгружать JavaScript-функционал.

jQuery. ajaxSetup

Функция jQuery.ajaxSetup не является функцией, которая взаимодействует с сервером или занимается посылкой данных. Вместо этого jQuery.ajaxSetup предназначена для инициализации параметров, используемых по умолчанию при вызовах jQuery.ajax. Функция принимает только один параметр: options — структура данных, которая описывает все, что необходимо для организации асинхронного запроса. Возможные параметры структуры и их значения описаны вместе с описанием функции jQuery.ajax.

Например, чтобы изменить поведение по умолчанию для jQuery.ajax, чтобы вместо GET-запросов по умолчанию производились POST-запросы, необходимо вызвать следующий код:

$.ajaxSetup({ type: "POST" });

После этого все вызовы jQuery.ajax по умолчанию будут создавать POST-запросы. jQuery.ajaxSetup крайне полезна для инициализации сценария клиентской страницы, когда вместо того, чтобы передавать однотипные параметры с каждым вызовом jQuery.ajax, вы определяете их как значения по умолчанию.

События Ajax в jQuery

Помимо функций, работающих с Ajax, в библиотеке jQuery существует ряд функций, добавляющих обработчиков к событиям, которые также относятся к сфере Ajax и вызываются в тот или иной момент работы Ajax-запросов:

□ ajaxComplete — событие, возникающее в момент завершения Ajax-запроса. Результат завершения не влияет на возникновение события. ajaxComplete будет вызвано в любом случае: был ли запрос успешен, произошла ли ошибка, исключительная ситуация или время ожидания ответа от сервера истекло;

□ ajaxError — событие, возникающее в момент завершения Ajax-запроса с ошибкой. Событие ajaxError позволяет обработать исключительную ситуацию, возникшую при выполнении запроса на сервере, или другие ситуации, когда запрос не был успешно выполнен;

□ ajaxSend — событие, возникающее непосредственно перед отправкой запроса на сервер. Событие ajaxSend часто используется для изменения состояния пользовательского интерфейса, например, для запрещения элементов, с помощью которых может быть отправлен повторный запрос. Кроме того, разработчик может использовать событие ajaxSend для отображения сообщения для пользователя о том, что запрос был отправлен на сервер;

□ ajaxstart и ajaxstop — однотипные события, которые возникают в момент старта и остановки Ajax-запросов соответственно. Могут быть использованы точно так же, как ajaxsend или ajaxComplete, однако отличаются от них отсутствием параметров с дополнительными данными;

□ ajaxSuccess — событие, возникающее в момент успешного завершения Ajax-запроса. Если Ajax-запрос был выполнен успешно и были получены данные от сервера, то вызывается событие ajaxSuccess, обработав которое разработчик может отреагировать на успешный асинхронный запрос.

Все эти события могут быть обработаны пользовательскими функциями, в которые передается от одного до четырех параметров. Не принимают параметры только функции, обрабатывающие события ajaxstart и ajaxstop. Следующие параметры используются во всех остальных функциях:

□ event — объект, содержащий информацию о событии;

□ XMLHttpRequest — объект, содержащий информацию о запросе;

□ ajaxOptions — параметры, которые были использованы для запроса.

Событие ajaxError, кроме перечисленных трех, содержит четвертый параметр:

□ thrownError — объект, который содержит информацию о произошедшей ошибке.

Использовать данные события достаточно просто. Рассмотрим пример, который выводит пользователю сообщение о старте Ajax-запроса, скрывает кнопку, для предотвращения повторного запроса, и возвращает ее после того, как запрос выполнился. Для этого модифицируем код функции GetTime и разметку так, как представлено в следующем фрагменте:

<script type="text/javascript">

  function GetTime() {

    $('#requestStatus').ajaxStart(function() {

      $(this).text('Запрос запушен...');

      $('#ajaxSend').hide();

    });

    $('#requestStatus').ajaxStop(function() {

      $(this).text('Запрос завершен...');

      $('#ajaxSend').show();

    });

    $.get('Home/GetTime',

      null,

      function(result) {

        $('#timeText').text('Bpeмя на сервере: ' + result);

    });

  }

</script>

<span id="requestStatus">Нажмите кнопку для 3anpoca</span><br/>

<input id="ajaxSend"

       type="button"

       onclick="javascript:GetTime()"

       value="Получить время" />

<span id="timeText">Время не получено</span>

Здесь представлена разметка для элемента requestStatus с отображением статуса Ajax-запроса, кнопки ajaxSend и элемента timeText для отображения результата запроса. В JavaScript-коде определены две функции для обработки ajaxStart и ajaxStop, которые отображают статус текущего состояния запроса и скрывают или показывают кнопку в зависимости от состояния. Для более явной демонстрации действия событий jQuery добавим в функцию GetTime контроллера HomeController задержку выполнения, чтобы увидеть, как изменяется сообщение о статусе запроса:

[OutputCache(NoStore = true, Duration = 0, VaryByParam = "*")]

public ActionResult GetTime()

{

  Thread.Sleep(1000);

  return Json(DateTime.Now.ToString());

}

Теперь, если пользователь нажмет кнопку Получить время, состояние запроса будет выведено в специальном поле (рис. 7.6). После получения результата поле состояния соответственно изменится (рис. 7.7).

Мы рассмотрели jQuery API, которое позволяет значительно упростить работу с Ajax-запросами как в целом, так и для частых практических ситуаций. Как мы убедились, некоторые варианты использования Ajax в jQuery могут состоять всего из одной строки текста. В следующей части главы мы рассмотрим применение jQuery более подробно.