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:

Parameter

Default value

Description

tileUrlTemplate*

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 contours 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

Name

Type

Description

events

IEventManager

Event manager.

Inherited from IEventEmitter.

options

IOptionManager

Options manager.

Inherited from ICustomizable.

Events

Name

Description

optionschange

Change to the object options.

Inherited from ICustomizable.

Methods

Name

Returns

Description

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:

Parameter

Default value

Description

tileNumber*

Type: Number[]

Tile number (tile coordinates).

zoom*

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:

Parameter

Default value

Description

tileNumber*

Type: Number[]

Tile number (tile coordinates).

zoom*

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:

Parameter

Default value

Description

layer*

Type: hotspot.Layer

The layer that the objects belong to.

res*

Type: Object

Server response.

callback*

Type: Function

Handler function.

tileNumber*

Type: Number[]

Number of the tile that the response is for.

zoom*

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:

Parameter

Default value

Description

layer*

Type: hotspot.Layer

Hotspot layer.

tileNumber*

Type: Number[]

Tile number.

zoom*

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});
var geoBounds = [
    [[31.729958, 69.369182], [34.203324, 68.666473]], // Murmansk
    [[82.179084, 55.341085], [83.725642, 54.670738]]  // Novosibirsk
];
var 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;
    var toGlobalPixels = projection.toGlobalPixels;
    var 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
    var leftTop = [tileNumber[0] * 256, tileNumber[1] * 256];
    var tileBounds = [leftTop, [leftTop[0] + 256, leftTop[1] + 256]];
    var 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:

Parameter

Default value

Description

template*

Type: String

Template for the ID.

* Mandatory parameter/option.

setTileUrlTemplate

{} setTileUrlTemplate(template)

Sets a new template for the tile data URL.

Parameters:

Parameter

Default value

Description

template*

Type: String

URL template

* Mandatory parameter/option.