Documentation
Reference
2.1.55 (current version)
collection
interactivityModel
Interfaces

hotspot.ObjectSource

Extends IHotspotObjectSource.

The standard implementation of the IHotspotObjectSource interface. Works with the standard format of the server response.

Constructor | Fields | Events | Methods

Constructor

hotspot.ObjectSource(tileUrlTemplate[, keyTemplate[, options]])

Returns the data source for the hotspot layer.

Parameters:

ParameterDefault valueDescription
tileUrlTemplate *
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: String|Function

Template for the URL of the data for the tile. Supports special constructions and the use of functions similar to Layer.

keyTemplate

Type: String|Function

Template for the tile ID. Used for creating padding in the jsonp request for data. Set in the same way as the previous parameter. All characters other than letters, numbers, and the "_" symbol will be replaced with "_". If this parameter is omitted, the request's padding will be generated automatically. Conversion examples for tileNumber=[3, 1], zoom=9:

  • 'myCallback=%x' => 'myCallback_3'
  • '%c' => 'x_3_y_1_z_9'
  • 'callback2_%c' => 'callback2_x_3_y_1_z_9'
  • 'callback%test' => 'callback_test'

options

Type: Object

Options for the data source.

options.bounds null

Type: Bounds

The area on the map that has data, or null if there is data everywhere. Option for the standard implementation of the "restrict" method.

options.maxZoom 0

Type: Bounds

The maximum zoom level to make data requests for. Option for the standard implementation of the "restrict" method.

options.minZoom 0

Type: Bounds

The minimum zoom level to make data requests for. Option for the standard implementation of the "restrict" method.

options.noCache false

Type: Boolean

false - Use the built-in browser cache; true - don't use it (each URL will have a random GET parameter appended automatically in order to prevent the browser from caching tiles).

* Mandatory parameter/option.

Example:

// Example of the standard format of the server response
hotspot_callback({
    // the response can contain the "data" or "error" field.
    "data": {
        "type": "FeatureCollection",
        // Array of hotspot objects.
        "features": [{
            "type": "Feature",
            // Object data.
            // Passes the constructor hotspot.layer.Object as data
            "properties": {
                "hintContent": "Content of the text hint.",
                "balloonContentBody": "Balloon content.",
                "balloonContentHeader": "Balloon title.",
                "balloonContentFooter": "Lower part of the balloon.",
                // You can set the balloonContent property instead of Body/Header/Footer

                // Required field that describes hotspot.layer.Object.
                "HotspotMetaData": {
                    // ID of the hotspot object.
                    // hotspot.layer.Object.getId returns the value of this field by default.
                    "id": 10469893,
                    "zIndex": 10,
                    // Data used for creating the geometry of hotspot.layer.Object.
                    // Required field.
                    // The standard implementation allows you to pass the following types of geometries:
                    //    "Rectangle" - a rectangle.
                    //      Creates the geometry.pixel.Rectangle geometry.
                    //    "Polygon" - a multi-contour polygon.
                    //      Creates the geometry.pixel.Polygon geometry.
                    //    "MultiPolygon" - a complex shape made up of multiple multi-contour polygons.
                    //      Creates the geometry.pixel.MultiPolygon geometry.
                    //    "ConvexPolygon" - a multi-contour polygon. All the contours should be convex.
                    //       It works faster than "Polygon".
                    //       Creates the geometry.pixel.Polygon geometry.
                    //    "MultiConvexPolygon" - a complex shape made up of multiple multi-contour polygons.
                    //      All the contour should be convex. It works faster than "MultiPolygon".
                    //      Creates the geometry.pixel.MultiPolygon geometry.
                    "RenderedGeometry": {
                        "type": "Polygon",
                        // Coordinates are passed in pixel coordinates that are calculated from the upper-left corner of the tile.
                        "coordinates": [
                            // The first contour of the polygon.
                            [
                                [-315, 280], [32, 442], [141, 208], [-206, 46], [-315, 280]
                            ],
                            // The second contour of the polygon.
                            [
                                [-186, 155], [-238, 265], [-152, 306], [-100, 196], [-186, 155]
                            ]
                        ]
                    }
                }
            },
            // The object's actual geometry.
            // Optional field.
            // Passed to hotspot.layer.Object and available via the hotspot.layer.Object.getGeometry method.
            "geometry": {
                "type": "Polygon",
                "coordinates": [
                    // The first contour of the polygon.
                    [
                        [29.176096525, 40.904183940],
                        [29.177027467, 40.903854324],
                        [29.177319900, 40.904329679],
                        [29.176389040, 40.904659406],
                        [29.176096525, 40.904183940]
                    ],
                    // The second contour of the polygon.
                    [
                        [29.176442530, 40.904437683],
                        [29.176303055, 40.904213830],
                        [29.176533525, 40.904131168],
                        [29.176673032, 40.904355010],
                        [29.176442530, 40.904437683]
                    ]
                ]
            }
        },
        {
            "type": "Feature",
            "properties": {
                // description of the next hotspot object...
            }
        }]
    }
});

Fields

NameTypeDescription
eventsIEventManager

Event manager.

Inherited from IEventEmitter.

optionsIOptionManager

Options manager.

Inherited from ICustomizable.

Events

NameDescription
optionschange

Change to the object options.

Inherited from ICustomizable.

Methods

NameReturnsDescription
cancelLastRequest()

Cancels the last request for data.

Inherited from IHotspotObjectSource.

getKey(tileNumber, zoom)

String

Returns the name of the callback function (padding) in the jsonp request if it is static, or null if a dynamic jsonp callback can be used. Templates support the same substitutions as in the template for the tile URL. All characters other than letters, numbers, and the "_" symbol will be replaced with "_".

getKeyTemplate()

String

Returns template for the tile ID.

getTileUrl(tileNumber, zoom)

String

Returns the URL of data for a specific tile.

getTileUrlTemplate()

String

Returns template for the URL for tile data.

parseResponse(layer, res, callback, tileNumber, zoom)

Parses the server response. Sends the callback an array of hotspot objects generated using the json description.

requestObjects(layer, tileNumber, zoom, callback)

Builds an array of IHotspotLayerObject objects corresponding to a particular layer, tile, and map zoom level, and passes it to the callback function.

Inherited from IHotspotObjectSource.

restrict(layer, tileNumber, zoom)

Boolean

Method that is called before sending a request for tile data. If the method returns true, the request will not be sent to the server, and an empty array of objects will be returned as the response. The standard implementation of the method checks whether the "zoom" parameter is within the limits of [options.minZoom, options.maxZoom]. It also checks whether the center of the requested tile falls within the specified options.bounds. If options.bounds=null, this parameter is not checked.

setKeyTemplate(template)

Sets a new tile ID template.

setTileUrlTemplate(template)

Sets a new template for the tile data URL.

Methods details

getKey

{String} getKey(tileNumber, zoom)

Returns the name of the callback function (padding) in the jsonp request if it is static, or null if a dynamic jsonp callback can be used. Templates support the same substitutions as in the template for the tile URL. All characters other than letters, numbers, and the "_" symbol will be replaced with "_".

Returns tile ID. Used when creating padding in the jsonp request for data.

Parameters:

ParameterDefault valueDescription
tileNumber*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Number[]

Tile number (tile coordinates).

zoom*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Integer

Zoom level.

* Mandatory parameter/option.

getKeyTemplate

{String} getKeyTemplate()

Returns template for the tile ID.

getTileUrl

{String} getTileUrl(tileNumber, zoom)

Returns the URL of data for a specific tile.

Parameters:

ParameterDefault valueDescription
tileNumber*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Number[]

Tile number (tile coordinates).

zoom*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Integer

Zoom level.

* Mandatory parameter/option.

Example:

var hotspotObjectSource = new ymaps.hotspot.ObjectSource('dataSource/?%c');
hotspotObjectSource.getTileUrl = function (tileNumber, zoom) {
    if (zoom > 10) {
        // For large scales, use the provided data path.
        return ymaps.hotspot.ObjectSource.prototype.call(this, tileNumber, zoom);
     } else {
        // For small scales, use a different path.
        return 'otherSource/getHotspots.xml?z=' + zoom + '<codeph>&</codeph>x=' + tileNumber[0] + '<codeph>&</codeph>y=' + tileNumber[1]';
     }
};

getTileUrlTemplate

{String} getTileUrlTemplate()

Returns template for the URL for tile data.

parseResponse

{} parseResponse(layer, res, callback, tileNumber, zoom)

Parses the server response. Sends the callback an array of hotspot objects generated using the json description.

Parameters:

ParameterDefault valueDescription
layer*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: hotspot.Layer

The layer that the objects belong to.

res*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Object

Server response.

callback*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Function

Handler function.

tileNumber*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Number[]

Number of the tile that the response is for.

zoom*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Number

The zoom level that the response is for; array of objects.

* Mandatory parameter/option.

restrict

{Boolean} restrict(layer, tileNumber, zoom)

Method that is called before sending a request for tile data. If the method returns true, the request will not be sent to the server, and an empty array of objects will be returned as the response. The standard implementation of the method checks whether the "zoom" parameter is within the limits of [options.minZoom, options.maxZoom]. It also checks whether the center of the requested tile falls within the specified options.bounds. If options.bounds=null, this parameter is not checked.

Returns true if the tile extends beyond the boundaries of the data area (there is no data for this tile), or false if it does not (there is data).

Parameters:

ParameterDefault valueDescription
layer*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: hotspot.Layer

Hotspot layer.

tileNumber*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Number[]

Tile number.

zoom*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Integer

Zoom level.

* Mandatory parameter/option.

Example:

// Example of redefining the "restrict" method
// Let's assume there is only data for Murmansk and Novosibirsk.
var myMap = new ymaps.Map('map', {center: [32.5, 68.9] , zoom: 9}),
    geoBounds = [
         [[31.729958, 69.369182], [34.203324, 68.666473]], // Murmansk
         [[82.179084, 55.341085], [83.725642, 54.670738]]  // Novosibirsk
    ],
    projection = myMap.options.get('projection');

var myHotspotSource = new ymaps.hotspot.ObjectSource('http://www.myDomain.ru/tiles/?%c', '%c');

myHotspotSource.restrict = function(layer, tileNumber, zoom) {

   // Calculating the pixel boundaries of the cities for this zoom level.
   var boundsFromPoints = ymaps.util.bounds.fromPoints,
       toGlobalPixels = projection.toGlobalPixels,
       pixelBounds = [
           boundsFromPoints(
               toGlobalPixels(geoBounds[0][0]], zoom),
               toGlobalPixels(geoBounds[0][1]], zoom)
           ),
           boundsFromPoints(
               toGlobalPixels(geoBounds[1][0]], zoom),
               toGlobalPixels(geoBounds[1][1]], zoom)
           )
      ],

       // Calculating the pixel boundaries of the tile
       leftTop = [tileNumber[0] * 256, tileNumber[1] * 256],
       tileBounds = [leftTop, [leftTop[0] + 256, leftTop[1] + 256]],
       intersects = ymaps.util.bounds.intersects;
   // If the tile's pixel boundaries intersect with the pixel boundaries of the specified areas,
   // we have to send a request for data
   if (intersects(pixelBounds[0], tileBounds) || (intersects(pixelBounds[1], tileBounds)) {
         return false;
  }

   // For all the other tiles, this source doesn't have any data.
   return true;
}

setKeyTemplate

{} setKeyTemplate(template)

Sets a new tile ID template.

Parameters:

ParameterDefault valueDescription
template*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: String

Template for the ID.

* Mandatory parameter/option.

setTileUrlTemplate

{} setTileUrlTemplate(template)

Sets a new template for the tile data URL.

Parameters:

ParameterDefault valueDescription
template*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: String

URL template

* Mandatory parameter/option.