--- layout: api title: v0.6.4 categories: api navigation: version: v0.6.4 navigation: - title: mapbox.map items: - map.smooth - map.center - map.zoom - map.centerzoom - map.getExtent - map.setExtent - map.setZoomRange - map.setPanLimits - map.setSize - map.zoomBy - map.zoomByAbout - map.panBy - map.draw - map.requestRedraw - map.refresh - Separator: Properties - map.coordinate - map.dimensions - map.parent - Separator: Conversions - map.pointLocation - map.pointCoordinate - map.locationPoint - map.locationCoordinate - map.coordinatePoint - map.coordinateLocation - Separator: Layer management - map.addLayer - map.addTileLayer - map.removeLayer - map.removeLayerAt - map.disableLayer - map.disableLayerAt - map.enableLayer - map.enableLayerAt - map.getLayer - map.getLayers - map.getLayerAt - Separator: Easing - map.ease - Separator: User interface - map.ui - map.ui.fullscreen - map.ui.hash - map.ui.zoombox - map.ui.zoomer - map.ui.attribution - map.ui.legend - map.ui.pointselector - map.ui.boxselector - map.ui.refresh - Separator: Interaction - map.interaction - map.interaction.auto - map.interaction.refresh - Separator: Events - map.addCallback - map.removeCallback - Event "zoomed" - Event "panned" - Event "resized" - Event "extentset" - Event "drawn" - title: mapbox.load items: - title: mapbox.auto items: - title: mapbox.layer items: - layer.id - layer.named - layer.url - layer.tilejson - layer.composite - layer.parent - title: mapbox.markers.layer items: - markers.named - markers.factory - markers.features - markers.add_feature - markers.sort - markers.filter - markers.key - markers.url - markers.id - markers.csv - markers.extent - markers.addCallback - markers.removeCallback - title: mapbox.markers.interaction items: - interaction.hideOnMove - interaction.showOnHover - interaction.exclusive - interaction.formatter - title: mapbox.ease items: - ease.map - ease.from - ease.to - ease.zoom - ease.optimal - ease.location - ease.t - ease.future - ease.easing - ease.path - ease.run - ease.running - ease.stop ---
Maps are the central element of the Javascript API - the map object manages tile layers, contains UI elements, and provides many types of interactivity.
Create a map on the current page.
Arguments:
element
must be the id
of an element on the page, or an element itself.
Typically maps are created within <div>
elements. This element should have a
size: whether specified with external CSS or an inline style like
style="width:600px;height:400px"
layers
can be a layer created with mapbox.layer()
, an array of such layers, or omitteddimensions
can be an object with x
and y
attributes representing the width and height in pixelseventHandlers
can be an array of event handlers, including any of the following:easey_handlers.DragHandler()
easey_handlers.DoubleClickHandler()
easey_handlers.MouseWheelHandler()
easey_handlers.TouchHandler()
MM.DragHandler()
MM.DoubleClickHandler()
MM.MouseWheelHandler()
MM.TouchHandler()
Returns a map object, which has the following methods:
Example:
// for this to work, you'll need an element like
// <div id="map"></div> on your page
var map = mapbox.map('map');
Enable or disable inertial panning on maps. By default, maps smoothly pan and zoom with inertia.
Arguments:
value
must be true
or false
to set whether the map uses inertia.Returns the map object.
Example:
map.smooth(false); // disable inertial panning
Center the map on a geographical location, or get its current center.
Arguments:
centerpoint
can be an object with lat
and lon
values, like { lat: 10, lon: -88 }
, or
ommitted to get the map's current locationanimate
can be true
to animate the map's movement, or omitted to move immediatelyReturns the map object if arguments are given, the map's center location (in the same form as
specified in centerpoint
) otherwise.
Example:
// center the map on Manhattan
map.center({ lat: 40.74, lon: -73.98);
Set the map's zoom level, or get its current zoom level.
Arguments:
zoom
can be zoom level in the range supported by the map's layers (an integer from 0-20, typically),
or omitted to get the current zoom level..animate
can be true
to animate the map's movement, or omitted to move immediately.Returns the map object if arguments are given, the map's current zoom level otherwise.
Example:
// zoom to z10 and animate the transition
map.zoom(10, true);
Set the map's zoom level and centerpoint simultaneously. Especially with the third argument, animate
,
set to true
, this allows for a better animation effect.
Arguments:
centerpoint
can be an object with lat
and lon
values, like { lat: 10, lon: -88 }
zoom
must be zoom level in the range supported by the map's layers (an integer from 0-20, typically)animate
can be true
to animate the map's movement, or omitted to move immediately.Returns the map object.
Example:
// Center the map on Washington, DC, at zoom level 5
map.centerzoom({ lat: 38.9, lon: -77.03 }, 5);
Get the extent of the currently visible area.
Returns an instance of MM.Extent
.
Modify the center and zoom of the map so that the provided extent is visible. This can be useful because extents - the corners of the map - can implicitly cause the map to 'show the whole world' regardless of screen size.
Arguments:
extent
can be an instance of MM.Extent
, or an array of two locations.precise
cab be true
or false
. If true, resulting zoom levels may be fractional. (By default, the map's zoom level is rounded down to keep tile images from blurring.)Returns the map object.
Example:
// using an extent object:
map.setExtent(new MM.Extent(80, -170, -70, 170));
// this call can also be expressed as:
map.setExtent([{ lat: 80, lon: -170 }, { lat: -70, lon: 170 }]);
Set the map's minimum and maximum zoom levels.
Arguments:
minZoom
is the minimum zoom levelmaxZoom
is the maximum zoom levelReturns the map object.
Example:
map.setZoomRange(3, 17);
Set the map's panning limits.
Arguments:
locations
must be either an instance of MM.Extent or an array of two locations in
{ lat: 0, lon: 0 }
form. The order of locations doesn't matter - they're sorted internally.Returns the map object.
Example:
map.setPanLimits([{ lat: -20, lon: 0 }, { lat: 0, lon: 20 }]);
// or with an Extent object
map.setPanLimits(new MM.Extent(0, -20, -20, 0));
Set the map's dimensions. This sets map.autoSize
to false to prevent further automatic resizing.
Arguments:
dimensions
is an object with x
and y
properties representing the map's new dimensions in pixels.Returns the map object.
Change zoom level by the provided offset.
Arguments:
zoomOffset
is the amount to zoom by. Positive offsets zoom in. Negative offsets zoom out.Returns the map object.
Example:
// zoom in by one zoom level
map.zoomBy(1);
// zoom out by two zoom levels
map.zoomBy(-2);
Change the zoom level by the provided offset, while maintaining the same location at the provided point. This is used by MM.DoubleClickHandler
.
zoomOffset
is the amount to zoom by. Positive offsets zoom in. Negative offsets zoom out.point
is the point on the map that maintains its current location.Returns the map object.
Pan by the specified distances.
Arguments:
x
the distance to pan horizontally. Positive values pan right, negative values pan left.y
the distance to pan vertically. Positive values pan down, negative values pan up.Returns the map object.
Example:
// pan right and down by one pixel
map.panBy(1, 1);
Redraw the map and its layers. First, the map enforces its coordLimits on its center and zoom. If autoSize is true, the map's dimensions are recalculated from its parent. Lastly, each of the map's layers is drawn.
Request a "lazy" call to draw in 1 second. This is useful if you're responding to lots of user input and know that you'll need to redraw the map eventually, but not immediately.
Refreshes map.ui and map.interaction to reflect any layer changes.
The map's current center coordinate.
An object with x
and y
attributes expressing the dimensions of the map in pixels.
The DOM element containing the map.
Convert a screen point to a location (longitude and latitude).
Arguments:
point
is an instance of MM.Point
or an object with x
and y
properties.Returns an object with lat
and lon
properties indicating the latitude
and longitude of the point on the globe.
Example:
// get the geographical location of the top-left corner of the map
var top_left = map.pointLocation({ x: 0, y: 0});
Convert a screen point to a tile coordinate.
Arguments:
point
is an instance of MM.Point
or an object with x
and y
properties.Returns an instance of MM.Coordinate
- an object with column
, row
,
and zoom
properties indicating the coordinate of the point. The zoom
of
the point will be same as the current zoom level of the map.
Example:
// get the coordinate location of the top-left corner of the map
var top_left = map.coordinateLocation({ x: 0, y: 0});
Convert a location to a screen point.
Arguments:
location
is an instance of MM.Location
or an object with lat
and lon
properties.Returns an instance of MM.Point
.
Convert a location to a tile coordinate.
Arguments:
location
is an instance of MM.Location
or an object with lat
and lon
properties.Returns an instance of MM.Coordinate
.
Convert a tile coordinate to a screen point.
Arguments:
coordinate
is an instance of MM.Coordinate
.Returns an instance of MM.Point
.
Convert a tile coordinate to a location (longitude and latitude).
Arguments:
coordinate
is an instance of MM.Coordinate
.Returns and instance of MM.Location
.
Add a layer to the map, above other layers.
Arguments:
layer
is a layer object, such as an instance of mapbox.layer()
or mapbox.markers.layer()
.Returns the map object.
Example:
// add a layer to the map
map.addLayer(mapbox.layer().id('examples.map-dg7cqh4z'));
Add a tile layer to the map, below any marker layers to prevent them from being covered up.
layer
is a layer object, such as an instance of mapbox.layer()
.Returns the map object.
Remove the provided layer from the map.
Arguments:
layer
is a layer, or the name of a layer, currently added to the map.Returns the map object.
Remove the layer at the provided index.
index
is a non-negative integer.Returns the map object.
Disable a layer. Disabled layers maintain their position, but do not get drawn.
Arguments:
layer
is the name of a layer currently added to the map.Returns the map object.
Disable a layer at the provided index. Disabled layers maintain their position, but do not get drawn.
Arguments:
index
is a non-negative integer representing the position of the layer.Returns the map object.
Example:
// disable the topmost layer in the map
map.disableLayerAt(0);
Enable a previously disabled layer.
Arguments:
layer
is the name of a layer currently added to the map.Returns the map object.
Enable the layer at the provided index.
Arguments:
index
is a non-negative integer representing the position of the layer to be enabled.Returns the map object.
Get a layer by name.
Arguments:
name
is the name of a layer.Returns the layer object.
Returns a list the map's layers.
Get the layer at the provided index.
Arguments
index
can be a non-negative integer.Returns a layer.
This is an instance of mapbox.ease attached to the map for convenience. For full documentation take a look at mapbox.ease.
Example:
map.ease.location({ lat: 10, lon: -88 }).zoom(5).optimal();
The API provides a set of UI elements that can be freely mixed & matched, as well as styled
beyond the default (provided in the mapbox.css
stylesheet).
Maps created with mapbox.map
have an array of pre-initialized UI elements at .ui
.
All UI elements support the simple operations .add()
and .remove()
to add &
remove them from the map.
Add the UI element to the map. Add the HTML elements that the UI element manages (if any) to the map element, and bind any events.
Example:
// enable the zoomer control. adds + and - buttons to the map
map.ui.zoomer.add();
Remove the UI element from the map. Removes the HTML elements from the map, if any, and removes listeners, if any.
// remove the fullscreen control from the map visually and functionally
map.ui.fullscreen.remove();
For applicable elements (zoomer, attribution, legend, fullscreen), returns the DOM element this control exposes.
Add a link that can maximize and minimize the map on the browser page
Add the map's changing position to the URL, making map locations linkable
Add the ability to zoom into the map by shift-clicking and dragging a box, to which the map zooms
Add zoom in and zoom out buttons to map
Add an element with attribution information to the map
Add an element with legend information to map
Allow simple location selection on the map: clicking without dragging will select a point, and notify listeners with the new list of points.
Adds a callback that is called on changes to the pointselector contents.
Arguments:
event
is a string of the event you want to bind the callback tocallback
is a funcion that is called on the event specified by event
Event should be a String which is one of the following:
change
: whenever points are added or removedCallback is a Function that is called with arguments depending on what event
is bound:
drawn
: the layer objectlocations
: a list of locations currently selectedReturns the pointselector
Remove a callback bound by .addCallback(event, callback)
.
Arguments:
event
is a string of the event you want to bind the callback to
This must be the same string that was given in addCallback
callback
is a funcion that is called on the event specified by event
.
This must be the same function as was given in addCallback
.
Returns the pointselector
Allow extents to be selected on the map.
Adds a callback that is called on changes to the boxselector contents.
Arguments:
event
is a string of the event you want to bind the callback tocallback
is a funcion that is called on the event specified by event
Event should be a String which is one of the following:
change
: whenever an extent is selectedCallback is a Function that is called with arguments depending on what event
is bound:
drawn
: the layer objectextent
: the currently selected extentReturns the boxselector
Remove a callback bound by .addCallback(event, callback)
.
Arguments:
event
is a string of the event you want to bind the callback to
This must be the same string that was given in addCallback
callback
is a funcion that is called on the event specified by event
.
This must be the same function as was given in addCallback
.
Returns the boxselector
Refresh legend and attribution to reflect layer changes, merging and displaying legends and attribution for all enabled layers.
Returns the ui object.
Interaction is what we call interactive parts of maps that are created with the powerful tooltips & regions system in TileMill. Under the hood, it's powered by the open UTFGrid specification.
Enable default settings - animated tooltips - for interaction with the map.
This internally calls interaction.refresh()
to set the interactivity for the top layer.
Returns the interaction control
Example:
var interaction = mapbox.interaction()
.map(map)
.auto();
Refresh interactivity control to reflect any layer changes.
If auto
has not been called, this function will not change anything.
Returns the interaction control
Add a callback for a specific event type. Event types are listed further down.
Arguments:
event
is a string such as "zoomed" or "drawn".callback
is function that gets called when the event is triggered.Returns the map object.
Remove a previously added callback.
Arguments:
event
is the event type to remove the callback for.callback
is the callback to be removed.Returns the map object.
Fires when the map's zoom level changes. Callbacks receive two arguments:
map
is the map object.zoomOffset
is the difference between zoom levels. Get the current zoom with map.zoom()
.Example:
map.addCallback("zoomed", function(map, zoomOffset) {
console.log("Map zoomed by", zoomOffset);
});
Fires when the map has been panned. Callbacks receive two arguments:
map
is the map object.panOffset
is a two-element array in the form of [dx, dy]
.Example:
map.addCallback("panned", function(map, panOffset) {
console.log("map panned by x:", panOffset[0], "y:", panOffset[1]);
});
Fires when the map has been resized. Callbacks receive two arguments:
map
is the map object.dimensions
is a new MM.Point
with the map's new dimensions.Example:
map.addCallback("resized", function(map, dimensions) {
console.log("map dimensions:", dimensions.x, "y:", dimensions.y);
});
Fires when the map's extent is set. Callbacks receive two arguments:
map
is the map object.extent
is an instance of MM.Extent
.Example:
map.addCallback("extentset", function(map, extent) {
console.log("Map's extent set to:", extent);
});
Fires when the map is redrawn. Callbacks receive one argument:
map
is the map object.Example:
map.addCallback("drawn", function(map) {
console.log("map drawn!");
});
To load information about a certain map you've created on MapBox, we provide mapbox.load
and
mapbox.auto
, which pull the TileJSON file from a server and
auto-instantiate many of its features.
Load layer definitions and other map information from MapBox Hosting.
Arguments:
url
can be either be a full URL to a TileJSON file, like
http://a.tiles.mapbox.com/v3/tmcw.map-hehqnmda.jsonp
, or a bare id, like
tmcw.map-hehqnmda
, which will get expanded to the former. This can also
accept an array of urls in the same format.callback
must be a function that receives either a single object with details
or an array of objects if an array of map ids was given as the first argument.
{
zoom: ZOOM_LEVEL,
center: CENTER,
// like you could create with mapbox.layer()
layer: TILE_LAYER,
// if present, like you would create with mapbox.markers()
markers: MARKERS_LAYER
}
Example:
<div id='map' style='width:500px;height:400px;'></div>
<script>
mapbox.load('tmcw.map-hehqnmda', function(o) {
var map = mapbox.map('map');
map.addLayer(o.layer);
});
</script>
Load and create a map with sensible defaults.
Arguments:
element
must be the id
of an element on the page, or an element itself. Typically maps are created within <div>
elementsurl
must be a TileJSON URL, the id of a MapBox map, multiple IDs and URLs in an array.callback
if specified, receives the map as its first argument, and the same object as mapbox.load
as the second argument. It is called after all resources have been loaded and the map is complete.Returns undefined
: this is an asynchronous function without a useful return value.
Example:
<div id='map' style='width:500px;height:400px;'></div>
<script>
mapbox.auto('map', 'http://a.tiles.mapbox.com/v3/tmcw.map-hehqnmda.jsonp');
</script>
mapbox.layer
is a fast way to add layers to your map without having to deal with complex configuration.
You can add a tiled layer to your map with mapbox.layer()
, a simple interface to
layers from MapBox Hosting and elsewhere.
Returns a layer object, which has the following methods:
Get or set the layer ID, which corresponds to a MapBox map.
Arguments:
id
can be the id of a MapBox map, or omitted to get the current id
value.
This also calls layer.named() setting
the name to be the same as the id - call named()
to reset it. For instance, if you were trying
to add the map at https://tiles.mapbox.com/tmcw/map/map-hehqnmda
, you could create this layer like so:callback
, if provided, is called after the layer has been asynchronously loaded from MapBox.
It is called with on argument, the layer object.Returns the layer object if arguments are given, the layer's id
otherwise.
Example:
var layer = mapbox.layer().id('map-hehqnmda');
Get or set the name of the layer, as referred to by the map.
Arguments:
name
can be a new name to call this layerReturns the layer object if arguments are given, the layer's name
otherwise.
Pull a layer from a server besides MapBox Hosting that supports TileJSON, like a self-hosted TileStream.
Arguments:
url
can be a string value that is a fully-formed URL, or omitted to get the URL from which
this layer was sourced.callback
, if provided, is called with one argument, the layer object, after the
TileJSON information has been asynchronously loaded.Returns the layer object if arguments are given, the pulled URL otherwise.
Example:
var layer = mapbox.layer().url('http://a.tiles.mapbox.com/v3/tmcw.map-hehqnmda.jsonp');
Set layer options directly from a TileJSON object.
Arguments:
tilejson
must be a TileJSON object as a Javascript object.Returns the layer object if arguments are given, the layer's TileJSON settings otherwise.
Enable or disable compositing layers together on MapBox hosting. Compositing combines multiple tile images into one layer of blended images, increasing map performance and reducing the number of requests the browser needs to make.
enabled
must be either true or false.Returns the layer object.
The layer's parent DOM element.
mapbox.markers
is a markers library that makes it easier to add HTML elements
on top of maps in geographical locations and interact with them. Internally,
markers are stored as GeoJSON objects, though
interfaces through CSV and simple Javascript are provided.
mapbox.markers.layer()
creates a
new layer into which markers can be placed and which can be added to
a map with map.addLayer()
Set the name of this markers layer. The default name for a markers
layer
is 'markers'
Arguments:
name
if given, must be a string.Returns the layer object if a new name is provided, otherwise the layer's existing name if it is omitted.
Define a new factory function, and if the layer already has points added to it,
re-render them with the new factory. Factory functions are what turn GeoJSON feature
objects into HTML elements on the map. Due to the way that markers allows multiple
layers of interactivity, factories
that want their elements to be interactive must either set .style.pointerEvents = 'all'
on
them via Javascript, or have an equivalent CSS rule with pointer-events: all
that affects
the elements.
Arguments:
factoryfunction
should be a function that takes a
GeoJSON feature object
and returns an HTML element,
or omitted to get the current value.Returns the layer object if a new factory function is provided, otherwise the layer's existing factory function
Set the contents of a markers layer: run the provided features through the filter function and then through the factory function to create elements for the map. If the layer already has features, they are replaced with the new features. An empty array will clear the layer of all features.
Arguments:
features
can be a array of GeoJSON feature objects,
or omitted to get the current value.Returns the layer object if a new array of features is provided, otherwise the layer's features
Add a single GeoJSON feature object to the layer.
Arguments:
features
must be a single GeoJSON feature objectReturns the layer object
Example:
var markerLayer = mapbox.markers.layer();
var newfeature = {
geometry: { coordinates: [-77, 37.9] },
properties: { }
};
// add this single new feature
markerLayer.add_feature(newfeature);
// This call is equivalent to
markerLayer.features(markerLayer.features().concat([x]));
Set the sorting function for markers in the DOM.
Markers are typically sorted in the DOM in order for them to correctly visually overlap. By default,
this is a function that sorts markers by latitude value - geometry.coordinates[1]
.
Arguments:
sortfunction
can be a function that takes two GeoJSON feature objects and returns a number indicating
sorting direction - fulfilling the Array.sort
interface, or omitted to get the current value.Returns the layer object if a new function is specified, otherwise the current function used to sort.
Example: // The default sorting function is: layer.sort(function(a, b) { return b.geometry.coordinates[1] - a.geometry.coordinates[1]; });
Set the layer's filter function and refilter features. Markers can also be filtered before appearing on
the map. This is a purely presentational filter -
the underlying features, which are accessed by markers.features()
,
are unaffected. Setting a new filter can therefore cause points to be
displayed which were previously hidden.
Arguments:
filterfunction
can be a function that takes a GeoJSON feature object and returns true
to allow it to be displayed or false
to hide it, or omitted to get the current valueReturns the layer object if a new function is specified, otherwise the current function used to filter.
Example:
// The default filter function is:
layer.filter(function() { return true; });
Set the key getter for this layer. The key getter is a funcion that takes a GeoJSON feature
and returns a unique id for that feature. If this is provided, the layer can optimize repeated
calls to markers.features()
for animation purposes, since updated markers will not be recreated,
only modified.
Arguments:
keyfunction
must be a function that takes a GeoJSON object and returns a unique ID for it
that does not change for the same features on repeated callsReturns the layer object if a new function is specified, otherwise the current function used to get keys.
Example:
// The default id function is:
var _seq = 0;
layer.key(function() { return ++_seq; });
// Thus this function always returns a new id for any feature. If you had
// features that do have an id attribute, a function would look like
layer.key(function(f) { return f.properties.id; });
Load features from a remote GeoJSON file into the layer.
Arguments:
url
should be a URL to a GeoJSON file on a server. If the server is remote, the
GeoJSON file must be served with a .geojsonp
extension and respond to the JSONP callback grid
.callback
, if provided, is optional and should be a callback that is called after the request finishes,
with the error (if encountered), features array (if any) and the layer instance as arguments.
If an error is encountered, .url()
will not call .features()
, since this would likely
clear the features array.Returns the markers layer or the current URL given if no url
argument
is provided.
Load markers from a MapBox layer.
Arguments:
layerid
must be the ID of a layer, like user.map-example
callback
can be a callback that fires after the request finishes, and behaves
the same as the callback in markers.url
Returns the markers layer.
Convert a string of CSV data into GeoJSON
and set layer to show it as features.
If it can find features in the CSV file, the markers.features()
of the layer are set to them - otherwise it will throw an error about not finding headers.
Arguments:
csvstring
must be a string of CSV data. This method returns the markers
layer. The CSV file must include columns beginning with lat
and lon
in any
case (Latitude, latitude, lat are acceptable).Returns the markers layer
Get the extent of all of the features provided.
Returns an array of two { lat: 23, lon: 32 }
objects compatible with
the map.extent()
call. If there are no
features, the extent is set to Infinity
in all directions, and if there is one feature, the extent is set
to its point exactly.
Add a callback that is called on certain events by this layer. These are primarily
used by mapbox.markers.interaction
,
but otherwise useful to support more advanced bindings
on markers layers that are bound at times when the markers layer object may not
be added to a map - like binding to the map's panned
event to clear tooltips.
Arguments:
event
is a string of the event you want to bind the callback tocallback
is a funcion that is called on the event specified by event
Event should be a String which is one of the following:
drawn
: whenever markers are drawn - which includes any map movementmarkeradded
: when markers are added anewCallback is a Function that is called with arguments depending on what event
is bound:
drawn
: the layer objectmarkeradded
: the new markerReturns the markers layer
Remove a callback bound by .addCallback(event, callback)
.
Arguments:
event
is a string of the event you want to bind the callback to
This must be the same string that was given in addCallback
callback
is a funcion that is called on the event specified by event
.
This must be the same function as was given in addCallback
.
Returns the markers layer
Bind interaction, hovering and/or clicking markers and seeing their details, and customizable through its methods. This supports both mouse & touch input.
Adds tooltips to your markers, for when a user hovers over or taps the features.
Arguments:
markerslayer
must be a markers layer.Returns an interaction
instance which provides methods for customizing how the layer behaves.
Determine whether tooltips are hidden when the map is moved.
The single argument should be true
or false
or not given in order to retrieve the current value.
Arguments:
value
must be true or false to activate or deactivate the modeReturns the interaction instance.
Determine whether tooltips are shown when the user hovers over them.
The single argument should be true
or false
or not given in order to retrieve the current value.
Arguments:
value
must be true or false to activate or deactivate the modeReturns the interaction instance.
Determine whether a single popup should be open at a time, or unlimited.
The single argument should be true
or false
or not given in order to retrieve the current value.
Arguments:
value
must be true or false to activate or deactivate the modeReturns the interaction instance.
Set or get the formatter function, that decides how data goes from being in a feature's properties
to
the HTML inside of a tooltip. This is a getter setter that takes a Function as its argument.
Arguments:
formatterfunction
: a new function that takes GeoJSON features as input and returns
HTML suitable for tooltips, or omitted to get the current value.Returns the interaction instance if a new formatter function is provided, otherwise the current formatter function
Example:
// The default formatter function
interaction.formatter(function(feature) {
var o = '', props = feature.properties;
if (props.title) {
o += '<h1 class="marker-title">' + props.title + '</h1>';
}
if (props.description) {
o += '<div class="marker-description">' + props.description + '</div>';
}
if (typeof html_sanitize !== undefined) {
o = html_sanitize(o,
function(url) {
if (/^(https?:\/\/|data:image)/.test(url)) return url;
},
function(x) { return x; });
}
return o;
});
Easing is moving from one point or zoom to another in a fluid motion, instead of just 'popping' from place to place. It's useful for map-based storytelling, since users get a better idea of geographical distance.
Returns an easey object, which has the following methods:
Specify the map to be used.
Arguments:
map
is an instance of mapbox.map()
or MM.Map
Returns the easey object.
Set the starting coordinate for the easing. You don't usually need to call this, because easings default to the current coordinate.
Arguments:
coord
is an instance of MM.Coordinate
representing the starting coordinate for the easing.Returns the easey object.
Set the destination coordinate for the easing.
Arguments:
coord
is an instance of MM.Coordinate
representing the destination coordinate for the easing. Since easey deals exclusively in Coordinates, the reference for converting between points, locations, and coordinates in Modest Maps is essential reading.
Returns the easey object.
Set the zoom level of the to
coordinate that easey is easing to.
Arguments:
level
is a number representing the zoom levelReturns the easey object.
Eases to from
in the smoothest way possible, automatically choosing run time based on distance. The easing zooms out and in to optimize for the shortest easing time and the slowest percieved speed. The optional arguments are as defined in Smooth and efficient zooming and panning.
Arguments:
V
inversely affects the speed (default is 0.9) rho
affects the sensitivity of zooming in and out (default 1.42)callback
is a function that gets called after the animation completes.Returns the easey object.
Sets the to
coordinate to the provided location.
Arguments:
location
is an object with lat
and lon
properties, or an instance of MM.Location
.Returns the easey object.
Set the map to a specific point in the easing.
Arguments:
value
is a float between 0 and 1, where 0 is from
and 1 is to
.Returns the easey object.
Get the future of an easing transition, given a number of parts for it to be divided over. This is a convenience function for calling easey.t()
a bunch of times.
Arguments:
parts
is an positive integer representing the number of parts to divide the easing into.Returns an array of MM.Coordinate
objects representing each in-between location.
Set the easing curve - this defines how quickly the transition gets to its end and whether it speeds up or slows down near the beginning and end.
Arguments:
name
is the string name of the easing to use. Current options are:Returns the easey object.
Set the type of path - the type of interpolation between points.
Arguments:
pathname
is a string name of the path to use. Current options are:screen
: a 'straight line' path from place to place - in the Mercator projection, this is a rhumb lineabout
: the default path for a double-click zoom: this keeps a single coordinate in the same screen pixel over the zoom transitionReturns the easey object.
Start an animated ease. Both parameters are optional.
Arguments:
time
is an integer representing the duration of the easing in milliseconds (default is 1000).callback
is a Javascript function that is called when the map has reached its destination.Returns the easey object.
Returns true
or false
depending on whether easey is currently animating the map.
Abort the currently running animation.
Arguments:
callback
is a function to be called after the previous animation has been successfully stopped.Returns the easey object.