LuizArmesto / backbone.leaflet

A map component for Backbone.js

Backbone.Leaflet (0.1.1)

(Disclaimer: This project is in an early development stage. It is not intended to be used in production yet!)

Backbone.Leaflet is a Backbone plugin designed to work with geospatial data using GeoJSON specification, providing an extended model (Backbone.Leaflet.GeoModel) and an extended collection (Backbone.Leaflet.GeoCollection) that accepts and exports GeoJSON data and a couple of views (Backbone.Leaflet.MapView and Backbone.Leaflet.SatelliteView) to display GeoModel instances in a map, using Leaflet.

You should be familiar with both Backbone and Leaflet to get the best use out of this plugin.

Dependencies:

• Backbone 1.1.x and its dependencies
• Leaflet 0.7.x

Backbone.Leaflet.GeoModel

The GeoModel is a Backbone Model to work with GeoJSON.

When using GeoModel the method toJSON will return a JSON object following the GeoJSON format specification. On the other hand you can use either a common JSON or a GeoJSON object with the type "Feature" as an input data. All other methods works as in ordinary Backbone's model.

Creating a GeoModel Instance

var geojsonFeature = {
  "type": "Feature",
  "properties": {
    "name": "Coors Field",
    "amenity": "Baseball Stadium",
    "popupContent": "This is where the Rockies play!"
  },
  "geometry": {
    "type": "Point",
    "coordinates": [-104.99404, 39.75621]
  }
};

var geoModel = new Backbone.Leaflet.GeoModel( geojsonFeature );

Backbone.Leaflet.GeoCollection

The GeoCollection is a Backbone Collection to work with GeoJSON and GeoModel. You can create a new collection using either an array of GeoModels or a GeoJSON object with the type "FeatureCollection". The toJSON method will return a GeoJSON object.

Creating a GeoCollection Instance Using "FeatureCollection" GeoJSON

var geojsonFeatureCollection = {
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [-46.6368, -23.5100]
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [-46.6156, -23.5016]
      }
    }
  ]
};

var geoCollection = new Backbone.Leaflet.GeoCollection( geojsonFeatureCollection );

Backbone.Leaflet.MapView

The MapView is a Backbone View to display GeoCollection on Leaflet map using MapQuest-OSM tiles.

There are some functions that can be overridden to customize the map behavior and appearance.

• getTileLayer() - Function that will be used to get an instance of L.TileLayer. Can be overridden to use another tiles server.
• modelFilter( model ) - Function that receives a model and returns true if the model should be added to map, otherwise false. Can be overridden but is recommended to use the filter option.
• layerStyle( model ) - Function that receives a model and returns the Leaflet style options used to define the layer appearance. Can be overridden but is recommended to use the style option.

Constructor Options

The mapView constructor allows some options.

• collection - GeoCollection instance.
• el - DOM element used to render the map.
• map - Leaflet Map options (optional).
• popup - Leaflet Popup options (optional).
• popupView - Constructor of Backbone view used to render the popup content (optional).
• layer - Leaflet GeoJSON Layer options (optional). It is not recommended to set custom callbacks using this option because this will override some important functions used internally.
• style - Leaflet style options or a function that receives a model and should return a style options object (optional). Prefer using this option instead of override layerStyle function or layer.style option.
• filter - Function that will receive a model and should return trueif the model should be added to map or false if not (optional). Prefer using this option instead of override modelFilter function or layer.filter option.

Creating a Simple Map

Use MapView just like any other Backbone view.

var mapView = new Backbone.Leaflet.MapView({

  el: '#map',

  collection: geoCollection,  // See above how to create a `GeoCollection` instance.

  map: {
    ...  // Leaflet map options (optional).
  }

});

For more informations about map options see the Leaflet documentation.

Delegating Map Events

To delegate map events just define the events property like you usually do but use "map" as selector to Leaflet map events. To delegate Layers (markers, polygons, etc) events use "layer" as selector.

var MyMapView = Backbone.Leaflet.MapView.extend({

  events: {
    'click map': 'onClick',
    'move map': 'onMove',
    'click layer', 'onLayerClick'
  },

  onClick: function ( evt ) {
    ...
  },

  onMove: function ( evt ) {
    ...
  },

  onLayerClick: function ( evt ) {
    var layer = evt.target;  // Get the Leaflet "layer" object.
    var model = this.collection.get( layer );  // Get the Backbone model associated to the "layer".
    ...
  }

});


var myMapView = new MyMapView({
  ...  // View options.
});

For more informations about Leaflet events see the map events reference.

Backbone.Leaflet.SatelliteView

The SatelliteView works similar to MapView, except that uses MapQuest Open Aerial tiles.

Backbone.Leaflet.PopupView

Backbone View used to render the popup content. You can extend this view to create a more complex popup and use the MapView popupView option to use your custom view.

Contributing

Indent your code with 2 spaces, strip trailing whitespace and take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using grunt.

Also, please don't edit files in the "dist" subdirectory as they are generated via grunt. You'll find source code in the "src" subdirectory!

Installing Dependencies

To contribute you will have to install some development dependencies. This assume you already have Node.js and npm installed on your system.

First install Grunt and Bower.

  sudo npm install -g grunt-cli
  sudo npm install -g bower

Now install all dependencies.

  npm install
  bower install

Finally, you will be ready to develop and contribute :)

Testing

Use grunt to test the code.

  grunt test

Building

Use grunt to build.

  grunt build

License

Copyright (c) 2014 Luiz Armesto Licensed under the MIT license.