Documentation
Reference
2.1.50 (current version)
collection
interactivityModel
Interfaces

Developing the frontend

Creating a manager

The object manager is created using the LoadingObjectManager class. Its constructor can be passed the following parameters:

  • urlTemplate — Template for the data URL (mandatory parameter).

    More about templates

    Using templates lets the manager automatically generate the appropriate URL for each tile (or for a particular area). For example, let's assume the template for the data URL looks like this:

    http://server.domain/?tileNumber=%t

    When forming a request, the manager performs substitution: in place of %t it substitutes the numbers of the upper-left and lower-right tiles of the requested area. So, for example, an area with the corner tiles [1,1] and [5,5] will have a data URL that looks like this:

    http://server.domain/?tileNumber=1,1,5,5.

  • Manager options.
var loadingObjectManager = new ymaps.LoadingObjectManager('http://myServer.com/tile?bbox=%b',
      {   
        // Enabling clusterization.
        clusterize: true,
        // Cluster options are set with the 'cluster' prefix.
        clusterHasBalloon: false,
        // Object options are set with the geoObject prefix.
        geoObjectOpenBalloonOnClick: false
      });

In order for the manager to start loading objects from the server, it must be added to the collection of map objects.

myMap.geoObjects.add(loadingObjectManager);

After being added to the map, the manager starts sending requests for data for the visible map area.

The manager puts loaded objects in the objectManager.ObjectCollection collection, which is linked to from loadingObjectManager.objects.

Setting up interaction between the manager and server

Most of the manager options define its behavior on the client side. For example, whether clusterization will be used, and whether overlays will be created synchronously. However, certain options affect how the manager interacts with the server. These options are covered in detail below.

paddingTemplate

You can use the paddingTemplate option to set a template for the callback function that the server will wrap the response in. Using templates allows the manager to specify the appropriate callback function for each request.

The manager passes the server the name of the callback function in the 'callback' parameter.

If the name of the callback function is not set when creating the manager, the manager will automatically generate new names for these functions each time before sending a request.

'{data URL}?callback=id_1234567'.

splitRequests

The splitRequests option allows you to set the mode in which the manager will load data from the server. The manager supports two modes for loading data:

  • Data is loaded for the entire viewport simultaneously (splitRequests = false).
  • Data is loaded for the viewport by tile (splitRequests = true).

By default, splitRequests = false, meaning the manager loads data immediately for the entire map viewport.

The choice of data loading mode depends on how interaction between the frontend and backend is organized. For more information about these modes, see the section Developing the backend.

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

Objects added to the manager are put in the objectManager.ObjectCollection collection. The link to this collection is in loadingObjectManager.objects. If clusterization is used when displaying objects, the cluster objects are placed in the objectManager.ClusterCollection collection. The link to this collection is in loadingObjectManager.clusters.

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.
loadingObjectManager.objects.set('preset', 'islands#greenDotIcon');

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

You can set the same options for manager objects as for geo objects. The list of cluster options is given in the description of the ClusterPlacemark class.

Filtering objects when displaying

LoadingObjectManager 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.
loadingObjectManager.setFilter('id > 100');

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

// A filter function can be set.
loadingObjectManager.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.

By default, 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. This means that if events on the manager's placemarks must be tracked, an event handler should be assigned for the loadingObjectManager.objects collection. 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".
    loadingObjectManager.objects.setObjectOptions(objectId, {
      preset: 'islands#yellowIcon'
    });
  } else {
    loadingObjectManager.objects.setObjectOptions(objectId, {
      preset: 'islands#blueIcon'
    });
  }
}

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

For clusters, an event handler is assigned for the loadingObjectManager.objects.clusters collection.

// 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".
    loadingObjectManager.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.   
loadingObjectManager.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 = loadingObjectManager.objects.overlays.getById(100);
overlay.events.add('click', onOverlayEvent);