Documentation
Reference
2.1.50 (current version)
collection
interactivityModel
Interfaces

RemoteObjectManager

Extends ICustomizable, IEventEmitter, IGeoObject, IParentOnMap.

The object manager that optimizes downloading of objects from the server. The manager sends data requests to the specified url in the JSONP format. This format corresponds to the format of objects added to ObjectManager, ObjectManager.add. Objects of type "Cluster" with the following fields are also supported:

  • type - The object type, always "Cluster" for clusters.
  • id - Unique cluster ID.
  • geometry - The cluster geometry in JSON format.
  • features - An array of cluster objects. Optional field.
  • bbox - An array of coordinates describing a rectangular area that includes all the cluster objects.
  • number - Number of objects in the cluster.
  • properties - Cluster data.
This module is designed for downloading and displaying the data which was previously processed on the server. Particularly, it is recommended to use the module for displaying results of server-side clustering. Data is requested again if the map zoom level is changed. The module does not provide clustering or filtering possibilities for managing visibility on the client side. To cluster objects on the client side after loading, use LoadingObjectManager. Note that objects drawn on the map via this manager can't have editing and dragging modes enabled.

Constructor | Fields | Events | Methods

Constructor

RemoteObjectManager(urlTemplate[, options])

Parameters:

ParameterDefault valueDescription
urlTemplate *
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: String

URL data template. Supports special constructions similar to Layer. Substitutions are also supported:

  • %b is replaced by an array of geographic coordinates that describes the rectangular region for which you want to load data.
  • %t is replaced by an array of tile numbers that describes the rectangular region to load data for.

options

Type: Object

Options.

  • You can set all the options specified in the Clusterer description, except for hasBalloon and hasHint options.
  • Cluster options are set with the "cluster" prefix. The list of options is specified in the description of ClusterPlacemark;
  • Options for singular objects should be specified with the geoObject prefix. The list of options is specified in Placemark.

options.paddingParamName 'callback'

Type: Boolean

Name of the GET parameter that contains the value of the JSONP callback.

options.paddingTemplate null

Type: String

Template for a jsonp callback. Supports the same substitutions as urlTemplate. All characters other than letters and numbers will be replaced with '_'. If the parameter is omitted, the name of the jsonp callback 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'
  • 'callback_%b' => 'callback_85_0841__180_0000_85_0841_180_0000'
Note that if substitution options are not used in the value, this may lead to an error. All requests will go to the same callback function.

options.splitRequests false

Type: Boolean

Divide requests for data into requests for individual tiles. By default, requests are made for data for a rectangular region that contains multiple tiles.

options.syncOverlayInit false

Type: Boolean

A flag that allows creating overlays for objects synchronously. Note that when you create an overlay synchronously, you should ensure that the appropriate class, which implements the IOverlay interface, is loaded. By default, the overlays are created asynchronously, and the overlay class is loaded on demand.

* Mandatory parameter/option.

Examples:

1.

var objectManager = new ymaps.RemoteObjectManager('http://myServer.com/tile?bbox=%b', {
    // Cluster options are set with the "cluster" prefix.
    clusterHasBalloon: false,
    // Geo object options are set with the "geoObject" prefix.
    geoObjectOpenBalloonOnClick: false
});

// You can set options directly for child collections.
objectManager.clusters.set({
    preset: 'islands#grayClusterIcons',
    hintContentLayout: ymaps.templateLayoutFactory.createClass('Group of objects')
});
objectManager.objects.set('preset', 'islands#grayIcon');

2.

An example of RemoteObjectManager response
jsonp_callback({
    // The response contains the error and data fields. If an error occurs, the "error" field
    // contains the error code or description.
    error: null,
    data: {
        type: 'FeatureCollection',
        features: [
             {
                 type: 'Feature',
                 geometry: {
                     type: 'Point',
                     coordinates: [55, 35]
                 },
                 id: 23,
                 properties: {
                     balloonContent: 'Placemark balloon content',
                     iconContent: 'Placemark content'
                 },
                 options: {
                     preset: 'islands#yellowIcon'
                 }
             },
             {
                 type: 'Cluster',
                 id: 24,
                 bbox: [[35, 46], [46, 57]],
                 number: 34,
                 // Array describing the 34 objects in the cluster.
                 // Optional field.
                 // If omitted, an empty balloon opens when the cluster is clicked.
                 features: [{
                     type: 'Feature',
                     id: 512,
                     properties: {
                         balloonContent: 'Placemark balloon content',
                         clusterCaption: 'Placemark title in the cluster balloon'
                     },
                     ...
                 ],
                 geometry: {
                     type: 'Point',
                     coordinates: [40.5, 51]
                 },
                 properties: {
                     iconContent: 34
                 }
             }
        ]
    }
});

Fields

NameTypeDescription
clustersobjectManager.ClusterCollection

Collection of clusters generated by the manager.

eventsIEventManager

Event manager.

Inherited from IDomEventEmitter.

geometryIGeometry|null

Geo object geometry.

Inherited from IGeoObject.

objectsobjectManager.ObjectCollection

Collection of objects added to the layer.

optionsIOptionManager

Options manager.

Inherited from ICustomizable.

propertiesIDataManager

Geo object data.

Inherited from IGeoObject.

stateIDataManager

State of the geo object.

Inherited from IGeoObject.

Events

NameDescription
click

Single left-click on the object. When using, keep in mind that mouse events are emulated when a touch screen is used. More information is available in domEvent.manager.

Inherited from IDomEventEmitter.

contextmenu

Calls the element's context menu. When using, keep in mind that mouse events are emulated when a touch screen is used. More information is available in domEvent.manager.

Inherited from IDomEventEmitter.

dblclick

Double left-click on the object. When using, keep in mind that mouse events are emulated when a touch screen is used. More information is available in domEvent.manager.

Inherited from IDomEventEmitter.

geometrychange

Change to the geo object geometry. Instance of the Event class. Names of fields that are available via the Event.get method:

  • originalEvent: IEvent - Original event of the geometry.

Inherited from IGeoObject.

mapchange

Map reference changed. Data fields:

  • oldMap - Old map.
  • newMap - New map.

Inherited from IParentOnMap.

mousedown

Pressing the mouse button over the object. When using, keep in mind that mouse events are emulated when a touch screen is used. More information is available in domEvent.manager.

Inherited from IDomEventEmitter.

mouseenter

Pointing the cursor at the object. When using, keep in mind that mouse events are emulated when a touch screen is used. More information is available in domEvent.manager.

Inherited from IDomEventEmitter.

mouseleave

Moving the cursor off of the object. When using, keep in mind that mouse events are emulated when a touch screen is used. More information is available in domEvent.manager.

Inherited from IDomEventEmitter.

mousemove

Moving the cursor over the object. When using, keep in mind that mouse events are emulated when a touch screen is used. More information is available in domEvent.manager.

Inherited from IDomEventEmitter.

mouseup

Letting go of the mouse button over an object. When using, keep in mind that mouse events are emulated when a touch screen is used. More information is available in domEvent.manager.

Inherited from IDomEventEmitter.

multitouchend

End of multitouch. This event is only available on devices that support multitouch. Returns an implementation of the IMultiTouchEvent interface.

Inherited from IDomEventEmitter.

multitouchmove

Repeating event during multitouch. This event is only available on devices that support multitouch. Returns an implementation of the IMultiTouchEvent interface with information about touches. Defines the touches property, which contains a list of touches. Every touch is described by an object that contains the following fields:

  • clientX - X coordinate of the touch relative to the viewable area of the browser.
  • clientY - Y coordinate of the touch relative to the viewable area of the browser.
  • pageX - X coordinate of the touch relative to the beginning of the document.
  • pageY - Y coordinate of the touch relative to the beginning of the document.

Inherited from IDomEventEmitter.

multitouchstart

Start of multitouch. This event is only available on devices that support multitouch. Returns an implementation of the IMultiTouchEvent interface with information about touches. Defines the touches property, which contains a list of touches. Every touch is described by an object that contains the following fields:

  • clientX - X coordinate of the touch relative to the viewable area of the browser.
  • clientY - Y coordinate of the touch relative to the viewable area of the browser.
  • pageX - X coordinate of the touch relative to the beginning of the document.
  • pageY - Y coordinate of the touch relative to the beginning of the document.

Inherited from IDomEventEmitter.

optionschange

Change to the object options.

Inherited from ICustomizable.

overlaychange

Change to the geo object overlay. Instance of the Event class. Names of fields that are available via the Event.get method:

  • overlay: IOverlay|null - Reference to the overlay.
  • oldOverlay: IOverlay|null - Previous overlay of the geo object.

Inherited from IGeoObject.

parentchange

The parent object reference changed.

Data fields:

  • oldParent - Old parent.
  • newParent - New parent.

Inherited from IChild.

propertieschange

Change to the geo object data. Instance of the Event class. Names of fields that are available via the Event.get method:

  • originalEvent: IEvent - Original event of the data manager.

Inherited from IGeoObject.

wheel

Mouse wheel scrolling. When using, keep in mind that mouse events are emulated when a touch screen is used. More information is available in domEvent.manager.

Inherited from IDomEventEmitter.

Methods

NameReturnsDescription
getBounds()

Number[][]|null

Calculates the boundaries in geo coordinates for an area that covers all the loaded objects in the manager.

getMap()

Map

Returns reference to the map.

Inherited from IParentOnMap.

getObjectState(id)

Object

Getting information about the current state of an object added to the manager.

getOverlay()

vow.Promise

Returns the promise object, which is confirmed by the overlay object at the time it is actually created, or is rejected with an appropriate error message.

Inherited from IGeoObject.

getOverlaySync()

IOverlay|null

The method provides synchronous access to the overlay.

Inherited from IGeoObject.

getParent()

IControlParent|null

Returns link to the parent object, or null if the parent element was not set.

Inherited from IChildOnMap.

getPixelBounds()

Number[][]|null

Calculates the boundaries in global pixel coordinates for an area that covers all the loaded objects in the manager.

getTileUrl()

String|null

Returns URL of the tile with data.

getUrlTemplate()

String

Returns URL data template.

reloadData()

Method that deletes all previously loaded data and sends a request for new data.

setFilter(filterFunction)

Sets a filter function for objects. Filters both individual objects and clusters.

setParent(parent)

IChildOnMap

Sets the parent object. If the null value is passed, the manager element will only be deleted from the current parent object.

Inherited from IChildOnMap.

setUrlTemplate(urlTemplate)

Fields details

clusters

Collection of clusters generated by the manager.

Example:

objectManager.clusters.events.add('click', function (e) {
    var objectId = e.get('objectId');
    objectManager.clusters.balloon.open(objectId);
});

objects

Collection of objects added to the layer.

Example:

objectManager.objects.events.add('click', function (e) {
    var objectId = e.get('objectId');
    objectManager.objects.balloon.open(objectId);
});

Methods details

getBounds

{Number[][]|null} getBounds()

Calculates the boundaries in geo coordinates for an area that covers all the loaded objects in the manager.

Returns array of the area's coordinates, or null if the manager has not been added to the map.

getObjectState

{Object} getObjectState(id)

Getting information about the current state of an object added to the manager.

Returns object with following fields:

  • found - Attribute that indicates whether an object with the passed ID exists in the loaded data. Type: Boolean.
  • isShown - Attribute that indicates whether the object is located in the visible area of the map. Type: Boolean.
  • isFilteredOut - Attribute indicating whether an object passed through filtration. If the filter is not set or the object passed through filtration, the value of the field is "false". Type: Boolean.
.

Parameters:

ParameterDefault valueDescription
id*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Object

ID of the object to get the state for.

* Mandatory parameter/option.

Example:

remoteObjectManager.setFilter('properties.type == "shop"');
...
if (!remoteObjectManager.getObjectState(7).isFilteredOut) {
    remoteObjectManager.objects.balloon.open(7);
}

getPixelBounds

{Number[][]|null} getPixelBounds()

Calculates the boundaries in global pixel coordinates for an area that covers all the loaded objects in the manager.

Returns array of the area's coordinates, or null if the manager has not been added to the map.

getTileUrl

{String|null} getTileUrl()

Returns URL of the tile with data.

Parameters:

ParameterDefault valueDescription
parameters*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type:

* Mandatory parameter/option.

Example:

var objectManager = new ymaps.RemoteObjectManager('http://myServer.com/tile?bbox=%b');
objectManager.getTileUrl = function (parameters) {
   var boundingBox = parameters.boundingBox.join('~');
   return this.getUrlTemplate().replace(/%b/g, boundingBox);
};

getUrlTemplate

{String} getUrlTemplate()

Returns URL data template.

reloadData

{} reloadData()

Method that deletes all previously loaded data and sends a request for new data.

setFilter

{} setFilter(filterFunction)

Sets a filter function for objects. Filters both individual objects and clusters.

Parameters:

ParameterDefault valueDescription
filterFunction*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Function|String

Filter function. Takes a single object added to ObjectManager. If the function returns true, the object will be processed. If false, the object will be excluded from further processing. A string can also be passed as a filter. The following keywords are available in the string filter:

  • options - Accessing the object's options.
  • properties - Accessing the object's data.
  • geometry - Accessing the object's geometry.
  • id - Accessing the object's identifier.
For a filter, you can specify an expression that returns true or false.

* Mandatory parameter/option.

Examples:

1.

// Select clusters with id > 100.
objectManager.setFilter('object.type == "Cluster" && id > 100');

2.

// Only objects of the specified types will be displayed on the map.
objectManager.setFilter('properties.type == "cafe" || properties.type == "pharmacy"');

3.

// You can define a filter function.
objectManager.setFilter(function (object) {
    return object.properties.name != 'The one who cannot be shown.';
});

setUrlTemplate

{} setUrlTemplate(urlTemplate)

Parameters:

ParameterDefault valueDescription
urlTemplate*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: String

URL data template.

* Mandatory parameter/option.