famous-map
Map component for Famo.us, supporting the following map-providers:
- Google Maps
- Leaflet.js (OpenStreetMap)
- OpenLayers 3 (any base map)
- Mapbox GL
Famous-map makes it possible for adding 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:
Create a google-maps view:
var MapView = ; var mapView = type: MapViewMapTypeGOOGLEMAPS mapOptions: zoom: 3 center: lat: 514484855 lng: 5451478 mapTypeId: googlemapsMapTypeIdTERRAIN ;this; // Wait for the map to load and initializemapView;
IMPORTANT: Don't forget to read this instruction on google maps running on mobile devices.
Leaflet
Include leaflet in the html file:
Create a leaflet map:
var MapView = ; var mapView = type: MapViewMapTypeLEAFLET mapOptions: zoom: 3 center: lat: 514484855 lng: 5451478 ;this; // Wait for the map to load and initializemapView;
OpenLayers 3
Include OpenLayers in the html file:
Create an open-layers map (uses canvas):
var MapView = ; var mapView = type: MapViewMapTypeOPENLAYERS3 mapOptions: zoom: 3 center: lat: 514484855 lng: 5451478 ;this; // Wait for the map to load and initializemapView;
Mapbox GL
Include Mapbox GL in the html file:
Create an mapbox GL map:
var MapView = ; var mapView = type: MapViewMapTypeMAPBOXGL mapOptions: zoom: 3 center: lat: 514484855 lng: 5451478 ;this;
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;
LatLng notation
Multiple LatLng formats are supported by the famous-map functions:
var pos = lat: 57876 lng: -13242 ; // object literalvar pos = 57876 -13242; // array: [lat, lng]var pos = 57876 -13242; // 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;
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 = ; var surface = size: 50 50 properties: backgroundColor: 'white' ;var modifier = align: 0 0 origin: 05 05;var mapModifier = mapView: mapView position: lat: 514484855 lng: 5451478;this;
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 = ; var surface = size: 50 50 properties: backgroundColor: 'white' ;var modifier = align: 0 0 origin: 05 05;var mapStateModifier = mapView: mapView position: lat: 514484855 lng: 5451478;this; // Animate the renderable across the mapmapStateModifier;mapStateModifier;
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 = mapView: mapView position: lat: 514484855 lng: 5451478 zoomBase: 5;
To use a different zooming strategy, use zoomScale. ZoomScale can be set to either a number or a getter function:
var mapModifier = mapView: mapView position: lat: 514484855 lng: 5451478 zoomBase: 5 zoomScale: 05; var mapModifier = mapView: mapView position: lat: 514484855 lng: 5451478 zoomBase: 5 { var zoom = currentZoom - baseZoom; if zoom < 0 return 1 / 2 * Math + 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 = ;var MapView = ;var isMobile = ; // https://github.com/kaimallea/isMobile // On mobile, disable app-mode and install the custom MapView// touch-handler so that Google Maps works.if isMobileany Engine; MapView; var mainContext = Engine;...
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
- @IjzerenHein
- http://www.gloey.nl
- hrutjes@gmail.com (for hire)
© 2014 / 2015 - Hein Rutjes