Merge pull request #231 from domoritz/markercluster

[view/map][m]: Cluster markers to enable better handling of large dataset - thanks to @domoritz.

README.md

@@ -28,10 +28,10 @@ For small bugfixes or enhancements:
 For larger changes:
 
 * Cleanup your code and affected code parts
-* Run the tests from test/index.html in different browsers (at least Chrome and FF)
+* Run the tests from `/test/index.html` in different browsers (at least Chrome and FF)
 * Update the documentation and tutorials where necessary
-* Update _layouts/recline-deps.html if you change required files (e.g. leaflet libraries)
-* Try to build the demos in /demos with jekyll and then check out the demos/multiview/ which utilizes most aspects of Recline
+* Update `/_includes/recline-deps.html` if you change required files (e.g. leaflet libraries)
+* Try to build the demos in `/demos/` with jekyll and then check out the `/demos/multiview/` which utilizes most aspects of Recline
 
 
 ## Changelog
@@ -42,6 +42,8 @@ For larger changes:
 
 Possible breaking changes
 
+* Updated Leaflet to latest version 0.4.4 #220
+* Added marker clustering in map view to handle a large number of markers
 * Dataset.restore method removed (not used internally except from Multiview.restore)
 * Views no longer call render in initialize but must be called client code
 

_includes/recline-deps.html

@@ -2,6 +2,11 @@
   <!--[if lte IE 8]>
   <link rel="stylesheet" href="{{page.root}}vendor/leaflet/0.4.4/leaflet.ie.css" />
   <![endif]-->
+  <link rel="stylesheet" href="{{page.root}}vendor/leaflet.markercluster/MarkerCluster.css">
+  <link rel="stylesheet" href="{{page.root}}vendor/leaflet.markercluster/MarkerCluster.Default.css">
+  <!--[if lte IE 8]>
+  <link rel="stylesheet" href="{{page.root}}vendor/leaflet.markercluster/MarkerCluster.Default.ie.css" />
+  <![endif]-->
   <link rel="stylesheet" href="{{page.root}}vendor/slickgrid/2.0.1/slick.grid.css">
   <link rel="stylesheet" href="{{page.root}}vendor/timeline/20120520/css/timeline.css">
 
@@ -22,6 +27,7 @@
   <script type="text/javascript" src="{{page.root}}vendor/bootstrap/2.0.2/bootstrap.js"></script>
   <script type="text/javascript" src="{{page.root}}vendor/flotr2/flotr2.js"></script>
   <script type="text/javascript" src="{{page.root}}vendor/leaflet/0.4.4/leaflet.js"></script>
+  <script type="text/javascript" src="{{page.root}}vendor/leaflet.markercluster/leaflet.markercluster.js"></script>
   <script type="text/javascript" src="{{page.root}}vendor/slickgrid/2.0.1/jquery-ui-1.8.16.custom.min.js"></script>
   <script type="text/javascript" src="{{page.root}}vendor/slickgrid/2.0.1/jquery.event.drag-2.0.min.js"></script>
   <script type="text/javascript" src="{{page.root}}vendor/slickgrid/2.0.1/slick.grid.min.js"></script>

docs/tutorial-views.markdown

@@ -193,10 +193,16 @@ library and the Recline Map view:
 <!--[if lte IE 8]>
 <link rel="stylesheet" href="vendor/leaflet/0.4.4/leaflet.ie.css" />
 <![endif]-->
+<link rel="stylesheet" href="vendor/leaflet.markercluster/MarkerCluster.css">
+<link rel="stylesheet" href="vendor/leaflet.markercluster/MarkerCluster.Default.css">
+<!--[if lte IE 8]>
+<link rel="stylesheet" href="vendor/leaflet.markercluster/MarkerCluster.Default.ie.css" />
+<![endif]-->
 <link rel="stylesheet" href="css/map.css">
 
 <!-- javascript -->
 <script type="text/javascript" src="vendor/leaflet/0.4.4/leaflet.js"></script>
+<script type="text/javascript" src="vendor/leaflet.markercluster/leaflet.markercluster.js"></script>
 <script type="text/javascript" src="src/view-map.js"></script>
 {% endhighlight %}
 

download.markdown

@@ -79,6 +79,7 @@ Optional dependencies:
 * [Mustache.js](https://github.com/janl/mustache.js/) >= 0.5.0-dev (required for all views)
 * [JQuery Flot](http://code.google.com/p/flot/) >= 0.7 (required for for graph view)
 * [Leaflet](http://leaflet.cloudmade.com/) >= 0.4.4 (required for map view)
+* [Leaflet.markercluster](https://github.com/danzel/Leaflet.markercluster)  as of 2012-09-12 (required for marker clustering)
 * [Verite Timeline](https://github.com/VeriteCo/Timeline/) as of 2012-05-02 (required for the timeline view)
 * [Bootstrap](http://twitter.github.com/bootstrap/) >= v2.0 (default option for CSS and UI JS but you can use your own)
 

src/view.map.js

@@ -53,12 +53,22 @@ my.Map = Backbone.View.extend({
         geomField: null,
         lonField: null,
         latField: null,
-        autoZoom: true
+        autoZoom: true,
+        cluster: false
       },
       options.state
     );
     this.state = new recline.Model.ObjectState(stateData);
 
+    this._clusterOptions = {
+      zoomToBoundsOnClick: true,
+      //disableClusteringAtZoom: 10,
+      maxClusterRadius: 80,
+      singleMarkerMode: false,
+      skipDuplicateAddTesting: true,
+      animateAddingMarkers: false
+    };
+
     // Listen to changes in the fields
     this.model.fields.bind('change', function() {
       self._setupGeometryField();
@@ -82,6 +92,9 @@ my.Map = Backbone.View.extend({
       self.state.set(self.menu.state.toJSON());
       self.redraw();
     });
+    this.state.bind('change', function() {
+      self.redraw();
+    });
     this.elSidebar = this.menu.el;
   },
 
@@ -93,7 +106,7 @@ my.Map = Backbone.View.extend({
   // ### infobox
   //
   // Function to create infoboxes used in popups. The default behaviour is very simple and just lists all attributes.
-  // 
+  //
   // Users should override this function to customize behaviour i.e.
   //
   //     view = new View({...});
@@ -146,14 +159,34 @@ my.Map = Backbone.View.extend({
     }
 
     if (this._geomReady() && this.mapReady){
-      if (action == 'reset' || action == 'refresh'){
+      // removing ad re-adding the layer enables faster bulk loading
+      this.map.removeLayer(this.features);
+      this.map.removeLayer(this.markers);
+
+      var countBefore = 0;
+      this.features.eachLayer(function(){countBefore++;});
+
+      if (action == 'refresh' || action == 'reset') {
         this.features.clearLayers();
+        // recreate cluster group because of issues with clearLayer
+        this.map.removeLayer(this.markers);
+        this.markers = new L.MarkerClusterGroup(this._clusterOptions);
         this._add(this.model.records.models);
       } else if (action == 'add' && doc){
         this._add(doc);
       } else if (action == 'remove' && doc){
         this._remove(doc);
       }
+
+      // enable clustering if there is a large number of markers
+      var countAfter = 0;
+      this.features.eachLayer(function(){countAfter++;});
+      var sizeIncreased = countAfter - countBefore > 0;
+      if (!this.state.get('cluster') && countAfter > 64 && sizeIncreased) {
+        this.state.set({cluster: true});
+        return;
+      }
+
       if (this.state.get('autoZoom')){
         if (this.visible){
           this._zoomToFeatures();
@@ -161,6 +194,11 @@ my.Map = Backbone.View.extend({
           this._zoomPending = true;
         }
       }
+      if (this.state.get('cluster')) {
+        this.map.addLayer(this.markers);
+      } else {
+        this.map.addLayer(this.features);
+      }
     }
   },
 
@@ -216,7 +254,6 @@ my.Map = Backbone.View.extend({
 
         try {
           self.features.addData(feature);
-
         } catch (except) {
           wrongSoFar += 1;
           var msg = 'Wrong geometry value';
@@ -235,7 +272,7 @@ my.Map = Backbone.View.extend({
     });
   },
 
-  // Private: Remove one or n features to the map
+  // Private: Remove one or n features from the map
   //
   _remove: function(docs){
 
@@ -344,7 +381,7 @@ my.Map = Backbone.View.extend({
   //
   _zoomToFeatures: function(){
     var bounds = this.features.getBounds();
-    if (bounds.getNorthEast()){
+    if (bounds && bounds.getNorthEast() && bounds.getSouthWest()){
       this.map.fitBounds(bounds);
     } else {
       this.map.setView([0, 0], 2);
@@ -357,6 +394,7 @@ my.Map = Backbone.View.extend({
   // on [OpenStreetMap](http://openstreetmap.org).
   //
   _setupMap: function(){
+    var self = this;
     this.map = new L.Map(this.$map.get(0));
 
     var mapUrl = "http://otile{s}.mqcdn.com/tiles/1.0.0/osm/{z}/{x}/{y}.png";
@@ -364,12 +402,16 @@ my.Map = Backbone.View.extend({
     var bg = new L.TileLayer(mapUrl, {maxZoom: 18, attribution: osmAttribution ,subdomains: '1234'});
     this.map.addLayer(bg);
 
-    this.features = new L.GeoJSON(null,
-      {onEachFeature: function(feature,layer) {
-        layer.bindPopup(feature.properties.popupContent);
+    this.markers = new L.MarkerClusterGroup(this._clusterOptions);
+
+    this.features = new L.GeoJSON(null,{
+        pointToLayer: function (feature, latlng) {
+          var marker = new L.marker(latlng);
+          marker.bindPopup(feature.properties.popupContent);
+          self.markers.addLayer(marker);
+          return marker;
         }
-        });
-    this.map.addLayer(this.features);
+    });
 
     this.map.setView([0, 0], 2);
 
@@ -442,19 +484,23 @@ my.MapMenu = Backbone.View.extend({
       </div> \
       <div class="editor-options" > \
         <label class="checkbox"> \
-          <input type="checkbox" id="editor-auto-zoom" checked="checked" /> \
+          <input type="checkbox" id="editor-auto-zoom" value="autozoom" checked="checked" /> \
           Auto zoom to features</label> \
+        <label class="checkbox"> \
+          <input type="checkbox" id="editor-cluster" value="cluster"/> \
+          Cluster markers</label> \
       </div> \
       <input type="hidden" class="editor-id" value="map-1" /> \
       </div> \
     </form> \
-',
+  ',
 
   // Define here events for UI elements
   events: {
     'click .editor-update-map': 'onEditorSubmit',
     'change .editor-field-type': 'onFieldTypeChange',
-    'click #editor-auto-zoom': 'onAutoZoomChange'
+    'click #editor-auto-zoom': 'onAutoZoomChange',
+    'click #editor-cluster': 'onClusteringChange'
   },
 
   initialize: function(options) {
@@ -487,10 +533,14 @@ my.MapMenu = Backbone.View.extend({
     }
     if (this.state.get('autoZoom')) {
       this.el.find('#editor-auto-zoom').attr('checked', 'checked');
-    }
-    else {
+    } else {
       this.el.find('#editor-auto-zoom').removeAttr('checked');
     }
+    if (this.state.get('cluster')) {
+      this.el.find('#editor-cluster').attr('checked', 'checked');
+    } else {
+      this.el.find('#editor-cluster').removeAttr('checked');
+    }
     return this;
   },
 
@@ -541,6 +591,10 @@ my.MapMenu = Backbone.View.extend({
     this.state.set({autoZoom: !this.state.get('autoZoom')});
   },
 
+  onClusteringChange: function(e){
+    this.state.set({cluster: !this.state.get('cluster')});
+  },
+
   // Private: Helper function to select an option from a select list
   //
   _selectOption: function(id,value){

test/index.html

@@ -15,6 +15,7 @@
   <script type="text/javascript" src="../vendor/mustache/0.5.0-dev/mustache.js"></script>
   <script type="text/javascript" src="../vendor/bootstrap/2.0.2/bootstrap.js"></script>
   <script type="text/javascript" src="../vendor/leaflet/0.4.4/leaflet-src.js"></script>
+  <script type="text/javascript" src="../vendor/leaflet.markercluster/leaflet.markercluster.js"></script>
   <script type="text/javascript" src="../vendor/slickgrid/2.0.1/jquery-ui-1.8.16.custom.min.js"></script>
   <script type="text/javascript" src="../vendor/slickgrid/2.0.1/jquery.event.drag-2.0.min.js"></script>
   <script type="text/javascript" src="../vendor/slickgrid/2.0.1/slick.grid.min.js"></script>

test/view.map.test.js

@@ -53,7 +53,8 @@ test('_setupGeometryField', function () {
     geomField: null,
     lonField: 'lon',
     latField: 'lat',
-    autoZoom: true
+    autoZoom: true,
+    cluster: false
   };
   deepEqual(view.state.toJSON(), exp);
   deepEqual(view.menu.state.toJSON(), exp);
@@ -129,6 +130,30 @@ test('_getGeometryFromRecord non-GeoJSON', function () {
   });
 });
 
+test('many markers', function () {
+  var data = [];
+  for (var i = 0; i<1000; i++) {
+    data.push({ id: i, lon: 13+3*i, lat: 52+i/10});
+  }
+  var fields = [
+    {id: 'id'},
+    {id: 'lat'},
+    {id: 'lon'}
+  ];
+
+  var dataset = new recline.Model.Dataset({records: data, fields: fields});
+  var view = new recline.View.Map({
+    model: dataset
+  });
+  $('.fixtures').append(view.el);
+  view.render();
+
+  dataset.query();
+
+  equal(view.state.get('cluster'), true);
+  view.remove();
+});
+
 test('Popup', function () {
   var dataset = GeoJSONFixture.getDataset();
   var view = new recline.View.Map({

vendor/leaflet.markercluster/MarkerCluster.Default.css

@@ -0,0 +1,38 @@
+.marker-cluster-small {
+	background-color: rgba(181, 226, 140, 0.6);
+	}
+.marker-cluster-small div {
+	background-color: rgba(110, 204, 57, 0.6);
+	}
+
+.marker-cluster-medium {
+	background-color: rgba(241, 211, 87, 0.6);
+	}
+.marker-cluster-medium div {
+	background-color: rgba(240, 194, 12, 0.6);
+	}
+
+.marker-cluster-large {
+	background-color: rgba(253, 156, 115, 0.6);
+	}
+.marker-cluster-large div {
+	background-color: rgba(241, 128, 23, 0.6);
+	}
+
+.marker-cluster {
+	background-clip: padding-box;
+	border-radius: 20px;
+	}
+.marker-cluster div {
+	width: 30px;
+	height: 30px;
+	margin-left: 5px;
+	margin-top: 5px;
+
+	text-align: center;
+	border-radius: 15px;
+	font: 12px "Helvetica Neue", Arial, Helvetica, sans-serif;
+	}
+.marker-cluster span {
+	line-height: 30px;
+	}

vendor/leaflet.markercluster/MarkerCluster.Default.ie.css

@@ -0,0 +1,22 @@
+ /* IE 6-8 fallback colors */
+.marker-cluster-small {
+	background-color: rgb(181, 226, 140);
+	}
+.marker-cluster-small div {
+	background-color: rgb(110, 204, 57);
+	}
+
+.marker-cluster-medium {
+	background-color: rgb(241, 211, 87);
+	}
+.marker-cluster-medium div {
+	background-color: rgb(240, 194, 12);
+	}
+
+.marker-cluster-large {
+	background-color: rgb(253, 156, 115);
+	}
+.marker-cluster-large div {
+	background-color: rgb(241, 128, 23);
+}
+

vendor/leaflet.markercluster/MarkerCluster.css

@@ -0,0 +1,6 @@
+.leaflet-cluster-anim .leaflet-marker-icon, .leaflet-cluster-anim .leaflet-marker-shadow {
+	-webkit-transition: -webkit-transform 0.25s ease-out, opacity 0.25s ease-in;
+	-moz-transition: -moz-transform 0.25s ease-out, opacity 0.25s ease-in;
+	-o-transition: -o-transform 0.25s ease-out, opacity 0.25s ease-in;
+	transition: transform 0.25s ease-out, opacity 0.25s ease-in;
+	}