Data source

Before the hotspot layer can be created, the data source must be generated. Its main purpose is to request data for the necessary tile from the server.

The API and the server interact in JSONP format. This means that the server must wrap the data being returned in a callback function; the data source specifies the name of this function in the request parameter.

The template for the URL of requests sent by the data source looks like this:

'{tile data URL}?callback={jsonp-callback}',

where {tile data URL} is the template for the URL of the tile data (see section Hotspot descriptions), and {jsonp-callback} is the name of the function that the server should wrap the response in.

Use the hotspot.ObjectSource class to create the data source. The template of the URL for the tile data must be passed in the constructor for this class. You may also specify additional parameters:

  • A template for jsonp-callback names that the server should use to wrap the data being returned for the necessary tile. Using this template, the data source will generate the name of the corresponding function for each tile and specify this name in the request as the callback parameter.
  • Data source options.
// Setting the template for the URL that will be used for accessing data for the tile on the server
var hotspotUrl = 'http://server.domain/%z/%x/%y', 
    // Setting the jsonp-callback template
    myCallback = 'myCallback_%c', // instead of '%c' the API will substitute 'x=`<`tile number on the x-axis`>`&y=`<`tile number on the y-axis`>`&z=`<`zoom level`>`'
    // Creating the tile source
    objSource = **new ymaps.hotspot.ObjectSource**(hotspotUrl, myCallback, {
        noCash: true // do not use the browser cache 
    });

Then, for example, the URL of the request for a tile numbered [2,3] with z=4 will look like this:

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

If a template for jsonp-callback names is not set when creating the data source, the API will automatically generate new names for these functions each time before sending the request. In this case, the server will not know beforehand what the jsonp-callback names are. The response will have to be generated dynamically on the server side, substituting the passed jsonp-callback.

If the callback parameter is set, the server will always wrap the data for a single tile in the same jsonp-callback. This can be useful for the following reason.

Since the jsonp-callback name for the tile is known beforehand, it will not be necessary to write a script defining this name on the server. The description of tile hotspots can be generated immediately, wrapped in the specified function. For example, if the template for jsonp-callback names is set as 'myCallback_%c', for the tile with the number [1,2] and z=5 this data file can be created on the server:

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

Based on the data received, the data source creates an array of objects (instances of the hotspot.layer.Object class) describing hotspots. These objects are provided in a special format that is convenient for calculating certain geometric tasks (such as determining when the mouse pointer falls on a hotspot).

The data source returns an array of converted objects to the layer. If the tile does not contain hotspots, the data source returns an empty array.

The standard implementation of hotspot.ObjectSource assumes that the data source will request data for any tile that the cursor moved to (even if there are not any hotspots there). However, there are situations when it can be determined beforehand which tiles have hotspots. Then the data source can be re-programmed to request data only for these tiles.

For information about how to redefine the standard implementation of hotspot.ObjectSource, see the Reference.

Using the browser cache

If the URL of each tile will remain constant, the browser can keep downloaded data for these URLs in the cache.

If it is known beforehand that the data on the server will not change, the browser can be used to "hard cache" the data. When using this type of caching, all accesses to data that was downloaded earlier will be served directly from the browser cache, without accessing the server. To do this, the server response output must specify the Expires and Cache-Control headers.

If the tile data is updated frequently (for example, traffic data is updated once every few minutes), normal browser caching can be used. To do this, the server response must specify the Etag header.

If the browser cache does not need to be used, you should set the data source optionnoCache with the value true (or do not set the template for names of the callback function).