Merge pull request #75 from PeterTheOne/update-doc

Update documentation: imagePath option, examples, readme, etc.

CONTRIBUTORS

@@ -12,3 +12,4 @@
 Luke Mahé <[email protected]>
 Brendan Kenny <[email protected]>
 Moisés Arcos <[email protected]>
+Peter Grassberger <[email protected]>

README.md

@@ -8,6 +8,46 @@ A Google Maps JavaScript API v3 library to create and manage per-zoom-level clus
 
 Migrated from the [Google Maps JavaScript API utility libraries on Google Code](https://code.google.com/p/google-maps-utility-library-v3/).
 
+## Usage
+
+Download or clone `markerclusterer.js` and images `m1.png` to `m5.png`, save images in `images` folder.
+
+To use your own custom cluster images just name your images `m[1-5].png` or set the `imagePath` option to the location and name of your images like this: `imagePath: 'customImages/cat'` for images `cat1.png` to `cat5.png`.
+
+index.html
+
+    ...
+
+    <div id="map-container"><div id="map"></div></div>
+    <script src="markerclusterer.js"></script>
+    <script>
+        function initialize() {
+            var center = new google.maps.LatLng(51.5074, 0.1278);
+
+            var map = new google.maps.Map(document.getElementById('map'), {
+              zoom: 3,
+              center: center,
+              mapTypeId: google.maps.MapTypeId.ROADMAP
+            });
+
+            var markers = [];
+            var marker = new google.maps.Marker({
+                position: new google.maps.LatLng(51.5074, 0.1278)
+            });
+            markers.push(marker);
+
+            var options = {
+                imagePath: 'images/m'
+            };
+
+            var markerCluster = new MarkerClusterer(map, markers, options);
+        }
+
+        google.maps.event.addDomListener(window, 'load', initialize);
+    </script>
+    ...
+
+
 ## Live Demos
 
 [![Marker Clusterer Screenshot](https://googlemaps.github.io/js-marker-clusterer/screenshot.png)](https://googlemaps.github.io/js-marker-clusterer/docs/examples.html)

docs/examples.html

@@ -35,9 +35,13 @@ <h1><a name="Marker_Clusterer_Examples" id="Marker_Clusterer_Examples"></a>
 var mc = new MarkerClusterer(map);
 </pre>
 
-     <p>You may also specify a number of options to fine-tune the marker
-        manager's performance. These options are passed via a object.
+     <p>
+         You may also specify a number of options to fine-tune the marker
+         manager's performance. These options are passed via a object.
      </p>
+    <p>
+        The <code>imagePath</code> option needs to be set to the location of your local marker images.
+    </p>
 
 <pre class="prettyprint">
 var center = new google.maps.LatLng(37.4419, -122.1419);
@@ -49,7 +53,7 @@ <h1><a name="Marker_Clusterer_Examples" id="Marker_Clusterer_Examples"></a>
 
 var map = new google.maps.Map(document.getElementById("map"), options);
 
-var mcOptions = {gridSize: 50, maxZoom: 15};
+var mcOptions = {gridSize: 50, maxZoom: 15, imagePath: 'images/m'};
 var mc = new MarkerClusterer(map, [], mcOptions);
 </pre>
 
@@ -67,7 +71,7 @@ <h1><a name="Marker_Clusterer_Examples" id="Marker_Clusterer_Examples"></a>
 
 var map = new google.maps.Map(document.getElementById("map"), options);
 
-var mcOptions = {gridSize: 50, maxZoom: 15};
+var mcOptions = {gridSize: 50, maxZoom: 15, imagePath: 'images/m'};
 var markers = [...]; // Create the markers you want to add and collect them into a array.
 var mc = new MarkerClusterer(map, markers, mcOptions);
 </pre>
@@ -93,7 +97,7 @@ <h2><a name="Marker_Clusterer" id="Marker_Clusterer"></a>A Simple MarkerClustere
   var marker = new google.maps.Marker({'position': latLng});
   markers.push(marker);
 }
-var markerCluster = new MarkerClusterer(map, markers);
+var markerCluster = new MarkerClusterer(map, markers, {imagePath: 'images/m'});
 </pre>
 
     <p><a href="../examples/simple_example.html">View example (simple_example.html)</a></p>

docs/reference.html

@@ -122,6 +122,106 @@ <h3>Constructor</h3>
 
           </tbody>
         </table>
+
+        <h3>Options</h3>
+        <table summary="class MarkerClusterer - Constructor" width="90%">
+
+          <tbody>
+            <tr>
+              <th>Name</th>
+
+              <th>Type</th>
+
+              <th>Description</th>
+            </tr>
+
+            <tr>
+              <td><code>gridSize</code></td>
+              <td><code>number</code></td>
+              <td>The grid size of a cluster in pixels.</td>
+            </tr>
+            <tr>
+              <td><code>maxZoom</code></td>
+              <td><code>number</code></td>
+              <td>The maximum zoom level that a marker can be part of a cluster.</td>
+            </tr>
+            <tr>
+              <td><code>zoomOnClick</code></td>
+              <td><code>boolean</code></td>
+              <td>Whether the default behaviour of clicking on a cluster is to zoom into it.</td>
+            </tr>
+            <tr>
+              <td><code>averageCenter</code></td>
+              <td><code>boolean</code></td>
+              <td>Whether the center of each cluster should be the average of all markers in the cluster.</td>
+            </tr>
+            <tr>
+              <td><code>minimumClusterSize</code></td>
+              <td><code>number</code></td>
+              <td>The minimum number of markers to be in a cluster before the markers are hidden and a count is shown.</td>
+            </tr>
+            <tr>
+              <td><code>styles</code></td>
+              <td><code>object</code></td>
+              <td>An object that has style properties.</td>
+            </tr>
+          </tbody>
+        </table>
+
+        <h3>Styles</h3>
+        <table summary="class MarkerClusterer - Constructor" width="90%">
+
+          <tbody>
+          <tr>
+            <th>Name</th>
+
+            <th>Type</th>
+
+            <th>Description</th>
+          </tr>
+
+          <tr>
+            <td><code>url</code></td>
+            <td><code>string</code></td>
+            <td>The image url.</td>
+          </tr>
+          <tr>
+            <td><code>height</code></td>
+            <td><code>number</code></td>
+            <td>The image height.</td>
+          </tr>
+          <tr>
+            <td><code>width</code></td>
+            <td><code>number</code></td>
+            <td>The image width.</td>
+          </tr>
+          <tr>
+            <td><code>anchor</code></td>
+            <td><code>Array</code></td>
+            <td>The anchor position of the label text.</td>
+          </tr>
+          <tr>
+            <td><code>textColor</code></td>
+            <td><code>string</code></td>
+            <td>The text color.</td>
+          </tr>
+          <tr>
+            <td><code>textSize</code></td>
+            <td><code>number</code></td>
+            <td>The text size.</td>
+          </tr>
+          <tr>
+            <td><code>backgroundPosition</code></td>
+            <td><code>string</code></td>
+            <td>The position of the backgound x, y.</td>
+          </tr>
+          <tr>
+            <td><code>iconAnchor</code></td>
+            <td><code>Array</code></td>
+            <td>The anchor position of the icon x, y.</td>
+          </tr>
+          </tbody>
+        </table>
 
         <h3>Methods</h3>
         <table summary="class MarkerClusterer - Methods" width="90%">

examples/advanced_example.html

@@ -148,7 +148,8 @@
         markerClusterer = new MarkerClusterer(map, markers, {
           maxZoom: zoom,
           gridSize: size,
-          styles: styles[style]
+          styles: styles[style],
+          imagePath: '../images/m'
         });
       }
 

examples/simple_example.html

@@ -50,7 +50,7 @@
           });
           markers.push(marker);
         }
-        var markerCluster = new MarkerClusterer(map, markers);
+        var markerCluster = new MarkerClusterer(map, markers, {imagePath: '../images/m'});
       }
       google.maps.event.addDomListener(window, 'load', initialize);
     </script>

examples/speed_test.js

@@ -137,7 +137,7 @@ speedTest.time = function() {
   $('timetaken').innerHTML = 'timing...';
   var start = new Date();
   if ($('usegmm').checked) {
-    speedTest.markerClusterer = new MarkerClusterer(speedTest.map, speedTest.markers);
+    speedTest.markerClusterer = new MarkerClusterer(speedTest.map, speedTest.markers, {imagePath: '../images/m'});
   } else {
     for (var i = 0, marker; marker = speedTest.markers[i]; i++) {
       marker.setMap(speedTest.map);

src/markerclusterer.js

@@ -43,7 +43,7 @@
  *                cluster.
  *     'zoomOnClick': (boolean) Whether the default behaviour of clicking on a
  *                    cluster is to zoom into it.
- *     'averageCenter': (boolean) Wether the center of each cluster should be
+ *     'averageCenter': (boolean) Whether the center of each cluster should be
  *                      the average of all markers in the cluster.
  *     'minimumClusterSize': (number) The minimum number of markers to be in a
  *                           cluster before the markers are hidden and a count