[#223,tutorial/maps][m]: start of a in-depth map tutorial with instructions on customizing infoboxes and markers.

* Also add to tutorials.html (and refactor that page a bit)

_includes/tutorial-maps-customize.js

@@ -0,0 +1,17 @@
+var $el = $('#map-customize');
+var view = new recline.View.Map({
+  el: $el,
+  model: dataset
+});
+
+view.geoJsonLayerOptions.pointToLayer = function(feature, latlng) {
+  // Look up Record so we can use it to customize size of marker
+  // note that 'this' is specially bound for us to parent view + that feature
+  // stores record cid
+  var record = this.model.records.getByCid(feature.properties.cid);
+  var marker = new L.CircleMarker(latlng, { radius: record.get('x') * 3 });
+  marker.bindPopup(feature.properties.popupContent);
+  return marker;
+}
+view.render();
+

_includes/tutorial-maps-infobox.js

@@ -0,0 +1,14 @@
+// this element will need to exist!
+var $el = $('#map-infobox');
+var view = new recline.View.Map({
+  el: $el,
+  model: dataset
+});
+// record is the recline.Model.Record object
+view.infobox = function(record) {
+  var html = '<h3>' + record.get('country') + ' &ndash; ' + record.get('date') + '</h3>';
+  html += 'id: ' + record.get('id');
+  return html;
+}
+view.render();
+

docs/tutorial-maps.markdown

@@ -0,0 +1,106 @@
+---
+layout: container
+title: Maps - Customizing Maps in Recline - Tutorial
+recline-deps: true
+root: ../
+---
+
+<div class="page-header">
+  <h1>
+    Doing More with the Map View
+    <br />
+    <small>This tutorial goes beyond the <a href="tutorial-views.html">basic
+    views tutorial</a> and shows you how to do more with maps</small>
+  </h1>
+</div>
+
+### Preparing your page
+
+See the instructions in the [basic views tutorial](tutorial-views.html).
+
+### Creating a Dataset
+
+Again like the views tutorial:
+
+Here's some example data We are going to work with:
+
+{% highlight javascript %}
+{% include data.js %}
+var dataset = new recline.Model.Dataset({
+  records: data
+});
+{% endhighlight %}
+
+<script type="text/javascript">
+{% include data.js %}
+var dataset = new recline.Model.Dataset({
+  records: data
+});
+</script>
+
+### General Pointers
+
+Check out the <a href="{{page.root}}/docs/src/view.map.html">Map reference
+(source) docs</a>. In particular this has details of the various state options.
+
+In addition, remember that Recline's map view is just a relatively lightweight
+wrapper around Leaflet. This means that pretty much anything you can do with
+Leaflet you can do with Recline's map. Specifically a `recline.View.Map`
+instance has the following attributes exposed:
+
+    map: the Leaflet map (L.Map)
+    features: Leaflet GeoJSON layer (L.GeoJSON) containing all the features
+
+(Recline converts all records in a dataset that yield geospatial info to a
+GeoJSON feature and adds it to the features layer).
+
+### Customizing the infobox
+
+The default infobox just shows all of the dataset attributes. Usually you'll
+want something a bit nicer. All you need to do is override the infobox
+function. For example, in our case let's make a nicer title and only show some
+data.
+
+{% highlight javascript %}
+{% include tutorial-maps-infobox.js %}
+{% endhighlight %}
+
+<div id="map-infobox">&nbsp;</div>
+
+<script type="text/javascript">
+{% include tutorial-maps-infobox.js %}
+</script>
+
+### Customizing the marker
+
+We're going to show how to replace the default marker with a circular marker.
+Even more exciting, we'll show how to have the marker size vary with an
+attribute of our data. We do the customization by via over-riding the
+pointToLayer function:
+
+{% highlight javascript %}
+{% include tutorial-maps-customize.js %}
+{% endhighlight %}
+
+<div id="map-customize">&nbsp;</div>
+
+<script type="text/javascript">
+{% include tutorial-maps-customize.js %}
+</script>
+
+### Customing features (which aren't points)
+
+Leaflet treats points and features differently. To customize features that
+aren't point we will need to bind to the feature layers featureparse event. As
+the feature layer can get re-rendered you don't do this directly but rather set
+the featureparse function on the recline view. For example, for classic popup
+behaviour:
+
+{% highlight javascript %}
+view.featureparse = function (e) {
+  if (e.properties && e.properties.popupContent) {
+    e.layer.bindPopup(e.properties.popupContent);
+  }
+};
+{% endhighlight %}
+

docs/tutorials.html

@@ -10,6 +10,8 @@ root: ../
   </h1>
 </div>
 
+<h3>Basics &ndash; Using the Dataset and its Friends</h3>
+<hr />
 <div id="tutorials" class="tutorials">
   <div class="row">
     <div class="span4">
@@ -30,17 +32,32 @@ root: ../
   </div>
 </div>
 
-<div id="tutorials" class="tutorials">
+<h3>Backends &ndash; Loading and Storing Data from Remote Sources</h3>
+<hr />
+<div class="tutorials">
   <div class="row">
     <div class="span4">
       <div class="well">
         <h4><a href="tutorial-backends.html">Backends: loading data from Google Docs, Local CSV, DataHub &amp; more ...</a></h4>
       </div>
     </div>
+  </div>
+</div>
+
+<h3>Views &ndash; Grids, Maps, Graphs and More!</h3>
+<hr />
+
+<div class="tutorials">
+  <div class="row">
     <div class="span4">
       <div class="well">
         <h4><a href="tutorial-views.html">Views Quickstart - Grids, Graphs and Maps</a></h4>
       </div>
     </div>
+    <div class="span4">
+      <div class="well">
+        <h4><a href="tutorial-maps.html">Doing more with maps</a></h4>
+      </div>
+    </div>
   </div>
 </div>