AJAX-запросы

Введение

В данной статье изучим, какие возможности работы с AJAX встроено API карт 2ГИС.

Основы

Операции с AJAX в общем случае можно выполнять с помощью фреймворка jQuery или других.

Но в ряде случаев можно обойтись без них. В этом нам поможет свойство карты myMap.ajax, которое хранит экземпляр класса DG.MapAjaxManager. Вручную создавать объект класса DG.MapAjaxManager не нужно.

В качестве формата мы используем JSONP. Благодаря этому можно делать кросс-доменные AJAX-запросы, но с ограничением — только GET-запросы.

Также есть методы для групповых операций с AJAX-запросами.

Класс DG.MapAjaxManager

Ниже мы подробно рассмотрим все методы класса DG.MapAjaxManager. Для наглядности допустим, что myMap — объект карты.

Описание методов представляет собой действие (что делает метод, для чего он нужен?) и название метода. Вместе с тем, представлены дополнительно параметры, возвращаемое значение метода и особенности, если таковые имеются.

Методы

Отправить AJAX-запрос
myMap.ajax.get(options)

Параметры:

Имя Тип Обязательный Описание
options.url String Да URL, на который будет выполняться AJAX-запрос. Сервер должен поддерживать JSONP-протокол.
options.data Object Нет Данные, которые нужно передать.
options.success Function Нет Функция-обработчик, вызываемая при успешном выполнении запроса. Функция принимает один параметр — ответ сервера.
options.failture Function Нет Функция-обработчик, вызываемая в случае ошибки. Функция принимает один параметр — ответ сервера.
options.scope Object Нет Контекст выполнения callback-функций options.success и options.failture. Другими словами, что будет скрываться за ключевым словом this внутри callback-функций.

Возвращает:

Тип Описание
String Уникальный идентификатор AJAX-запроса, который автоматически создается в процессе выполнения данного метода.

Пример запроса на сторонний сервис:

// Инициализация карты
var myMap = new DG.Map('map1');
myMap.setCenter(new DG.GeoPoint(82.927810142519, 55.028936234826), 15);

// Отправка асинхронного запроса на сторонний сервис
var cid1 = myMap.ajax.get({
    url: 'http://www.geonames.org/postalCodeLookupJSON?callback=$[callback]',
    data: {
        postalcode: 10504,
        country: 'US'
    },
    success: function (response){
        var postalCode = response.postalcodes[0];
        alert('Почтовый индекс: ' + postalCode.postalcode + ', широта/долгота: ' + postalCode.lng + '/' + postalCode.lat);
    },
    failture: function (){
        alert('При отправке запроса возникла ошибка!');
    },
    scope: this
 });
Добавить AJAX-запрос в группу
myMap.ajax.addCallbackToGroup(cid, gid)

Параметры:

Имя Тип Обязательный Описание
cid String Да Идентификатор AJAX-запроса, который был получен в процессе выполнения метода myMap.ajax.get.
gid String Да Идентификатор группы. Если для указанной группы вызываем данный метод первый раз, создается группа с указанным идентификатором gid. В неё добавляется cid. При последующих вызовах идентификаторы AJAX-запросов просто добавляются в указанную группу.

Пример:

myMap.ajax.addCallbackToGroup(cid1, 'myGroup1'); // Где cid1 - идентификатор AJAX-запроса
Отключить обработчик определенного AJAX-запроса
myMap.ajax.cancelCallback(cid)

Параметры:

Имя Тип Обязательный Описание
cid String Да Идентификатор AJAX-запроса.

Пример:

myMap.ajax.cancelCallback(cid1); // Где cid1 - идентификатор AJAX-запрос

Вызов данного метода приводит к тому, что success и failture обработчики не будут вызваны после завершения заданного AJAX-запроса.

Отменить всех обработчиков группы AJAX-запросов
myMap.ajax.cancelCallbacksByGroup(gid)

Параметры:

Имя Тип Обязательный Описание
gid String Да Идентификатор группы.

Пример:

myMap.ajax.cancelCallbacksByGroup('myGroup1');

Вызов данного метода приводит к тому, что success и failture обработчики не будут вызваны после завершения всех AJAX-запросов из указанной группы.

Отмена всех обработчиков карты
myMap.ajax.cancelAllCallbacks()

Пример:

myMap.ajax.cancelAllCallbacks();

Вызов данного метода приводит к тому, что success и failture обработчики не будут вызваны после завершения всех AJAX-запросов на карте.