Источник данных

Перед созданием слоя активных областей необходимо сформировать источник данных. Основная его задача — запрашивать у сервера данные нужного тайла.

API и сервер общаются между собой в формате JSONP. Это означает, что сервер должен оборачивать возвращаемые данные в callback-функцию, название которой источник указывает в параметре запроса.

Шаблон URL запросов, отправляемых источником, выглядит следующим образом:

'{URL данных тайла}?callback={jsonp-callback}',

где {URL данных тайла} — шаблон URL данных тайла (см. в разделе Описания активных областей), {jsonp-callback} — имя функции, в которую сервер должен обернуть ответ.

Для создания источника данных предназначен класс hotspot.ObjectSource. В конструкторе этого класса необходимо передать шаблон URL данных тайлов. Также можно указать дополнительные параметры:

  • шаблон имени jsonp-callback, в который сервер должен оборачивать возвращаемые данные нужного тайла. По этому шаблону источник будет формировать для каждого тайла название соответствующей функции и в запросе укажет это название в качестве параметра callback;
  • опции источника данных;
// Зададим шаблон URL, по которому будут доступны данные для тайла на сервере
var hotspotUrl = 'http://server.domain/%z/%x/%y', 
    // Зададим шаблон jsonp-callback
    myCallback = 'myCallback_%c', // вместо '%c' API выполнит подстановку 'x=`<`номер тайла по x`>`&y=`<`номер тайла по y`>`&z=`<`коэффициент масштабирования`>`'
    // Создадим источник тайлов
    objSource = new ymaps.hotspot.ObjectSource(hotspotUrl, myCallback, {
        noCash: true // не использовать кеш браузера 
    });

Тогда, например, URL запроса для тайла с номером [2,3] и z=4 будет выглядеть следующим образом:

http://server.domain/4/2/3?callback=myCallback_x_2_y_3_z_4.

Если при создании источника не задан шаблон имени jsonp-callback, то API будет автоматически генерировать новые названия этих функций каждый раз перед отправкой запроса. В этом случае сервер не будет знать заранее имени jsonp-callback. Поэтому на серверной стороне придется формировать ответ динамически, подставляя переданный jsonp-callback.

Если же параметр callback задан, то сервер будет оборачивать данные для одного тайла всегда в один и тот же jsonp-callback. Это может быть полезным по следующей причине.

Так как название jsonp-callback для тайла заранее известно, на сервере не придется писать скрипт, определяющий это название. Описание активных областей тайла можно сформировать сразу обернутыми в заданную функцию. Например, если шаблон названия jsonp-callback задан как 'myCallback_%c', то для тайла с номером [1,2] и z=5 на сервере можно создать файл данных:

myCallback_x_1_y_2_z_5({
    "data": {
        "type": "FeatureCollection",
        ...
    }
});

На основе полученных данных источник создает массив объектов (экземпляров класса hotspot.layer.Object), описывающих активные области. Эти объекты представляются в специальном формате, который является удобным для вычисления некоторых геометрических задач (например, определение попадания указателя мыши в активную область).

Источник возвращает слою массив преобразованных объектов. Если тайл не содержит активных областей, то источник возвращает пустой массив.

Стандартная реализация hotspot.ObjectSource предполагает, что источник будет запрашивать данные для любого тайла, на который переместился указатель (даже если активных областей там нет). Однако, бывают ситуации, когда можно заранее определить, в каких тайлах находятся активные области. Тогда источник можно перепрограммировать так, что он будет запрашивать данные только для этих тайлов.

О том, как можно переопределить стандартную реализацию hotspot.ObjectSource, можно посмотреть в справочнике.

Использование кэша браузера

Если URL каждого тайла будет оставаться неизменным, то браузер может запоминать в кэше загруженные данные для этих URL.

Если заранее известно, что данные на сервере меняться не будут, то можно жестко кэшировать данные браузером. При таком кэшировании все обращения к ранее загруженным данным будут напрямую обслуживаться из кэша браузера, без обращения к серверу. Для этого в выдаче ответа сервера необходимо указать заголовки Expires и Cache-Control.

Если данные тайлов обновляются часто (например, в пробках данные обновляются раз в несколько минут), то можно использовать обычное кэширование браузера. Для этого в ответе сервера необходимо указывать заголовок Etag.

Если же кэш браузера использовать не нужно, то следует задать опцию источника noCache со значением true (либо не задавать шаблон имени собственной callback-функции).