ClusterPlacemark

Extends IGeoObject, collection.Item.

Cluster of geo objects. Used by default in Clusterer.

Constructor | Fields | Events | Methods

Constructor

ClusterPlacemark(geometry, properties[, options])

Parameters:

Parameter

Default value

Description

geometry*

Type: Number[]

Object

IPointGeometry

Coordinates of the placemark, or a hash describing the geometry, or a reference to the point geometry object.

properties*

Type: IDataManager

Cluster data.

properties.geoObjects*

Type: IGeoObject[]

Array of geo objects that are located in the given cluster.

options

Type: Object

Cluster options. In addition to special options, the cluster balloon supports the same options as Balloon. The cluster balloon options are indicated with the "balloon" prefix.

options.balloonContentLayout

'cluster#balloonTwoColumns'

Type: Function|String

Layout of the cluster balloon in normal mode. You can pass the object's constructor with the ILayout interface or the key for one of the standard layouts. Each standard layout has several customized options. In standard layouts, geo object data fields are used by default: clustercaption, balloonContentHeader, balloonContent, and balloonContentFooter (see Placemark).

  • 'cluster#balloonTwoColumns' - Two-column layout. The left column lists the names of placemarks (the clusterCaption field of the placemark or balloonContentHeader, if the first field is not defined). The right column contains information about the geo object. Layout options:

    • balloonLeftColumnWidth — The width of the column with the list of objects in the cluster balloon, in pixels. Default value: 125
  • 'cluster#balloonCarousel' - Information about the geo object is positioned in the center. The buttons to navigate to the previous and next geo object are positioned on each side. The lower part of the balloon has a quick navigation menu. Layout options:

    • balloonCycling — Cycle the list when navigating with the side arrows. Default value: true
    • balloonPagerSize — Number of navigational items in the lower panel. The default value depends on the type of device. For mobile phones it is 4, and for tablets and PCs — 9.
    • balloonPagerType — Type of lower panel for navigation. Takes the values 'numeric' or 'marker'.
    • numeric — Display the number of a geo object in the list.
    • marker — Display markers without numbers. Recommended for use when the number of items in the cluster is less than or equal to the value of options.balloonPagerSize.
      Default value: numeric
    • balloonPagerVisible — Whether to display the navigation panel. Default value: true
  • 'cluster#balloonAccordion' - Information about geo objects in list format. Each list item is a small icon and the name of the placemark (the clusterCaption field of the placemark or balloonContentHeader, if the first field is not defined). The color of the icon corresponds to the color of the placemark. The color of the placemark is defined by the "iconColor" Placemark option. The icons might not always appear in Internet Explorer 8 and below. When a list item is clicked, information about the geo object is expanded beneath it. Layout options:

    • balloonAccordionShowIcons — Option that determines whether to display the geo object's icon in the 'cluster#balloonAccordionItemTitle' layout. This option is not used in Internet Explorer 8 and below. Default value: true

options.balloonContentLayoutHeight

Type: Number

The height of the layout of the content of the balloon cluster. The balloon cluster option balloonMaxHeight is not set by default, because all standard layouts have fixed dimensions. The standard value depends on the layout.

  • 'cluster#balloonTwoColumns' - 210 pixels
  • 'cluster#balloonCarousel' - 177 pixels
  • 'cluster#balloonAccordion' - 283 pixels

options.balloonContentLayoutWidth

Type: Number

The width of the layout of the content of the balloon cluster. The balloon cluster option balloonMaxWidth is not set by default, because all standard layouts have fixed dimensions. The standard value depends on the layout.

  • 'cluster#balloonTwoColumns' - 475 pixels
  • 'cluster#balloonCarousel' - 308 pixels
  • 'cluster#balloonAccordion' - 305 pixels
    The option is not used in the panel mode.

options.balloonItemContentLayout

Type: ILayout|String

The layout containing the information about geo object. The standard value depends on the layout.

  • Displayed to the right of the list in the 'cluster#balloonTwoColumns' layout. The standard value of 'cluster#balloonTwoColumnsItemContent'
  • Displayed in the center in the 'cluster#balloonCarousel' layout. The standard value of 'cluster#balloonCarouselItemContent'.
  • Displayed after the list item is clicked in the 'cluster#balloonAccordion' layout. The standard value of 'cluster#balloonAccordionItemContent'.
    ** The set of fields received by this layout differs from the parent and matches the fields that received by the standard layout of a geo object balloon. Additionally, ownerProperties, ownerOptions and ownerState fields have been added to access the cluster data. **

options.balloonPanelContentLayout

null

Type: Function|String

Layout of the cluster balloon in the "panel" mode. You can pass the object's constructor with the ILayout interface. The available values are the same as in the 'balloonContentLayout' options. If null, then the value of the 'balloonContentLayout' option is used.

options.cursor

'pointer'

Type: String

Cursor over the cluster marker.

options.disableClickZoom

false

Type: Boolean

Flag that prohibits zooming in on the map when the cluster is clicked.

options.hideIconOnBalloonOpen

true

Type: Boolean

Hide the icon when opening the balloon.

options.iconColor

Type: String

The color of the cluster icon. This option is used for standard icons in browsers that support SVG.

options.iconContentLayout

'cluster#iconContent'

Type: Function|String

Layout for cluster marker contents. (Type: constructor for an object with the ILayout interface or the layout key). If you do not want to display the content of the placemark, set the option value to null.

options.iconLayout

'cluster#icon'

Type: Function|String

Layout of the cluster placemark (Type: constructor for an object with the ILayout interface or the layout key).

options.icons

Type: Object[]

Array describing the icon for standard implementation of the cluster. An icon description is made up of an object with the following fields:

  • href - Link to the image.
  • size - Array of two numbers representing the icon size in pixels.
  • offset - Offset of the icon relative to the anchor point of the object.
  • shape - Optional field. An object that implements the IShape interface or a JSON description of the geometry. Allows to specify the description of the icon geometry. If the parameter is omitted, a rectangular area around the icon will be considered as an active area for events (mouse over, mouse click).

options.iconShape

Type: IGeometryJson|null

The hotspot shape of the cluster. Specified as a JSON description of the pixel geometry of the icon. Use this option when creating your HTML layouts. The coordinates of the figure geometry are counted from the anchor point.

options.interactivityModel

'default#geoObject'

Type: String

Cluster interactivity model. Available keys and their values are listed in the description of interactivityModel.storage.

options.numbers

[10, 100]

Type: Number[]

Array describing the boundary values for cluster dimensions. The number of icons described in the "icons" options must be 1 more than the number in this array.

options.openBalloonOnClick

true

Type: Boolean

Option that prevents opening the balloon when clicking on a cluster. By default, opening the balloon is allowed.

options.openEmptyHint

false

Type: Boolean

Enables displaying empty popup hints. Empty cluster hints are not shown by default.

options.openHintOnHover

true

Type: Boolean

Option that allows you to forbid displaying the popup hint when the cluster is pointed at. By default, showing hints is allowed.

options.zIndexHover

Type: Number

The zIndex value, which is set to the cluster placemark on mouse hovering.

* Mandatory parameter/option.

Examples:

1.

// Variable with a description of two types of cluster icons.
var clusterIcons = [
    {
        href: 'small.png',
        size: [40, 40],
        // Offset so the image center matches the cluster center.
        offset: [-20, -20]
    },
    {
        href: 'big.png',
        size: [60, 60],
        offset: [-30, -30],
        // You can define the shape of the hotspot area
        // of the placemark.
        // The rectangular area is used by default.
        shape: {
            type: 'Circle',
            coordinates: [0, 0],
            radius: 30
        }
    }
],
// For a cluster size up to 100, the image small.jpg will be used.
// For a cluster size over 100, big.png will be used.
clusterNumbers = [100],
// Making a layout for cluster icon contents,
// in which numbers will be white.
MyIconContentLayout = ymaps.templateLayoutFactory.createClass(
    '<div style="color: #FFFFFF; font-weight: bold;">{{ properties.geoObjects.length }}</div>'
),
var clusterer = new ymaps.Clusterer({
    // If options for the cluster are set via the clusterer,
    // they must be specified with the "cluster" prefix.
    clusterIcons: clusterIcons,
    clusterNumbers: clusterNumbers,
    clusterIconContentLayout: MyIconContentLayout
});

2.

// Creating a clusterer with a carousel layout.
var clusterer = new ymaps.Clusterer({
    clusterDisableClickZoom: true,
    // Using the carousel layout.
    clusterBalloonContentLayout: "cluster#balloonCarousel",
    // Prohibiting cycling the list for paginated navigation.
    clusterBalloonCycling: false,
    // Configuring the appearance of the navigation panel.
    // Markers will be the items in the navigation panel.
    clusterBalloonPagerType: "marker",
    // Number of items in the navigation panel.
    clusterBalloonPagerSize: 6
});

3.

// Creating a clusterer with an accordian layout.
var clusterer = new ymaps.Clusterer({
    clusterDisableClickZoom: true,
    // Using the accordian layout.
    clusterBalloonContentLayout: "cluster#balloonAccordion"
});

4.

// Creating a clusterer with a custom HTML layout of the cluster icon.
var clusterer = new ymaps.Clusterer({
    // Defining the cluster placemark layout.
    clusterIconLayout: ymaps.templateLayoutFactory.createClass('<div class="clusterIcon">{{ properties.geoObjects.length }}</div>'),
    // Redefining the active area of the placemark to make it clickable.
    clusterIconShape: {
        type: 'Rectangle',
        coordinates: [[0, 0], [20, 20]]
    }
});

Fields

Name

Type

Description

events

IEventManager

Event manager.

Inherited from IDomEventEmitter.

geometry

IGeometry|null

Geo object geometry.

Inherited from IGeoObject.

options

IOptionManager

Options manager.

Inherited from ICustomizable.

properties

IDataManager

Geo object data.

Inherited from IGeoObject.

state

data.Manager

Cluster state. Defined by the following fields:

  • activeObject - Reference to the cluster's active object. The active object is the one that is currently selected in the cluster balloon.

Events

Name

Description

click

Single left-click on the object. When using, keep in mind that mouse events are emulated when a touch screen is used. Instance of the MapEvent class. More information is available in domEvent.manager.

Inherited from IDomEventEmitter.

contextmenu

Calls the element's context menu. When using, keep in mind that mouse events are emulated when a touch screen is used. Instance of the MapEvent class. More information is available in domEvent.manager.

Inherited from IDomEventEmitter.

dblclick

Double left-click on the object. When using, keep in mind that mouse events are emulated when a touch screen is used. Instance of the MapEvent class. More information is available in domEvent.manager.

Inherited from IDomEventEmitter.

geometrychange

Change to the geo object geometry. Instance of the Event class. Names of fields that are available via the Event.get method:

  • originalEvent: IEvent - Original event of the geometry.

Inherited from IGeoObject.

mapchange

Map reference changed. Data fields:

  • oldMap - Old map.
  • newMap - New map.

Inherited from IParentOnMap.

mousedown

Pressing the mouse button over the object. When using, keep in mind that mouse events are emulated when a touch screen is used. Instance of the MapEvent class. More information is available in domEvent.manager.

Inherited from IDomEventEmitter.

mouseenter

Pointing the cursor at the object. When using, keep in mind that mouse events are emulated when a touch screen is used. Instance of the MapEvent class. More information is available in domEvent.manager.

Inherited from IDomEventEmitter.

mouseleave

Moving the cursor off of the object. When using, keep in mind that mouse events are emulated when a touch screen is used. Instance of the MapEvent class. More information is available in domEvent.manager.

Inherited from IDomEventEmitter.

mousemove

Moving the cursor over the object. When using, keep in mind that mouse events are emulated when a touch screen is used. Instance of the MapEvent class. More information is available in domEvent.manager.

Inherited from IDomEventEmitter.

mouseup

Letting go of the mouse button over an object. When using, keep in mind that mouse events are emulated when a touch screen is used. Instance of the MapEvent class. More information is available in domEvent.manager.

Inherited from IDomEventEmitter.

multitouchend

End of multitouch. This event is only available on devices that support multitouch. Returns an implementation of the IMultiTouchEvent interface.

Inherited from IDomEventEmitter.

multitouchmove

Repeating event during multitouch. This event is only available on devices that support multitouch. Returns an implementation of the IMultiTouchEvent interface with information about touches. Defines the touches property, which contains a list of touches. Every touch is described by an object that contains the following fields:

  • clientX - X coordinate of the touch relative to the viewable area of the browser.
  • clientY - Y coordinate of the touch relative to the viewable area of the browser.
  • pageX - X coordinate of the touch relative to the beginning of the document.
  • pageY - Y coordinate of the touch relative to the beginning of the document.

Inherited from IDomEventEmitter.

multitouchstart

Start of multitouch. This event is only available on devices that support multitouch. Returns an implementation of the IMultiTouchEvent interface with information about touches. Defines the touches property, which contains a list of touches. Every touch is described by an object that contains the following fields:

  • clientX - X coordinate of the touch relative to the viewable area of the browser.
  • clientY - Y coordinate of the touch relative to the viewable area of the browser.
  • pageX - X coordinate of the touch relative to the beginning of the document.
  • pageY - Y coordinate of the touch relative to the beginning of the document.

Inherited from IDomEventEmitter.

optionschange

Change to the object options.

Inherited from ICustomizable.

overlaychange

Change to the geo object overlay. Instance of the Event class. Names of fields that are available via the Event.get method:

  • overlay: IOverlay|null - Reference to the overlay.
  • oldOverlay: IOverlay|null - Previous overlay of the geo object.

Inherited from IGeoObject.

parentchange

The parent object reference changed.

Data fields:

  • oldParent - Old parent.
  • newParent - New parent.

Inherited from IChild.

propertieschange

Change to the geo object data. Instance of the Event class. Names of fields that are available via the Event.get method:

  • originalEvent: IEvent - Original event of the data manager.

Inherited from IGeoObject.

wheel

Mouse wheel scrolling. When using, keep in mind that mouse events are emulated when a touch screen is used. Instance of the MapEvent class. More information is available in domEvent.manager.

Inherited from IDomEventEmitter.

Methods

Name

Returns

Description

getBounds()

Number[][]|null

Returns the geographical coordinates of the rectangular area that includes all the cluster elements.

getGeoObjects()

IGeoObject[]

The method is a simplified call of cluster.properties.get('geoObjects');

getMap()

Map

Returns reference to the map.

Inherited from IParentOnMap.

getOverlay()

vow.Promise

Returns the promise object, which is confirmed by the overlay object at the time it is actually created, or is rejected with an appropriate error message.

Inherited from IGeoObject.

getOverlaySync()

IOverlay|null

The method provides synchronous access to the overlay.

Inherited from IGeoObject.

getParent()

IParentOnMap|null

Returns link to the parent object, or null if the parent element was not set.

Inherited from IChildOnMap.

onAddToMap(map)

Function that is called when adding an element to the map. To perform additional actions when adding the object to the map, redefine this function.

Inherited from collection.Item.

onRemoveFromMap(oldMap)

Function that is called when deleting an element from the map. To perform additional actions when deleting the object from the map, redefine this function.

Inherited from collection.Item.

setParent(parent)

IChildOnMap

Sets the parent object. If the null value is passed, the manager element will only be deleted from the current parent object.

Inherited from IChildOnMap.

Fields details

state

{data.Manager} state

Cluster state. Defined by the following fields:

  • activeObject - Reference to the cluster's active object. The active object is the one that is currently selected in the cluster balloon.

Example:

var geoObjects = cluster.properties.get('geoObjects');
// When opening the cluster's balloon, the third object in the list will be selected.
cluster.state.set('activeObject', geoObjects[2]);

Methods details

getBounds

{Number[][]|null} getBounds()

Returns the geographical coordinates of the rectangular area that includes all the cluster elements.

getGeoObjects

{IGeoObject[]} getGeoObjects()

The method is a simplified call of cluster.properties.get('geoObjects');

Returns an array of geo objects that make up the cluster.