Pin Clusterer is a small JavaScript layer for clustering pins on Bing maps (version 7.0).
Usage
The Clusterer's constructor accepts two arguments, an instance of the map, and few options.
One of the options must be latlongs, which is an Array of objects
with two properties: latitude and longitude
(view the data used in this example here).
See below how the Clusterer is setup in order to display the pins on the map:
var map = new Microsoft.Maps.Map(document.getElementById('map'), {
credentials: 'Your Bing Map Key here'
}),
pinClusterer = new PinClusterer(map);
map.setView({
center: new Microsoft.Maps.Location(data[0].latitude, data[0].longitude),
zoom : 12
});
// data in this case is an array of objects
// with properties: latitude and longitude
pinClusterer.cluster(data);
The grid size
The Clusterer groups the closest pins together based on a setting called gridSize.
The default value is 60px. The smaller this value, the denser are the clusters.
You can pass this setting with the options when instatiating the Clusterer, but you can change it anytime.
Click here to set the grid size to 40px, and
here to change it back to 60px.
var pinClusterer = new PinClusterer(map, {
gridSize: 40
});
pinCluster.cluster(data);
pinCluster.setOptions({ gridSize: 30 });
pinCluster.cluster();
You can see the grids on the map by setting the debug option to true
(click here to do this live,
or here to turn the debug off):
pinCluster.setOptions({ debug: true });
pinCluster.cluster();
The Pushpin settings
You can change the pin settings, such as its appearance and event handlers, as you would
normally do with a Microsoft.Maps.Pushpin instance.
The Clusterer exposes an event, onClusterToMap,
which you can pass an handler to via the settings.
The event is triggered just before it is added to the map.
The code below hides the text from the pins, which shows the number of locations group within a cluster.
Click here to see this on the map,
or here to show the text again.
pinCluster.setOptions({
onClusterToMap: function (center) {
center.setOptions({ text: '' });
}
});
pinCluster.cluster();
Expanding the clusters
By default, when you click on the clusters that contain more than one pin, it will expand by zooming to the maximum zoom level,
and so showing all the clusters as single pins. Try this now by clicking on any of the clusters on the map with numbers in them.
You can disable this by setting the options below:
pinCluster.setOptions({ clickToZoom: false });
Stylesheets
The Clusterer includes a small CSS file, pin_clusterer.css, which changes the style of the pushpins, to get the effect on the right.
The stylesheet uses a few CSS3 features, such as border-radius, box-shadow, and linear-gradient
to create some nice-looking pins without the need of images.
This is made possible by the fact that the Clusterer adds two classes to the clusters: a general one for all the pins called pin_cluster,
and two specific ones: cluster for clusters with more more than one pin,
and pin for clusters with a single pin.
Please note that adding these styles is absolutely unnecessary for the Clusterer to do its job,
and you can affect the clusters' look as you would do with any Pushpin: when setting the
PushpinOptions when setting the onClusterToMap handler (see above).
Need more information about Bing Maps?
My new book, Learning Bing Maps API, is now out. Email me for a free sample, or order it now from Packt.
References