Documentation
Reference
2.1.38 (current version)
collection
interactivityModel
Interfaces

Developing the frontend

Creating a manager

Use the ObjectManager class to create the manager. Its constructor can be used for setting the manager's options.

var objectManager = new ymaps.ObjectManager({
      // Use clusterization.
      clusterize: true
    });

To add objects to the manager, use the add() method. For parameters, pass the description of objects in JSON format. It should contain the ID, information about geometries of objects and their coordinates, as well as their properties.

Example of a JSON description of objects
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": 0,
      "geometry": {
        "type": "Point",
        "coordinates": [55.831903, 37.411961]
      },
      "properties": {
        "balloonContent": "Balloon content",
        "clusterCaption": "Placemark 1",
        "hintContent": "Hint text"
      }
    },
    {
      "type": "Feature",
      "id": 1,
      "geometry": {
        "type": "Point",
        "coordinates": [55.763338, 37.565466]
      },
      "properties": {
        "balloonContent": "Balloon content",
        "clusterCaption": "Placemark 2",
        "hintContent": "Hint text"
      }
    }
  ]
}

The ID uniquely identifies each object of the manager. You can use the ID to get access to the desired object and, for example, change its options. Object IDs are required attributes and must be created independently.

In the example below, JSON data is added to the manager. This data was loaded from the server using the jQuery.getJSON() function.

jQuery.getJSON('data.json', function (json) {
  objectManager.add(json);  
});

Objects added to the manager are put in the objectManager.ObjectCollection collection. The link to this collection is in objectManager.objects.

In order to display objects on the map, the manager must be added to the collection of map objects.

myMap.geoObjects.add(objectManager);

Note. You can see an example of adding objects to the map using ObjectManager in the sandbox.

Object clustering

If clustering is necessary for objects being added to the map via the manager, when creating it, the constructor should be given the clusterize: true option.

Cluster objects are placed in the objectManager.ClusterCollection collection. The link to this collection is in objectManager.clusters.

IDs for clusters are generated automatically when creating them.

Setting object options

The manager implements hierarchical inheritance for options. This means that object options are inherited from their parent collections. To set options for all manager objects, you only need to set the appropriate option for the entire collection of objects.

// Setting icon style for separate placemarks.
objectManager.objects.setObjectOptions('preset', 'islands#greenDotIcon');

// Icon style for clusters.
objectManager.clusters.options.setClusterOptions('preset', 'islands#greenClusterIcons');

These methods allow setting object options “on the fly”. This means that when setting these object options, the object's overlay is reconstructed, meaning the changes are immediately reflected on the map.

Object options can also be set using the set() method:

objectManager.objects.getById(1).set('preset', 'islands#greenDotIcon');
When setting object options using the set() method, their overlays will not be reconstructed. So in order for changes to be reflected on the map, you must use the set() method before the manager is added to the map.

Note. You can review an example of changing object options in the sandbox.

Manager objects can be given the same options as geo objects that are instances of Placemark. The list of cluster options is given in the description of the ClusterPlacemark class.

Filtering objects when displaying

ObjectManager allows filtering objects by attributes. For example, you can display only red objects, or only objects with IDs higher than 10.

Use the setFilter() method for filtering objects. As a parameter, pass a string containing the condition for selecting objects, or a filter function that must return true or false.

// Skip objects with an ID lower than 100.
objectManager.setFilter('id > 100');

// The map will only display objects with the specified types.
objectManager.setFilter('properties.type == "cafe" || properties.type == "pharmacy"');

// A filter function can be set.
objectManager.setFilter(function (object) {
  return object.properties.name != 'The one that can't be displayed.';
});

Overlays

Placemarks and clusters are represented as overlay.Placemark objects, which implement the IOverlay interface.

The visual representation of manager objects is created asynchronously on request. You can use the syncOverlayInit option to set the manager to create object overlays in synchronous mode.

Links to overlays for placemarks and clusters are in objectManager.objects.overlays and objectManager.clusters.overlays, respectively.

Processing events on objects

Events on the manager's objects are propagated to the parent collections. If events on placemarks or clusters must be tracked, an event handler should be assigned for the objectManager.objects and objectManager.clusters collections, respectively. The unique ID of the object where the event occurred is passed in the objectID attribute of the event.

// When pointing the mouse at placemarks, their icons turn yellow
// When the pointer moves away, the icon color turns blue.
function onObjectEvent (e) {
  var obj = e.get('target');
  if (obj.properties. == 'islands#redDotIcon') {
    // The setObjectOptions method allows setting options for an object "on the fly".
    objectManager.objects.setObjectOptions(objectId, {
      preset: 'islands#yellowIcon'
    });
  } else {
    objectManager.objects.setObjectOptions(objectId, {
      preset: 'islands#blueIcon'
    });
  }
}

// Assigning the event handler for the manager's collection of objects.   
objectManager.objects.events.add(['click'], onObjectEvent);

Assigning the event handler for a collection of clusters:

// When pointing the mouse at placemarks, their icons turn yellow.
// When the pointer moves away, the icon color turns blue.
function onClusterEvent (e) {
  var objectId = e.get('objectId');
  if (e.get('type') == 'mouseenter') {
    //  The setObjectOptions method allows setting options for an object "on the fly".
    objectManager.objects.setObjectOptions(objectId, {
      preset: 'islands#yellowIcon'
    });
  } else {
    objectManager.objects.setObjectOptions(objectId, {
      preset: 'islands#blueIcon'
    });
  }  
}

// Assigning the event handler for the manager's collection of cluster objects.   
objectManager.clusters.events.add(['mouseenter', 'mouseleave'], onClusterEvent);

Sometimes events need to be tracked on a particular object of the manager. In this case, the event handler should be assigned for this object's overlay.

// When pointing the mouse at clusters, their icons turn yellow.
// When the pointer moves away, the icon color turns blue.
function onClusterEvent (e) {
  e.balloon.open('');
}

var overlay = objectManager.objects.overlays.getById(100);
overlay.events.add('click', onOverlayEvent);