Map integration for famo.us (Google Maps, Leaflet, Open Layers 3 & Mapbox GL)
JavaScript HTML CSS
Permalink
Failed to load latest commit information.
dist Added Mapbox GL support. May 8, 2015
docs Added Mapbox GL support. May 8, 2015
examples Show correct title in photo demos May 8, 2015
.editorconfig Updated eslint & jscs + code accordingly (grunt command now runs with… Jul 24, 2014
.eslintrc Updated eslint & jscs + code accordingly (grunt command now runs with… Jul 24, 2014
.gitignore Updated bower.json and package.json for submition Jun 9, 2014
.gitmodules Remove famous/almond/requirejs/polyfills git submodules (bower_compon… Jun 10, 2014
.jscsrc Updated eslint & jscs + code accordingly (grunt command now runs with… Jul 24, 2014
CONTRIBUTORS.md Added Andreas Hocevar to CONTRIBUTORS.md + minor improvements to readme. May 2, 2015
Gruntfile.js Added scripts for generating 'dist/famous-map-global.js' + made easie… May 3, 2015
LICENSE Initial commit Jun 5, 2014
MapModifier.js Fixed exception in MapModifier when MapView was not yet completely in… May 2, 2015
MapPositionTransitionable.js Fixed various warnings, used smaller copyright headers + bump to v0.1.0 Mar 4, 2015
MapStateModifier.js Fixed various warnings, used smaller copyright headers + bump to v0.1.0 Mar 4, 2015
MapTransition.js Fixed various warnings, used smaller copyright headers + bump to v0.1.0 Mar 4, 2015
MapUtility.js Fixed various warnings, used smaller copyright headers + bump to v0.1.0 Mar 4, 2015
MapView.js Added Mapbox GL support. May 8, 2015
README.md Added screenshot May 8, 2015
bower.json Added Mapbox GL support. May 8, 2015
package.json Added Mapbox GL support. May 8, 2015
screenshot.gif Added screenshot May 8, 2015
template-global.js Added scripts for generating 'dist/famous-map-global.js' + made easie… May 3, 2015
template.js Added scripts for generating 'dist/famous-map-global.js' + made easie… May 3, 2015

README.md

famous-map

Map integration for Famo.us, supporting the following map-providers:

Screenshot

Famous-map makes it possible to add a map-component to the famo.us render-tree. Additionally, famous transitions can be used to pan the map and modifiers can be used to sync the position of renderables with a geographical position.

Demos

note: Hit refresh if the demo doesn't load properly. GitHub sometimes rejects loading famous-map.min.js the first time, but it always loads the next time :?

Getting started

Install using bower or npm:

bower install famous-map

npm install famous-map

Google Maps

Include google-maps in the html file:

<head>
    <script type="text/javascript" src="https://maps.googleapis.com/maps/api/js?v=3.exp&sensor=false"></script>
</head>

Create a google-maps view:

var MapView = require('famous-map/MapView');

var mapView = new MapView({
    type: MapView.MapType.GOOGLEMAPS,
    mapOptions: {
        zoom: 3,
        center: {lat: 51.4484855, lng: 5.451478},
        mapTypeId: google.maps.MapTypeId.TERRAIN
    }
});
this.add(mapView);

// Wait for the map to load and initialize
mapView.on('load', function () {

    // Move across the globe and zoom-in when done
    mapView.setPosition(
        {lat: 51.4484855, lng: 5.451478},
        { duration: 5000 },
        function () {
            mapView.getMap().setZoom(7);
        }
    );
}.bind(this));

IMPORTANT: Don't forget to read this instruction on google maps running on mobile devices.

Leaflet

Include leaflet in the html file:

<head>
    <link rel="stylesheet" href="http://cdn.leafletjs.com/leaflet-0.7.3/leaflet.css" />
    <script src="http://cdn.leafletjs.com/leaflet-0.7.3/leaflet.js"></script>
</head>

Create a leaflet map:

var MapView = require('famous-map/MapView');

var mapView = new MapView({
    type: MapView.MapType.LEAFLET,
    mapOptions: {
        zoom: 3,
        center: {lat: 51.4484855, lng: 5.451478}
    }
});
this.add(mapView);

// Wait for the map to load and initialize
mapView.on('load', function () {

    // Add tile-layer (you can also get your own at mapbox.com)
    L.tileLayer('http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
        attribution: 'Map data &copy; <a href="http://openstreetmap.org">OpenStreetMap</a>'
    }).addTo(mapView.getMap());
}.bind(this));

OpenLayers 3

Include OpenLayers in the html file:

<head>
  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/ol3/3.4.0/ol.min.css" />
  <script src="https://cdnjs.cloudflare.com/ajax/libs/ol3/3.4.0/ol.js"></script>
</head>

Create an open-layers map (uses canvas):

var MapView = require('famous-map/MapView');

var mapView = new MapView({
    type: MapView.MapType.OPENLAYERS3,
    mapOptions: {
        zoom: 3,
        center: {lat: 51.4484855, lng: 5.451478}
    }
});
this.add(mapView);

// Wait for the map to load and initialize
mapView.on('load', function () {

    // Add tile-layer (OSM is just one of many options)
    mapView.getMap().addLayer(new ol.layer.Tile({
        source: new ol.source.OSM()
    }));
}.bind(this));

Mapbox GL

Include Mapbox GL in the html file:

<head>
  <link href='https://api.tiles.mapbox.com/mapbox-gl-js/v0.7.0/mapbox-gl.css' rel='stylesheet' />
  <script src='https://api.tiles.mapbox.com/mapbox-gl-js/v0.7.0/mapbox-gl.js'></script>
</head>

Create an mapbox GL map:

var MapView = require('famous-map/MapView');

var mapView = new MapView({
    type: MapView.MapType.MAPBOXGL,
    mapOptions: {
        zoom: 3,
        center: {lat: 51.4484855, lng: 5.451478}
    }
});
this.add(mapView);

IMPORTANT: Touch events are not yet supported by mapbox-gl-js on mobile, so swiping, pinching, etc.. does not work on your phone or tablet: https://github.com/mapbox/mapbox-gl-js/pull/949

Documentation

To access the underlying map object, use MapView.getMap(). The Map-object is only safely accessible after the 'load' event, because the DOM-object must first be created and the map needs to load.

mapView.on('load', function () {
    var map = mapView.getMap();
    ...
});
LatLng notation

Multiple LatLng formats are supported by the famous-map functions:

var pos = { lat: 57.876, lng: -13.242 }; // object literal
var pos = [57.876, -13.242]; // array: [lat, lng]
var pos = new google.maps.LatLng(57.876, -13.242); // object with .lat() and .lng() functions
Panning the map using transitions

To pan the map using famo.us transitions, use MapView.setPosition(). Transitions are chained, so you can create paths that the map will follow.

mapView.setPosition(
    {lat: 51.4484855, lng: 5.451478},
    {duration: 5000, curve: Easing.outBack},
    function () {
        mapView.getMap().setZoom(7)
    }
);
Linking a renderable to a geographical coordinate on the map

To place a renderable on the map like a marker, use MapModifier or MapStateModifier:

var MapModifier = require('famous-map/MapModifier');

var surface = new Surface({
    size: [50, 50],
    properties: {
        backgroundColor: 'white'
    }
});
var modifier = new Modifier({
    align: [0, 0],
    origin: [0.5, 0.5]
});
var mapModifier = new MapModifier({
    mapView: mapView,
    position: {lat: 51.4484855, lng: 5.451478}
});
this.add(mapModifier).add(modifier).add(surface);
Moving a renderable across the map

MapStateModifier relates to MapModifier in the same way StateModifier relates to Modifier. MapStateModifier makes it possible to change the position from one place to another, using a transitionable. Transitions are chained, so you can create paths that the renderable will follow:

MapStateModifier = require('famous-map/MapStateModifier');

var surface = new Surface({
    size: [50, 50],
    properties: {
        backgroundColor: 'white'
    }
});
var modifier = new Modifier({
    align: [0, 0],
    origin: [0.5, 0.5]
});
var mapStateModifier = new MapStateModifier({
    mapView: mapView,
    position: {lat: 51.4484855, lng: 5.451478}
});
this.add(mapStateModifier).add(modifier).add(surface);

// Animate the renderable across the map
mapStateModifier.setPosition(
    {lat: 52.4484855, lng: 6.451478},
    {method: 'map-speed', speed: 200} // 200 km/h
);
mapStateModifier.setPosition(
    {lat: 50.4484855, lng: 3.451478},
    {duration: 4000}
);
Enable auto-scaling when the map is zoomed in or out

To enable auto-scaling set zoomBase to the zoom-level you wish the renderables to be displayed in its true size. In this example where zoomBase is set to 5, this would mean that at zoom-level 4 its size will 1/4 of its original size:

var mapModifier = new MapModifier({
    mapView: mapView,
    position: {lat: 51.4484855, lng: 5.451478},
    zoomBase: 5
});

To use a different zooming strategy, use zoomScale. ZoomScale can be set to either a number or a getter function:

var mapModifier = new MapModifier({
    mapView: mapView,
    position: {lat: 51.4484855, lng: 5.451478},
    zoomBase: 5,
    zoomScale: 0.5
});

var mapModifier = new MapModifier({
    mapView: mapView,
    position: {lat: 51.4484855, lng: 5.451478},
    zoomBase: 5,
    zoomScale: function (baseZoom, currentZoom) {
        var zoom = currentZoom - baseZoom;
        if (zoom < 0) {
            return 1 / (2 * (Math.abs(zoom) + 1));
        } else {
            return 1 + (2 * zoom);
        }
    }
});
API reference
Class Description
MapView View class which encapsulates a maps object.
MapModifier Stateless modifier which positions a renderable based on a geographical position {LatLng}.
MapStateModifier Modifier which positions a renderable based on a geographical position {LatLng}, using transitions.
MapUtility General purpose utility functions.
MapTransition Transition for moving at a certain speed over the map (km/h).
MapPositionTransitionable Transitionable for geographical coordinates {LatLng}.

Known issues & performance

Google-Maps and Drag/Pinch on mobile devices

Famo.us prevents 'touchmove' events on mobile devices, which causes drag-to-move and pinch-to-zoom to break in Google Maps. To workaround this problem, disable 'app-mode' on mobile devices and instead install the custom MapView touch-handler before the main-context is created:

var Engine = require('famous/core/Engine');
var MapView = require('famous-map/MapView');
var isMobile = require('ismobilejs'); // https://github.com/kaimallea/isMobile

// On mobile, disable app-mode and install the custom MapView
// touch-handler so that Google Maps works.
if (isMobile.any) {
    Engine.setOptions({appMode: false});
    MapView.installSelectiveTouchMoveHandler();
}

var mainContext = Engine.createContext();
...

Resources:

Panning the map & smoothness

Panning the map using MapView.setPosition() and a transition works great, but is not as smooth in all scenarios and on all devices. Panning is smoothest for smaller tile-distances. To see map panning in action at different speeds, view the nyat-cat demo.

Google-Maps and Zoom-levels < 3

At the lower zoom-levels, renderables may not be positioned correctly using Google Maps. This happens when the entire world fits more than once on the surface. In this case, the bounding east and west longitude cannot be determined through the google-maps API, which are required for calculating the x position. To workaround this issue, set mapOptions.minZoom to 3.

Renderables lag and Leaflet

The leaflet-API returns the position and zoom-level after animations have occured. This causes a small lag in the position of renderables when panning the map. When zooming the map, the renderables are re-positioned after the zoom and smooth zooming is therefore not possible and disabled.

Contribute

Feel free to contribute to this project in any way. The easiest way to support this project is by giving it a star.

Contact

© 2014 / 2015 - Hein Rutjes