JS Tutorial
Download
- Overview
- Documents
- Demos
User Rating: 2.9/5 ( 5 votes)
Your Rating:
This is an enhanced version of the MarkerClusterer library for managing large amounts of markers. It adds support for several new properties as well as support for four more events. It also allows greater control over the styling of the text that appears on the cluster marker. The documentation has been significantly improved and the overall code has been simplified and polished. Very large numbers of markers can now be managed without causing Javascript timeout errors on Internet Explorer. It is backward compatible with MarkerClusterer.
Usage
Note: Be sure to include markerclusterer.js or markerclusterer_packed.js in your HTML document.
<script src="/path/to/markerclusterer.js" type="text/javascript"></script>
To use a marker clusterer, create a MarkerClusterer object. In the simplest case, just pass a map to it.
var center = new google.maps.LatLng(37.4419, -122.1419);
var options = {
'zoom': 13,
'center': center,
'mapTypeId': google.maps.MapTypeId.ROADMAP
};
var map = new google.maps.Map(document.getElementById("map"), options);
var mc = new MarkerClusterer(map);
You may also specify a number of options to fine-tune the marker clusterer's performance. These options are passed via an object.
var center = new google.maps.LatLng(37.4419, -122.1419);
var options = {
'zoom': 13,
'center': center,
'mapTypeId': google.maps.MapTypeId.ROADMAP
};
var map = new google.maps.Map(document.getElementById("map"), options);
var mcOptions = {gridSize: 50, maxZoom: 15};
var mc = new MarkerClusterer(map, [], mcOptions);
Once you create a marker clusterer, you will want to add markers to it. You can add markers using the addMarker() or addMarkers()method or by providing an array of markers to the constructor:
var center = new google.maps.LatLng(37.4419, -122.1419);
var options = {
'zoom': 13,
'center': center,
'mapTypeId': google.maps.MapTypeId.ROADMAP
};
var map = new google.maps.Map(document.getElementById("map"), options);
var mcOptions = {gridSize: 50, maxZoom: 15};
var markers = [...]; // Create the markers you want to add and collect them into an array.
var mc = new MarkerClusterer(map, markers, mcOptions);
Simple Example
This example will show 100 markers on a map.
var center = new google.maps.LatLng(37.4419, -122.1419);
var options = {
'zoom': 13,
'center': center,
'mapTypeId': google.maps.MapTypeId.ROADMAP
};
var map = new google.maps.Map(document.getElementById("map"), options);
var markers = [];
for (var i = 0; i < 100; i++) {
var latLng = new google.maps.LatLng(data.photos[i].latitude,
data.photos[i].longitude);
var marker = new google.maps.Marker({'position': latLng});
markers.push(marker);
}
var markerCluster = new MarkerClusterer(map, markers);
class Cluster
Constructor
| Constructor | Description |
|---|---|
| Cluster(mc:MarkerClusterer) | Creates a single cluster that manages a group of proximate markers. Used internally, do not call this constructor directly. |
Methods
| Methods | Return Value | Description |
|---|---|---|
| getCenter() | google.maps.LatLng | Returns the center of the cluster. You can call this from a click, mouseover, or mouseout event handler for the MarkerClusterer object. |
| getMarkers() | Array | Returns the array of markers managed by the cluster. You can call this from a click, mouseover, or mouseout event handler for the MarkerClustererobject. |
| getSize() | number | Returns the number of markers managed by the cluster. You can call this from a click, mouseover, or mouseout event handler for the MarkerClustererobject. |
class ClusterIconInfo
This class is an object containing general information about a cluster icon. This is the object that a calculator function returns.
Properties
| Properties | Type | Description |
|---|---|---|
| index | number | The index plus 1 of the element in the styles array to be used to style the cluster icon. |
| text | string | The text of the label to be shown on the cluster icon. |
| title | string | The tooltip to display when the mouse moves over the cluster icon. If this value is undefined or "", title is set to the value of the title property passed to the MarkerClusterer. |
class ClusterIconStyle
This class represents the object for values in the styles array passed to the MarkerClusterer constructor. The element in this array that is used to style the cluster icon is determined by calling the calculator function.
Properties
| Properties | Type | Description |
|---|---|---|
| anchorIcon | Array | The anchor position (in pixels) of the cluster icon. This is the spot on the cluster icon that is to be aligned with the cluster position. The format is [yoffset, xoffset] where yoffset increases as you go down and xoffset increases to the right of the top-left corner of the icon. The default anchor position is the center of the cluster icon. |
| anchorText | Array | The position (in pixels) from the center of the cluster icon to where the text label is to be centered and drawn. The format is [yoffset, xoffset] where yoffsetincreases as you go down from center and xoffset increases to the right of center. The default is [0, 0]. |
| backgroundPosition | string | The position of the cluster icon image within the image defined by url. The format is "xpos ypos" (the same format as for the CSS background-positionproperty). You must set this property appropriately when the image defined by url represents a sprite containing multiple images. Note that the position must be specified in px units. The default value is "0 0". |
| fontFamily | string | The value of the CSS font-family property for the label text shown on the cluster icon. The default value is "Arial,sans-serif". |
| fontStyle | string | The value of the CSS font-style property for the label text shown on the cluster icon. The default value is "normal". |
| fontWeight | string | The value of the CSS font-weight property for the label text shown on the cluster icon. The default value is "bold". |
| height | number | The display height (in pixels) of the cluster icon. Required. |
| textColor | string | The color of the label text shown on the cluster icon. The default value is "black". |
| textDecoration | string | The value of the CSS text-decoration property for the label text shown on the cluster icon. The default value is "none". |
| textSize | number | The size (in pixels) of the label text shown on the cluster icon. The default value is 11. |
| url | string | The URL of the cluster icon image file. Required. |
| width | number | The display width (in pixels) of the cluster icon. Required. |
class MarkerClusterer
This class extends google.maps.OverlayView.
Constructor
| Constructor | Description |
|---|---|
| MarkerClusterer(map:google.maps.Map, opt_markers?:Array.<google.maps.Marker>,opt_options?:MarkerClustererOptions) | Creates a MarkerClusterer object with the options specified inMarkerClustererOptions. |
Methods
| Methods | Return Value | Description |
|---|---|---|
| addMarker(marker:google.maps.Marker,opt_nodraw?:boolean) | None | Adds a marker to the clusterer. The clusters are redrawn unless opt_nodraw is set to true. |
| addMarkers(markers:Array.<google.maps.Marker>,opt_nodraw?:boolean) | None | Adds an array of markers to the clusterer. The clusters are redrawn unless opt_nodraw is set to true. |
| clearMarkers() | None | Removes all clusters and markers from the map and also removes all markers managed by the clusterer. |
| fitMapToMarkers() | None | Fits the map to the bounds of the markers managed by the clusterer. |
| getAverageCenter() | boolean | Returns the value of the averageCenter property. |
| getBatchSizeIE() | number | Returns the value of the batchSizeIE property. |
| getCalculator() | function | Returns the value of the calculator property. |
| getClusterClass() | string | Returns the value of the clusterClass property. |
| getClusters() | Array | Returns the current array of clusters formed by the clusterer. |
| getEnableRetinaIcons() | boolean | Returns the value of the enableRetinaIcons property. |
| getGridSize() | number | Returns the value of the gridSize property. |
| getIgnoreHidden() | boolean | Returns the value of the ignoreHidden property. |
| getImageExtension() | string | Returns the value of the imageExtension property. |
| getImagePath() | string | Returns the value of the imagePath property. |
| getImageSizes() | Array | Returns the value of the imageSizes property. |
| getMarkers() | Array | Returns the array of markers managed by the clusterer. |
| getMaxZoom() | number | Returns the value of the maxZoom property. |
| getMinimumClusterSize() | number | Returns the value of the minimumClusterSize property. |
| getStyles() | Array | Returns the value of the styles property. |
| getTitle() | string | Returns the value of the title property. |
| getTotalClusters() | number | Returns the number of clusters formed by the clusterer. |
| getTotalMarkers() | number | Returns the number of markers managed by the clusterer. |
| getZoomOnClick() | boolean | Returns the value of the zoomOnClick property. |
| removeMarker(marker:google.maps.Marker,opt_nodraw?:boolean) | boolean | Removes a marker from the cluster. The clusters are redrawn unless opt_nodraw is set to true. Returns true if the marker was removed from the clusterer. |
| removeMarkers(markers:Array.<google.maps.Marker>,opt_nodraw?:boolean) | boolean | Removes an array of markers from the cluster. The clusters are redrawn unless opt_nodraw is set to true. Returns true if markers were removed from the clusterer. |
| repaint() | None | Recalculates and redraws all the marker clusters from scratch. Call this after changing any properties. |
| setAverageCenter(averageCenter:boolean) | None | Sets the value of the averageCenter property. |
| setBatchSizeIE(batchSizeIE:number) | None | Sets the value of the batchSizeIE property. |
| setCalculator(calculator:function(Array.<google.maps.Marker>|number)) | None | Sets the value of the calculator property. |
| setClusterClass(clusterClass:string) | None | Sets the value of the clusterClass property. |
| setEnableRetinaIcons(enableRetinaIcons:boolean) | None | Sets the value of the enableRetinaIcons property. |
| setGridSize(gridSize:number) | None | Sets the value of the gridSize property. |
| setIgnoreHidden(ignoreHidden:boolean) | None | Sets the value of the ignoreHidden property. |
| setImageExtension(imageExtension:string) | None | Sets the value of the imageExtension property. |
| setImagePath(imagePath:string) | None | Sets the value of the imagePath property. |
| setImageSizes(imageSizes:Array) | None | Sets the value of the imageSizes property. |
| setMaxZoom(maxZoom:number) | None | Sets the value of the maxZoom property. |
| setMinimumClusterSize(minimumClusterSize:number) | None | Sets the value of the minimumClusterSize property. |
| setStyles(styles:Array.<ClusterIconStyle>) | None | Sets the value of the styles property. |
| setTitle(title:string) | None | Sets the value of the title property. |
| setZoomOnClick(zoomOnClick:boolean) | None | Sets the value of the zoomOnClick property. |
Events
| Events | Arguments | Description |
|---|---|---|
| click | c:Cluster | This event is fired when a cluster marker is clicked. |
| clusteringbegin | mc:MarkerClusterer | This event is fired when the MarkerClusterer begins clustering markers. |
| clusteringend | mc:MarkerClusterer | This event is fired when the MarkerClusterer stops clustering markers. |
| mouseout | c:Cluster | This event is fired when the mouse moves out of a cluster marker. |
| mouseover | c:Cluster | This event is fired when the mouse moves over a cluster marker. |
class MarkerClustererOptions
This class represents the optional parameter passed to the MarkerClusterer constructor. There is no constructor for this class. Instead, this class is instantiated as a javascript object literal.
Properties
| Properties | Type | Description |
|---|---|---|
| averageCenter | boolean | Whether the position of a cluster marker should be the average position of all markers in the cluster. If set to false, the cluster marker is positioned at the location of the first marker added to the cluster. The default value is false. |
| batchSize | number | Set this property to the number of markers to be processed in a single batch when using a browser other than Internet Explorer (for Internet Explorer, use the batchSizeIE property instead). The default value is MarkerClusterer.BATCH_SIZE. |
| batchSizeIE | number | When Internet Explorer is being used, markers are processed in several batches with a small delay inserted between each batch in an attempt to avoid Javascript timeout errors. Set this property to the number of markers to be processed in a single batch; select as high a number as you can without causing a timeout error in the browser. This number might need to be as low as 100 if 15,000 markers are being managed, for example. The default value isMarkerClusterer.BATCH_SIZE_IE. |
| calculator | function | The function used to determine the text to be displayed on a cluster marker and the index indicating which style to use for the cluster marker. The input parameters for the function are (1) the array of markers represented by a cluster marker and (2) the number of cluster icon styles. It returns a ClusterIconInfo object. The default calculator returns a text property which is the number of markers in the cluster and an index property which is one higher than the lowest integer such that 10^i exceeds the number of markers in the cluster, or the size of the styles array, whichever is less. The styles array element used has an index of indexminus 1. For example, the default calculator returns a text value of "125" and an index of 3 for a cluster icon representing 125 markers so the element used in the styles array is 2. A calculator may also return a title property that contains the text of the tooltip to be used for the cluster marker. If title is not defined, the tooltip is set to the value of the title property for the MarkerClusterer. The default value is MarkerClusterer.CALCULATOR. |
| clusterClass | string | The name of the CSS class defining general styles for the cluster markers. Use this class to define CSS styles that are not set up by the code that processes thestyles array. The default value is "cluster". |
| enableRetinaIcons | boolean | Whether to allow the use of cluster icons that have sizes that are some multiple (typically double) of their actual display size. Icons such as these look better when viewed on high-resolution monitors such as Apple's Retina displays. Note: if this property is true, sprites cannot be used as cluster icons. The default value isfalse. |
| gridSize | number | The grid size of a cluster in pixels. The grid is a square. The default value is 60. |
| ignoreHidden | boolean | Whether to ignore hidden markers in clusters. You may want to set this to true to ensure that hidden markers are not included in the marker count that appears on a cluster marker (this count is the value of the text property of the result returned by the default calculator). If set to true and you change the visibility of a marker being clustered, be sure to also call MarkerClusterer.repaint(). The default value is false. |
| imageExtension | string | The extension name for the cluster icon image files (e.g., "png" or "jpg"). The default value is MarkerClusterer.IMAGE_EXTENSION. |
| imagePath | string | The full URL of the root name of the group of image files to use for cluster icons. The complete file name is of the form imagePathn.imageExtension where n is the image file number (1, 2, etc.). The default value is MarkerClusterer.IMAGE_PATH. |
| imageSizes | Array | An array of numbers containing the widths of the group of imagePathn.imageExtension image files. (The images are assumed to be square.) The default value isMarkerClusterer.IMAGE_SIZES. |
| maxZoom | number | The maximum zoom level at which clustering is enabled or null if clustering is to be enabled at all zoom levels. The default value is null. |
| minimumClusterSize | number | The minimum number of markers needed in a cluster before the markers are hidden and a cluster marker appears. The default value is 2. |
| styles | Array | An array of ClusterIconStyle elements defining the styles of the cluster markers to be used. The element to be used to style a given cluster marker is determined by the function defined by the calculator property. The default is an array of ClusterIconStyle elements whose properties are derived from the values for imagePath, imageExtension, and imageSizes. |
| title | string | The tooltip to display when the mouse moves over a cluster marker. (Alternatively, you can use a custom calculator function to specify a different tooltip for each cluster marker.) The default value is "". |
| zoomOnClick | boolean | Whether to zoom the map when a cluster marker is clicked. You may want to set this to false if you have installed a handler for the click event and it deals with zooming on its own. The default value is true. |
class String
Methods
| Methods | Return Value | Description |
|---|---|---|
| trim() | string | IE hack since trim() doesn't exist in all browsers |
