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

Name Type Description
balloon objectManager.Balloon

Cluster balloon in the manager.

events IEventManager

Event manager.

Inherited from IEventEmitter.

hint objectManager.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 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.
overlays objectManager.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.

state data.Manager
State of the collection of clusters. Defined by the following fields:
  • activeObject - JSON description of the object selected in the cluster balloon.

Events

Name Description
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

Name Returns Description
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:

Parameter Default value Description
callback *

Type: Function

Callback function that the collection objects are passed to.

context *

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:

Parameter Default value Description
id *

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:

Parameter Default value Description
objectId *

Type: String

Cluster ID.

options *

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'
        });
    }
});