modestmaps.js

v3.3.4

Getting the Source

Quick Start

Map

Location

Extent

Point

Coordinate

TemplatedLayer

Layer

Template

MapProvider

modestmaps.js

Modest Maps is a bare-bones geographic map display and interaction library. It was designed and conceived by Tom Carden, tweaked by Michal Migurski, and is maintained and hacked on primarily by Tom MacWright and Shawn Allen.

Getting the Source

You can get modestmaps.js by cloning the github repo or downloading it:

After you've downloaded it, you can include by putting this <script> tag into the <head> of your HTML document:

<script type="text/javascript" src="modestmaps.js"></script>

Quick Start

Making a Map

Making a map is easy. First, you'll need a place for your map in the HTML:

<div id="map"></div>

Then, add a script below:

<script type="text/javascript">
var tiles = new MM.TemplatedLayer("http://tile.stamen.com/toner/{Z}/{X}/{Y}.png");
var size = new MM.Point(640, 480);
var map = new MM.Map("map", tiles, size);
</script>

This will create a map showing Stamen's toner tiles in a 640x480-pixel area. See the docs below for more info on layers and map dimensions.

If you want the size of your map to be determined by CSS, you can style your div like so:

#map {
    height: 500px;
}

Then, leave off the size argument to the constructor:

<script type="text/javascript">
var tiles = new MM.TemplatedLayer("http://tile.stamen.com/toner/{Z}/{X}/{Y}.png");
var map = new MM.Map("map", tiles);
</script>

For more info on resizing, see the Map constructor and autoSize docs.

Moving Around

Once you've got your map initialized, you can move it around the world. Geographic locations in modestmaps.js are modeled with the Location class, which is called with latitude and longitude values:

var oakland = new MM.Location(37.804, -122.271);

Once you've got a location, you can tell the map to center on it by calling setCenter:

// center on Oakland, California
map.setCenter(oakland);
// center on Amsterdam, Netherlands
map.setCenter(new MM.Location(52.3702157, 4.8951679));

You can get the current center of the map with getCenter. You can also modify the visible area by setting its extent, which is defined by two or more locations. Setting a map's extent adjusts its center and zoom level so that the rectangular bounding box surrounding the locations is entirely visible:

var oakland = new MM.Location(37.804, -122.271),
    amsterdam = new MM.Location(52.3702157, 4.8951679);
var extent = new MM.Extent(oakland, amsterdam);
map.setExtent(extent)

You can change the map's zoom level with the zoomIn, zoomOut and zoomTo methods:

map.zoomIn();   // increase zoom by 1
map.zoomOut();  // decrease zoom by 1
map.zoomTo(12); // zoom to level 12

Working with Layers

One popular feature of many online maps is a "hybrid" style, which overlays satellite imagery with graphical labels. You can achieve this effect in modestmaps.js by creating two tile layers, and passing them both to the Map constructor as an array:

var baseURL = "http://tile.stamen.com/",
    watercolor = new MM.TemplatedLayer(baseURL + "watercolor/{Z}/{X}/{Y}.jpg"),
    labels = new MM.TemplatedLayer(baseURL + "toner-labels/{Z}/{X}/{Y}.jpg");
var map = new MM.Map("map", [watercolor, labels]);

Or you can create the map with one layer, then add the overlay later:

var map = new MM.Map("map", watercolor);
map.addLayer(labels);

See the addLayer docs and the TemplatedLayer class reference for more on working with layers.

MM.Map

The Map class is the core of modestmaps.js.

new MM.Map(parent [, layerOrLayers [, dimensions [, eventHandlers]]])

Creates a new map inside the given parent element, containing the specified layers, optionally with the specified dimensions in pixels and custom event handlers. The Map constructor arguments are described in detail below:

parent

The parent element of the map. This is typically a String indicating the ID of the element:

var map = new MM.Map("map", []);

You can also provide an element reference:

var firstDiv = new MM.Map(document.querySelector("div.map"), ...);

Here's a pattern for inserting maps into a series of classed elements, using document.getElementsByClassName:

var elements = document.getElementsByClassName("map"),
    maps = [];
for (var i = 0; i < elements.length; i++) {
  maps[i] = new MM.Map(elements[i], ...);
}

If an element with the provided ID string is not found, an exception is raised.

If parent is not an object or a string, an exception is raised.

layerOrLayers

Either a single layer object or an array of layer objects. Layer objects should either be instances of the Layer class or implement the Layer interface.

Here's an example of a map with two tile layers, from maps.stamen.com:

var baseURL = "http://tile.stamen.com/",
    watercolor = new MM.TemplatedLayer(baseURL + "watercolor/{Z}/{X}/{Y}.png"),
    labels = new MM.TemplatedLayer(baseURL + "toner-labels/{Z}/{X}/{Y}.png");
var map = new MM.Map("map", [watercolor, labels]);

NOTE: Before modestmaps.js v3.1.1, an exception was raised if layerOrLayers was not an object or an array.

dimensions

An optional map size in pixels, expressed as a Point object.

var size = new MM.Point(512, 512);
var map = new MM.Map("map", [], size);
console.log("map size:", map.dimensions.x, "x", map.dimensions.y);

If dimensions is null or undefined, the dimensions are derived from the width and height of the parent element, and the map's autoSize flag is set to true.

Empty <div> elements have no intrinsic height, so if you don't provide dimensions you'll need to provide the map's parent height in CSS (either inline or in a stylesheet).

eventHandlers

An optional array of interaction event handlers, which should implement the EventHandler interface. If no handlers are provided (eventHandlers === undefined), the map is initialized with mouse and touch handlers.

For instance, to create a map without scroll wheel zooming (which is enabled by default), you can provide drag, and double-click handlers:

var map = new MM.Map("map", [], null, [
  new MM.DragHandler(),
  new MM.DoubleClickHandler()
]);

The touch handler provides panning and zooming in touch-enabled browsers:

var map = new MM.Map("map", [], null, [
  new MM.TouchHandler()
]);

To initialize the map without any interaction handlers, specify eventHandlers as null or an empty array ([]).

getCenter map.getCenter()

Get the map's center location.

var center = map.getCenter();
console.log("center latitude:", center.lat, "+ longitude:", center.lon);

setCenter map.setCenter(location)

Set the map's center location.

var center = new MM.Location(37.764, -122.419);
map.setCenter(center);

getZoom map.getZoom()

Get the map's zoom level.

var zoom = map.getZoom();
console.log("zoom level:", zoom);

setZoom map.setZoom(zoom)

Set the map's zoom level.

map.setZoom(17);

setCenterZoom map.setCenterZoom(location, zoom)

Set the map's center location and zoom level.

map.setCenterZoom(new MM.Location(37.764, -122.419), 17);

getExtent map.getExtent()

Get the visible extent (bounds) of the map as an Extent object.

var extent = map.getExtent();
console.log("northwest location:", extent.northWest());
console.log("southeast location:", extent.southEast());

setExtent map.setExtent(extent [, precise])

Modify the center and zoom of the map so that the provided extent is visible. If precise is true, resulting zoom levels may be fractional. (By default, the map's zoom level is rounded down to keep tile images from blurring.)

var extent = new MM.Extent(
  new MM.Location(55.679, 12.584),
  new MM.Location(55.668, 12.607)
);
map.setExtent(extent, true);

NOTE: For historical reasons, setExtent also accepts an array of Location objects, which are converted using Extent.fromArray.

zoomIn map.zoomIn()

Increase the map's zoom level by one.

zoomOut map.zoomOut()

Decrease the map's zoom level by one.

zoomBy map.zoomBy(zoomOffset)

Zoom the map by the provided offset. Positive offsets zoom in; negative offsets zoom out.

// this is the equivalent of calling map.zoomIn() twice:
map.zoomBy(2);

zoomByAbout map.zoomByAbout(zoomOffset, point)

Zoom the map by the provided zoom offset from a point on the screen in pixels. Positive offsets zoom in; negative offsets zoom out. This function is used by DoubleClickHandler to zoom in on the point where the map is double-clicked.

// zoom in on the upper left corner
var point = new MM.Point(0, 0);
map.zoomByAbout(1, point);

panBy map.panBy(x, y)

Pan the map by the specified x and y distance in pixels. Positive values move the map right and down, respectively; negative values move the map left and up.

// pan 500 pixels to the right
map.panBy(500, 0);
// pan 200 pixels up
map.panBy(0, -200);

panLeft map.panLeft()

panRight map.panRight()

panUp map.panUp()

panDown map.panDown()

Pan the map to the left, right, up or down by 100 pixels. To vary the offset distance, use panBy.

getLayers map.getLayers()

Get a copy of the map's layers array.

var layers = map.getLayers();
var base = layers[0];

getLayerAt map.getLayerAt(index)

Get the layer at a specific index. The first layer is at index 0, the second at 1, etc.

var map = new MM.Map(...);
var base = map.getLayerAt(0);
base.parent.id = "base";

addLayer map.addLayer(layer)

Add layer to the map's layer stack]. This triggers a redraw.

var layer = new MM.TemplatedLayer("http://tile.stamen.com/toner-lines/{Z}/{X}/{Y}.png");
map.addLayer(layer);

removeLayer map.removeLayer(layer)

Remove layer from the map's layer stack.

setLayerAt map.setLayerAt(index, newLayer)

Replace the existing layer at index with the new layer.

var layer = new MM.TemplatedLayer("http://tile.stamen.com/toner/{Z}/{X}/{Y}.png");
map.setLayerAt(0, layer);

insertLayerAt map.insertLayerAt(index, layer)

Insert a layer at the provided index.

// let's assume the map has 2 layers already
var layer = new MM.TemplatedLayer("http://tile.stamen.com/toner-lines/{Z}/{X}/{Y}.png");
map.insertLayerAt(1, layer);
// (now it has 3, with our new layer at index 1)

removeLayerAt map.removeLayerAt(index)

Remove the layer at the provided index.

// remove the second layer
map.removeLayerAt(1);

swapLayersAt map.swapLayersAt(indexA, indexB)

Swap the z-index (order) or the layers at indexA and indexB.

// swap the bottom and top layers
var bottom = 0,
    top = map.getLayers().length - 1;
map.swapLayersAt(bottom, top);

pointLocation map.pointLocation(screenPoint)

Convert a point on the screen to a location (a point on the Earth).

pointCoordinate map.pointCoordinate(screenPoint)

Convert a point on the screen to a tile coordinate.

locationPoint locationPoint(location)

Convert a location (a point on the Earth) to a point on the screen.

locationCoordinate map.locationCoordinate(location)

Convert a location (a point on the Earth) to a tile coordinate.

coordinateLocation map.coordinateLocation(coord)

Convert a tile coordinate to a location (a point on the Earth).

coordinatePoint map.coordinatePoint(coord)

Convert a tile coordinate to a point on the screen.

setZoomRange map.setZoomRange(minZoom, maxZoom)

Set the map's minimum and maximum zoom levels. This function modifies the zoom levels of the map's coordLimits.

setSize map.setSize(dimensions)

Set the map's dimensions in pixels. If the map's autoSize flag is true, setting the size manually sets autoSize to false and prevents further automatic resizing.

map.setSize(new MM.Point(640, 480));

NOTE: The map's current size is available in its dimensions property.

addCallback map.addCallback(eventType, callback)

Add a callback function (listener) to the map for a specific event type. Callback functions always receive the map instance as their first argument; additional arguments differ by event type. See the events list for supported types.

function onPanned(map, offset) {
  console.log("panned by", offset[0], offset[1]);
}

map.addCallback("panned", onPanned);

You can remove callbacks with removeCallback.

removeCallback map.removeCallback(eventType, callback)

Remove a callback function (listener) for the given event type. You can add callbacks with addCallback.

map.removeCallback("panned", onPanned);

draw map.draw()

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.

requestRedraw map.requestRedraw()

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.

Multiple calls to requestRedraw within 1 second of one another will be ignored, so this is a perfectly reasonable thing to do:

setInterval(function() {
  map.requestRedraw();
}, 100);

Hybrid Methods

Hybrid methods behave differently depending on whether they receive arguments: The "getter" form (with no arguments) returns the current value, and the "setter" form sets it to the value provided then returns this, which makes function chaining possible (a la jQuery, d3, and Polymaps).

center map.center([location])

Get or set the map's center location.

var center = map.center();
center.lat += .1;
map.center(center);

zoom map.zoom([level])

Get or set the map's zoom level.

var zoom = map.zoom();
zoom -= 3;
map.zoom(zoom);

extent map.extent([locationsOrExtent [, precise]])

Get or set the map's extent. If precise is true, resulting zoom levels may be fractional.

// get the extent, check if it contains a location…
var extent = map.extent(),
    loc = new MM.Location(37.764, -122.419);
if (!extent.containsLocation(loc)) {
  // then enclose the location and set the map's new extent
  extent.encloseLocation(loc);
  map.extent(extent);
}

Map Properties

autoSize map.autoSize

The autoSize property is set to true if no dimensions are provided in the constructor. When autoSize is true, the map's dimensions are recalculated (and the map is redrawn) on window resize.

coordinate map.coordinate

The map's current center coordinate.

coordLimits map.coordLimits

An array specifying the map's coordinate bounds, in which the first element defines the top left (northwest) and outermost zoom level, and the second defines the bottom right (southwest) and innermost zoom.

You can adjust the minimum and maximum zoom levels of the map without affecting the bounds with setZoomRange.

dimensions map.dimensions

The map's current dimensions, expressed as a Point.

// the bottom right screen coordinate is also its southeast point
var southEast = map.pointLocation(map.dimensions);

parent map.parent

The map's parent (container) DOM element.

map.parent.style.backgroundColor = "green";

projection map.projection

The map's projection, also known as Coordinate Reference System (CRS) or Spatial Reference System (SRS).

tileSize map.tileSize

The pixel dimensions of the map's individual image tiles, expressed as a Point. By default, tiles are 256 pixels square.

// you can use the tile size to estimate the number of tiles visible
// at any given moment:
var maxRows = Math.ceil(map.dimensions.x / map.tileSize.x);
var maxCols = Math.ceil(map.dimensions.y / map.tileSize.y);
var maxTiles = maxRows * maxCols;
console.log("max tiles:", maxTiles);

Map Events

Map events are triggered when the map moves (either in response to a direct function call or indirectly, through user interaction with an event handlers) or is drawn. You can start and stop listening for map events with addCallback and removeCallback:

function onDrawn(map) {
  console.log("map drawn!");
}

// After this, the onDrawn will be called whenever the map changes.
map.addCallback("drawn", onZoomed);
// Later, remove the callback.
map.removeCallback("drawn", onZoomed);

"zoomed" function(map, zoomOffset) { ... }

Fires when the map's zoom level changes, usually in response to zoomBy or zoomByAbout. Note that the zoom offset is the difference between the last zoom level and the new zoom level. You can query the map's current zoom level (rather than the offset) with getZoom.

map.addCallback("zoomed", function(map, zoomOffset) {
  console.log("map zoomed by:", zoomOffset);
});

"panned" function(map, panOffset) { ... }

Fires when the map is panned, and receives the pan offset (delta) in pixels as a two-element array ([dx, dy]).

map.addCallback("panned", function(map, panOffset) {
  var dx = panOffset[0],
      dy = panOffset[1];
  console.log("map panned by x:", dx, "y:", dy);
});

"resized" function(map, dimensions) { ... }

Fires when the map is resized, and receives the map's new dimensions as a Point object.

map.addCallback("panned", function(map, dimensions) {
  console.log("map dimensions:", dimensions.x, "y:", dimensions.y);
});

"extentset" function(map, locationsOrExtent) { ... }

Fires whenever the map's full extent is set, and receives the Extent or array of Location objects provided to setExtent or extent.

map.addCallback("extentset", function(map, extent) {
  // convert to an Extent instance if it's a Location array
  if (extent instanceof Array) {
    extent = MM.Extent.fromArray(extent);
  }
  console.log("map extent:", extent);
});

"drawn" function(map) { ... }

Fires whenever the map is redrawn.

map.addCallback("drawn", function(map) {
  console.log("map drawn!");
});

MM.Location

Location objects represent geographic coordinates on the Earth's surface, expressed as degrees latitude and longitude. The constructor takes these two values as its arguments:

new MM.Location(latitude, longitude)

Locations are most often used when getting and setting the center of a map. You can read the latitude and longitude of a Location by accessing its lat and lon properties, respectively:

var center = map.getCenter(),
    latitude = center.lat,
    longitude = center.lon;

Note that the Map class doesn't store any references to Location objects internally. Both the getCenter and setCenter methods convert between geographic and tile coordinate systems, and return copies of objects rather than references. This means that changing the lat and lon properties of a Location object returned from getCenter won't change the map's center; you have to call setCenter with the modified Location object.

lat location.lat

The location's latitude, or distance from the Earth's equator in degrees. -90 is at the bottom of the globe (the south pole in Antarctica), 0 is at the equator, and 90 is at the top (the north pole in the Arctic Ocean).

NOTE: Because ModestMaps uses a spherical Mercator projection, points at Earth's extreme north and south poles become infinitely large and impossible to model. This limits the effective range of web maps to ±85º, depending on zoom level. Setting a map's center to a Location with a latitude outside of this range will most likely have undesired consequences.

lon location.lon

The location's longitude, or distance from the prime meridian in degrees. Positive values are east of the prime meridian (towards Asia); negative values are west (towards North America). ±180 degrees is near the international date line. Longitude values outside of the [-180, 180] range "wrap", so a longitude of 190 degrees may be converted to -170 in certain calculations.

Location.fromString MM.Location.fromString(str)

Parse a string in the format "lat,lon" into a new Location object.

Location.distance MM.Location.distance(a, b, earthRadius)

Get the physical distance (along a great circle) between locations a and b, assuming an optional Earth radius:

Location.interpolate MM.Location.interpolate(a, b, t)

Interpolate along a great circle between locations a and b at bias point t (a number between 0 and 1).

Location.bearing MM.Location.bearing(a, b)

Determine the direction in degrees between locations a and b. Note that bearing direction is not constant along significant great cirlce arcs.

A warning about the location variable name

Because browsers reserve the window.location variable for information about the current page location, we suggest using variable names other than location to avoid namespace conflicts. center and loc are good alternatives.

MM.Extent

Extent objects represent rectangular geographic bounding boxes, and are identified by their north, south, east and west bounds. North and south bounds are expressed as degrees latitude; east and west bounds are degrees longitude. The constructor takes two forms:

new MM.Extent(north, west, south, east)

Create an extent bounded by north, west, south and east edges.

new MM.Extent(northWest, southEast)

Create an extent containing both northWest and southEast locations.

north extent.north

The northern edge of the extent. The constructor compares northern and southern values and selects the higher of the two as its north.

south extent.south

The southern edge of the extent. The constructor compares northern and southern values and selects the lower of the two as its south.

east extent.east

The eastern edge of the extent. The constructor compares eastern and western values and selects the higher of the two as its east.

west extent.west

The western edge of the extent. The constructor compares eastern and western bounds and selects the lower of the two values as its west.

northWest extent.northWest()

Get the extent's northwest corner as a Location.

northEast extent.northEast()

Get the extent's northeast corner as a Location.

southEast extent.southEast()

Get the extent's southeast corner as a Location.

southWest extent.southWest()

Get the extent's southwest corner as a Location.

center extent.center()

Get the extent's center as a Location.

containsLocation extent.containsLocation(lcoation)

Returns true if the location falls within the extent, otherwise false.

var extent = new MM.Extent(37.8, -122.5, 37.6, -122.3);
var sf = new MM.Location(37.764, -122.419);
var oakland = new MM.Location(37.804, -122.271);
extent.containsLocation(sf); // true
extent.containsLocation(oakland); // false

encloseLocation extent.encloseLocation(location)

Update the bounds of extent to include the provided location.

var extent = new MM.Extent(37.8, -122.5, 37.6, -122.3);
var oakland = new MM.Location(37.804, -122.271);
extent.encloseLocation(oakland);
extent.containsLocation(oakland); // true

encloseLocations extent.encloseLocations(locations)

Update the bounds of extent to include the provided locations (an array of Location objects).

encloseExtent extent.encloseExtent(otherExtent)

Update the bounds of extent to include the bounds of the other extent.

setFromLocations extent.setFromLocations(locations)

Reset the bounds of the extent and enclose the provided locations.

copy extent.copy()

Copy the extent and its north, south, east and west values.

toArray extent.toArray()

Returns a two-element array containing the extent's northwest and southeast locations.

Extent.fromString MM.Extent.fromString(str)

Parse a string in the format "north,west,south,east" into a new Extent object.

Extent.fromArray MM.Extent.fromArray(locations)

Create a new Extent object from an array of Location objects.

MM.Point

Point objects represent x and y coordinates on the screen, such as a map's dimensions and the position of mouse or touch interactions.

new MM.Point(x, y)

Create a new Point object with x and y coordinates. parseFloat() is used to convert string values to numbers. The resulting object has x and y properties.

Point objects can be used with pointLocation to determine the geographic coordinates of a point on the screen inside a map. For instance:

// define the map's dimensions
var size = new MM.Point(640, 480);
// create a map without any layers or event handlers
var map = new MM.Map("map", [], size, []);
// zoom to San Francisco
map.setCenterZoom(new MM.Location(37.764, -122.419), 8);
// get the geographic coordinates of the bottom right corner
var southEast = map.pointLocation(size);

And vice-versa, you can use locationPoint to get the screen position of a geographic coordinate:

var oakland = new MM.Location(37.804, -122.271);
var point = map.locationPoint(oakland);
// do something with point.x and point.y

Point.distance MM.Point.distance(a, b)

Compute the Euclidian distance between two Point objects.

Point.interpolate MM.Point.interpolate(a, b, t)

Compute the point on a straight line between points a and b at normal distance t, a number between 0 and 1. (If t == .5 the point will be halfway between a and b.)

MM.Coordinate

Coordinate objects are used internally by ModestMaps to model the surface of the Earth in Google's spherical Mercator projection, which flattens the globe into a square, or tile. Coordinate objects represent points within that tile at different zoom levels, with column and row properties indicating their x and y positions, respectively. Each round number column and row within a zoom level represents a 256-pixel square image displayed in a ModestMaps tile layer.

new Coordinate(row, column, zoom)

zoom coordinate.zoom

Coordinates are always expressed relative to a specific zoom level. At zoom 0, the Earth fits into a single square tile, Coordinate(0, 0, 0). With each increase in zoom, every tile is divided into 4 parts, so at zoom level 1 the Earth becomes 4 tiles; at zoom level 2 it becomes 16. Coordinates can be converted to different zoom levels with zoomTo.

column coordinate.column

A Coordinate's column represents a tile's relative x position at its zoom level. At zoom 0 there is one column. With each increase in zoom, the number of columns doubles, so at zoom 1 there are two (0 >= column < 2), at zoom 2 there are four (0 >= column < 4), and so on.

row coordinate.row

A Coordinate's row represents a tile's relative y position at its zoom level. At zoom 0 there is only one tile. With each increase in zoom, the number of rows doubles, so at zoom 1 there are two (0 >= row < 2), at zoom 2 there are four (0 >= row < 4), and so on.

copy coordinate.copy()

Copy the coordinate's zoom, row and column properties into a new Coordinate object.

container coordinate.container()

Create a Coordinate object that contains coordinate by flooring its zoom, column and row properties. This is the actual "tile" coordinate.

zoomTo coordinate.zoomTo(zoom)

Copy coordinate and adjust its row and column properties to match the new zoom level.

zoomBy coordinate.zoomBy(zoomOffset)

Zoom coordinate by the the specified zoom offset and return a new Coordinate object.

up coordinate.up()

Get the Coordinate above coordinate.

right coordinate.right()

Get the Coordinate to the right of coordinate.

down coordinate.down()

Get the Coordinate below coordinate.

left coordinate.left()

Get the Coordinate to the left of coordinate.

toKey coordinate.toKey()

Generate a string key for the coordinate, e.g. "(1,1,5)" ("zoom,row,column").

toString coordinate.toString()

Format the coordinate as a human-readable string, e.g. "(5,4 @ 1)" (("row,column @ zoom"))

Pre-projecting

Coordinate are also useful for "pre-projecting" locations. Because conversions between screen and geographic coordinates are more computationally expensive than conversions between screen and tile coordinates, you may wish to do the Location to Coordinate conversion once then do Coordinate to Point conversions subsequently. For example:

var map = new MM.Map("map", …);
var sfLocation = new MM.Location(37.764, -122.419);
var sfCoordinate = map.locationCoordinate(sfLocation);
// assuming there is an "sf" element, with CSS positon: absolute
var marker = map.parent.appendChild(document.getElementById("sf"));
map.addCallback("drawn", function() {
    var point = map.coordinatePoint(sfCoordinate);
    marker.style.left = point.x + "px";
    marker.style.top = point.y + "px";
});

In this example, map.coordinatePoint(sfCoordinate) will be much faster than calling map.locationPoint(sfLocation) each time the map is redrawn. You probably won't notice the performance gain with one marker, but you certainly will with hundreds.

MM.TemplatedLayer

The TemplatedLayer class provides a simple interface for making layers with templated tile URLs.

new MM.TemplatedLayer(templateURL [, subdomains])

Create a layer in which each tile image's URL is a variation of the URL template and optional list of subdomains.

You can learn more about templated tile URLs in the Template reference. Here are some examples:

var toner = new MM.TemplatedLayer("http://tile.stamen.com/toner/{Z}/{X}/{Y}.png");
var bing = new MM.TemplatedLayer("http://ecn.t0.tiles.virtualearth.net/tiles/r{Q}?" +
    "g=689&mkt=en-us&lbl=l1&stl=h");
var osm = new MM.TemplatedLayer("http://tile.openstreetmap.org/{Z}/{X}/{Y}.png");

MM.Layer

Map layers are where map imagery (including but not limited to tiles) gets rendered. The Layer class does all of the heavy lifting to determine which tiles are visible at any given moment, loads them if necessary, then adds them to the DOM and positions them on screen.

new MM.Layer(provider [, parent])

Create a new map layer that uses a provider, optionally specifying a custom parent element (or container). A layer's provider is an instance of the MapProvider class, which converts tile coordinates into image URLs. This example provides Placehold.it URLs that list the tile coordinates:

var provider = new MM.MapProvider(function(coord) {
    return "http://placehold.it/256x256&text=" +
        [coord.zoom, coord.column, coord.row].join("/");
});
var layer = new MM.Layer(provider);
map.addLayer(layer);

The Template class simplifies generating image URLs for tile servers with popular template formats.

getProvider layer.getProvider()

Get the layer's current provider.

setProvider layer.setProvider()

Set the layer's current provider.

destroy layer.destroy()

Destroy the layer, removing all of its tiles from memory and removing its parent element from the map.

draw layer.draw()

Redraw the layer by loading, unloading, adding, removing, and repositioning tile images as appropriate. Changing the provider triggers a draw.

requestRedraw layer.requestRedraw()

Request a layer redraw in 1 second. This works just like Map.redraw.

MM.MapProvider

Map providers convert tile coordinates to image URLs. If your image tiles come in either XYZ or quadkey formats, you should use the TemplateProvider class.

new MM.MapProvider(getTileUrl)

MapProvider is an abstract class, meaning that it is meant to be extended. The constructor takes a function as its only argument, which is expected to return an image URL (or null) for a given tile coordinate. This example emulates the behavior of Template using a static URL template:

var provider = new MM.MapProvider(function(coord) {
    return "http://tile.stamen.com/toner/{Z}/{X}/{Y}.png"
        .replace("{Z}", coord.zoom)
        .replace("{X}", coord.column)
        .replace("{Y}", coord.row);
});
// Coordinate(row, col, zoom)
provider.getTile(new MM.Coordinate(1, 2, 3));
// returns: "http://tile.stamen.com/toner/3/2/1.png"

Map providers expose the following interface to Layer objects:

getTile provider.getTile(tileCoord)

Generates a tile URL or DOM element for the given tile coordinate. If the returned value is a string, an <img> element is created. Otherwise, if truthy, the return value is assumed to be a DOM element.

For instance, you could create a map provider that generates <canvas> elements for each tile by customizing getTile like so (note that in this case, your tiles will need to either reside on the same server or be served with the appropriate CORS headers):

var myProvider = new MM.MapProvider(function(coord) {
    return "path/to/tiles/" +
        [coord.zoom, coord.column, coord.row].join("/") +
        ".png";
});
myProvider.getTile = function(coord) {
    var url = this.getTileUrl(coord);
    if (url) {
        var canvas = document.createElement("canvas");
        canvas.width = canvas.height = 256;
        var ctx = canvas.getContext("2d"),
            img = new Image();
        img.onload = function() {
            canvas.drawImage(img);
        };
        img.src = url;
        return canvas;
    }
};

NOTE: Because layers cache elements returned by this function, there is no guarantee that getTile will be called subsequently after a call to releaseTile with the same tile coordinate. If your provider needs to be notified of "re-added" tiles (ones that are generated once, released, then added again from the cache), it should implement reAddTile.

getTileUrl provider.getTileUrl(tileCoord)

Get the URL of the tile with the provided coordinate. In the abstract MapProvider class, getTile and getTileUrl

releaseTile provider.releaseTile(tileCoord)

Clean up any resources required to display the tile coordinate's corresponding tile image or element. This is probably only necessary if your provider maintains references (such as a list or numeric reference count) to tiles generated by getTile.

reAddTile provider.reAddTile(tileCoord)

If a provider implements the reAddTile method, cached tiles will be passed to this function so that the provider can know about the re-addition of tiles revived from the layer cache.

MM.Template

ModestMap's Template class extends MapProvider, and converts tile coordinates to image URLs using a standard template format. These are the same constructor arguments as in TemplatedLayer:

new MM.Template(urlTemplate [, subdomains])

Create a new templated provider based on the specified URL template, and an optional array of subdomain replacements. URL templates may contain the following placeholders:

X, Y, Z http://example.com/tiles/{Z}/{X}/{Y}.ext

In an XYZ template, the {X}, {Y} and {Z} placeholders are replaced with each tile's column, row and zoom properties, respectively.

var toner = new MM.Template("http://tile.stamen.com/toner/{Z}/{X}/{Y}.png");

Quadkey http://example.com/tiles/{Q}.ext

In a quadkey template, the {Q} placeholder is replaced with each tile's quadkey string. These are found on Microsoft's Bing Maps (previously VirtualEarth) tile servers:

var bingBase = "http://ecn.t0.tiles.virtualearth.net/tiles/r{Q}?";
var bing = new MM.Template(bingBase + "g=689&mkt=en-us&lbl=l1&stl=h");

Subdomains http://{S}.example.com/...

If an array of subdomains is passed to the Template constructor, tile URLs will substitute a predictable selection from the array for any {S} placeholder (e.g., the first one gets subdomains[0], the second gets subdomains[1], etc.). Many tile servers support loading via multiple subdomains, e.g.:

var osm = new MM.Template("http://{S}.tile.openstreetmap.org/{Z}/{X}/{Y}.png",
    ["a", "b", "c", "d"]);
var bing = new MM.Template("http://ecn.t{S}.tiles.virtualearth.net/tiles/r{Q}" +
    "?g=689&mkt=en-us&lbl=l1&stl=h",
    [1, 2, 3, 4]);
var terrain = new MM.Template("http://{S}.tile.stamen.com/terrain/{Z}/{X}/{Y}.png",
    "a b c d".split(" "));

Multiple subdomains may drastically speed up your maps! Most browsers place limits on the number of URLs that can be loaded simultaneously from each domain. Using two subdomains in effect doubles the number of image tiles that can load at the same time.

NOTE: {S} placeholders need not necessarily refer to subdomains. You could, for instance, vary the entire hostname of each tile, like so:

var template = new MM.TemplateProvider("http://{S}/tiles/{Z}/{X}/{Y}.png",
    ["example.com", "example.org", "example.net"]);

Package Utilities

These are provided as useful shortcuts, often used to provide cross-browser compatibility.

MM.extend MM.extend(childClass, parentClass)

Extend the prototype of child class with previously unspecified methods from the parent class's prototype. This is how you extend classes in ModestMaps:

var MyLayer = function(provider) {
    // do something MyLayer-specific
    // then call the Layer constructor
    MM.Layer.call(this, provider);
};

MyLayer.prototype = {
    getTile: function(coord) {
        // do something cool here
    }
};

MM.extend(MyLayer, MM.Layer);

MM.coerceLayer MM.coerceLayer(layerish)

Coerce the provided layerish string or object into a Layer, according to the following rules:

  1. If layerish is a string, return a new TemplatedLayer with layerish as the URL template.
  2. If layerish has a draw function, assume that it's a Layer instance and return it.
  3. Otherwise, assume that it's a MapProvider and return a new Layer with it as the constructor argument: new MM.Layer(layerish).

MM.addEvent MM.addEvent(element, eventType, listener)

Adds the listener to the provided DOM element for the given event type. In browsers that support DOM Level 2 events, this calls element.addEventListener(eventType, listener, false). In older versions of Internet Explorer, this uses element.attachEvent().

var link = document.getElementById("null-island"),
    nullIsland = new MM.Location(0, 0);
MM.addEvent(link, "click", function(e) {
    map.setCenterZoom(nullIsland, 12);
    return MM.cancelEvent(e);
});

You can remove event listeners with MM.removeEvent.

MM.removeEvent MM.removeEvent(element, eventType, listener)

Removes the listener from element for the given event type.

MM.removeEvent(link, "click", onClick);

MM.cancelEvent MM.cancelEvent(event)

Does whatever is necessary to cancel the provided DOM event and returns false. This is useful for preventing the default behavior or click events, e.g.:

var zoomIn = document.getElementById("zoom-in");
MM.addEvent(zoomIn, "click", function(e) {
    map.zoomIn();
    return MM.cancelEvent(e);
});

MM.getStyle MM.getStyle(element, property)

Get the element's computed style of the named CSS property.

var bgcolor = MM.getStyle(map.parent, "background-color");

MM.moveElement MM.moveElement(element, point)

Updates the CSS properties of element so that it appears at the absolute position point. If available, this function uses CSS transforms (which are often hardware accelerated, and thus faster than traditional top and left properties).

var marker = document.getElementById("marker"),
    sf = new MM.Location(37.764, -122.419);
map.addCallback("drawn", function() {
    var point = map.locationPoint(sf);
    MM.moveElement(marker, point);
});

(See the section on pre-projecting for a slightly better way of doing this.)

MM.getFrame MM.getFrame(frameCallback)

This is a stand-in for requestAnimationFrame, a feature of modern browsers that calls the frame callback function as often as possible without affecting page repainting.

MM.transformProperty MM.transformProperty

The name of the property used by the running browser to provide CSS transforms.

MM.matrixString MM.matrixString(point)

Convert point into a CSS transform-compatible matrix string.