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

{objectManager.Balloon} balloon

Cluster balloon in the manager.

hint

{objectManager.Hint} 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

{objectManager.OverlayCollection} 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');
    var 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'));
    var 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;
var it = objectManager.clusters.getIterator();
var 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

{objectManager.ObjectCollection} setClusterOptions(objectId, options)

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'));
    var objects = cluster.properties.geoObjects;
    if (objects.length > 20) {
        objectManager.clusters.setClusterOptions(cluster.id, {
            preset: 'islands#redClusterIcons'
        });
    }
});