Documentation
Reference
2.1.53 (current version)
collection
interactivityModel
Interfaces

objectManager.ClusterCollection

Extends ICustomizable, IEventEmitter.

Collection of clusters generated by ObjectManager. Clusters are added to and deleted from the collection automatically, and are read-only. The cluster object is a JSON structure the same as the objects in the layer. Cluster object field:

  • id - Unique cluster ID.
  • geometry - Description of the cluster geometry.
  • properties - Description of the cluster data. The properties.geoObjects field stores an array of objects that are included in the cluster.
  • options - Cluster options. Optional field.

Constructor | Fields | Events | Methods

Constructor

objectManager.ClusterCollection()

Fields

NameTypeDescription
balloonobjectManager.Balloon

Cluster balloon in the manager.

eventsIEventManager

Event manager.

Inherited from IEventEmitter.

hintobjectManager.Hint

Object hint in the ObjectManager. Names of fields available via Event#get:

  • objectId - ID of the object where the hint was shown.

optionsoption.Manager

Options manager. Names of fields that are available via the option.Manager#get method:

  • hasBalloon - Indicates whether the collection has the .balloon field. If a balloon doesn't need to be opened when clicking the cluster, we recommend setting this option to the "false" value to avoid unnecessary initializations.
  • hasHint - Indicates whether the collection has the .hint field. If a popup hint doesn't need to be displayed when the cluster is pointed at, we recommend setting this option to the "false" value to avoid unnecessary initializations.
  • hideIconOnBalloonOpen - Hide the icon when opening the balloon. Default value: true.
  • openBalloonOnClick - Option that allows you to forbid opening the balloon when clicking on a cluster. By default, opening the balloon is allowed.
  • openHintOnHover - Option that allows you to forbid displaying the popup hint when the cluster is pointed at. By default, showing hints is allowed.

overlaysobjectManager.OverlayCollection

Collection of cluster overlays. All events, with the exception of "add" and "remove" events, propagate from the collection of overlays to the collection of clusters.

statedata.Manager

State of the collection of clusters. Defined by the following fields:

  • activeObject - JSON description of the object selected in the cluster balloon.

Events

NameDescription
add

Adds a cluster to the collection. Instance of the Event class. Names of fields that are available via the Event#get method:

  • objectId - ID of the added object.
  • child - The added object.

clusteroptionschange

Modification of cluster options via the objectManager.ClusterCollection#setClusterOptions method. Instance of the Event class. Names of fields that are available via the Event#get method:

  • objectId - ID of the cluster that had options modified.

optionschange

Change to the object options.

Inherited from ICustomizable.

remove

Deletes a cluster from the collection. Instance of the Event class. Names of fields that are available via the Event#get method:

  • objectId - ID of the deleted object.
  • child - The deleted object.

Methods

NameReturnsDescription
each(callback, context)
getAll()

Object[]

Returns array of objects contained in the collection.

getById(id)

Object|null

Returns cluster object with the specified ID, or null if this cluster does not exist.

getIterator()

IIterator

Returns iterator for the collection.

getLength()

Number

Returns the number of objects in the collection.

getObjectManager()

ObjectManager

Returns the parent layer of objects in the collection.

setClusterOptions(objectId, options)

objectManager.ObjectCollection

Returns self-reference.

Fields details

balloon

Cluster balloon in the manager.

hint

Object hint in the ObjectManager. Names of fields available via Event#get:

  • objectId - ID of the object where the hint was shown.

options

{option.Manager} options

Options manager. Names of fields that are available via the option.Manager#get method:

  • hasBalloon - Indicates whether the collection has the .balloon field. If a balloon doesn't need to be opened when clicking the cluster, we recommend setting this option to the "false" value to avoid unnecessary initializations.
  • hasHint - Indicates whether the collection has the .hint field. If a popup hint doesn't need to be displayed when the cluster is pointed at, we recommend setting this option to the "false" value to avoid unnecessary initializations.
  • hideIconOnBalloonOpen - Hide the icon when opening the balloon. Default value: true.
  • openBalloonOnClick - Option that allows you to forbid opening the balloon when clicking on a cluster. By default, opening the balloon is allowed.
  • openHintOnHover - Option that allows you to forbid displaying the popup hint when the cluster is pointed at. By default, showing hints is allowed.

Example:

objectManager.objects.options.set({
    preset: 'islands#greenDotIcon',
    hintContentLayout: ymaps.templateLayoutFactory.createClass('{{propeties.name}}')
});

overlays

Collection of cluster overlays. All events, with the exception of "add" and "remove" events, propagate from the collection of overlays to the collection of clusters.

Example:

// Changing the color of the cluster icon when moused over.
objectManager.clusters.events.add(['mouseenter', 'mouseleave'], function (e) {
    var objectId = e.get('objectId'),
        overlay = objectManager.clusters.overlays.getById(objectId);
    if (e.get('type') == 'mouseenter') {
        setRedColor(objectId);
        overlay.events.add('mapchange', onMapChange);
    } else {
        setGreenColor(objectId);
        overlay.events.remove('mapchange', onMapChange);
    }
});

function onMapChange (e) {
    setGreenColor(objectManager.clusters.overlays.getId(e.get('target')));
}

function setGreenColor (objectId) {
    objectManager.clusters.setClusterOptions(objectId, {
        preset: 'islands#greenClusterIcons'
    });
}

function setRedColor (objectId) {
    objectManager.clusters.setClusterOptions(objectId, {
        preset: 'islands#redClusterIcons'
    });
}

state

{data.Manager} state

State of the collection of clusters. Defined by the following fields:

  • activeObject - JSON description of the object selected in the cluster balloon.

Example:

// Opening the cluster balloon with the selected object.
var objectState = objectManager.getObjectState(myObjects[i]);
if (objectState.isClustered) {
    objectManager.clusters.state.set('activeObject', myObjects[i]);
    objectManager.clusters.balloon.open(objectState.cluster.id);
}

Events details

add

Adds a cluster to the collection. Instance of the Event class. Names of fields that are available via the Event#get method:

  • objectId - ID of the added object.
  • child - The added object.

clusteroptionschange

Modification of cluster options via the objectManager.ClusterCollection#setClusterOptions method. Instance of the Event class. Names of fields that are available via the Event#get method:

  • objectId - ID of the cluster that had options modified.

remove

Deletes a cluster from the collection. Instance of the Event class. Names of fields that are available via the Event#get method:

  • objectId - ID of the deleted object.
  • child - The deleted object.

Methods details

each

{} each(callback, context)

Parameters:

ParameterDefault valueDescription
callback*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Function

Callback function that the collection objects are passed to.

context*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Object

Context for the callback.

* Mandatory parameter/option.

Example:

var clusterizedObjectsCounter = 0;
objectManager.clusters.each(function (cluster) {
    clusterizedObjectsCounter += cluster.properties.geoObjects.length;
});
alert('The map shows ' + clusterizedObjectsCounter + ' clusterized objects.');

getAll

{Object[]} getAll()

Returns array of objects contained in the collection.

Example:

var clusterArray = objectManager.clusters.getAll();

getById

{Object|null} getById(id)

Returns cluster object with the specified ID, or null if this cluster does not exist.

Parameters:

ParameterDefault valueDescription
id*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: String

Cluster ID.

* Mandatory parameter/option.

Example:

// Making the cluster color change if it has more than 20 objects.
objectManager.clusters.events.add('add', function (e) {
    var cluster = objectManager.clusters.getById(e.get('objectId')),
        objects = cluster.properties.geoObjects;
    if (objects.length > 20) {
        objectManager.clusters.setClusterOptions(cluster.id, {
            preset: 'islands#redClusterIcons'
        });
    }
});

getIterator

{IIterator} getIterator()

Returns iterator for the collection.

Example:

var clusterizedObjectsCounter = 0,
    it = objectManager.clusters.getIterator(),
    cluster;
while ((cluster = it.getNext()) != it.STOP_ITERATION)
    clusterizedObjectsCounter += cluster.properties.geoObjects.length;
});
alert('The map displays ' + clusterizedObjectsCounter + ' clusterized objects.');

getLength

{Number} getLength()

Returns the number of objects in the collection.

Example:

alert('The map displays ' + objectManager.clusters.getLength() + ' clusters.');

getObjectManager

{ObjectManager} getObjectManager()

Returns the parent layer of objects in the collection.

setClusterOptions

Returns self-reference.

Parameters:

ParameterDefault valueDescription
objectId*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: String

Cluster ID.

options*
[no-highlight[

* Mandatory parameter/option.

]no-highlight]

Type: Object

Object with cluster options.

* Mandatory parameter/option.

Example:

// Making the cluster color change if it has more than 20 objects.
objectManager.clusters.events.add('add', function (e) {
    var cluster = objectManager.clusters.getById(e.get('objectId')),
        objects = cluster.properties.geoObjects;
    if (objects.length > 20) {
        objectManager.clusters.setClusterOptions(cluster.id, {
            preset: 'islands#redClusterIcons'
        });
    }
});