Home

Modest Maps JS API

• Layers and Providers - ways of putting tiles and data on the map
• Point, Location, and Coordinate - datatypes for places in the world and on your screen
• Projections and Transformations - changing coordinates from one type to another with math
• Interaction - getting your mouse and fingers to move the map
• Map Moving - using code to move the map
• Util - basic utilities for dealing with browsers and elements
• Testing - how we test
• Upgrading to 1.0.0 - if you've already been using a 0.x.0 version
• How it Works - for those interested in guts

We're doing our best to follow Semantic Versioning for version number guidelines. These docs are written against v1.0.0 and should be valid for all v1.x.y versions.

Modest Maps is as much a vocabulary for tiled maps as it is a code library. See ModestMapsNess for a more concise overview.

Please also play with the examples for hints on intended usage.

Map

A Map requires a DOM element, layer and optional dimensions and event handlers. The simplest way to create one is in the window onload handler with a TemplatedMapProvider and the id of a div with width and height set.

// name of a div element:
var parent = 'map';

// defaults to Google-style Mercator projection, so works
// out of the box with OpenStreetMap and friends:
var template = 'http://tile.openstreetmap.org/{Z}/{X}/{Y}.png';
var provider = new MM.TemplatedMapProvider(template);

// without a size, it will expand to fit the parent:
var map = new MM.Map(parent, provider);

Alternatively you can specify a fixed size:

// name of a div element:
var parent = 'map';

var template = 'http://tile.openstreetmap.org/{Z}/{X}/{Y}.png';
var provider = new MM.TemplatedMapProvider(template);

// Just a way of saying 600px wide by 400px high
var dimensions = new MM.Point(600,400);
var map = new MM.Map(parent, provider, dimensions);

And you can also specify a provider with a more complex method of generating URLs:

// name of a div element:
var parent = 'map';

var provider = new MM.MapProvider(function(c) {
    var img = [ c.zoom, c.column, c.row ].join('/') + '.png';
    return 'http://tile.openstreetmap.org/' + img;
});

var dimensions = new MM.Point(600,400);

var map = new MM.Map(parent, provider, dimensions);

Layers and Providers

A map can support multiple Layers, and has an interface to add, remove, and rearrange them.

// Prepare a new layer
var osm = new MM.Layer(new MM.TemplatedMapProvider('http://tile.openstreetmap.org/{Z}/{X}/{Y}.png'+bust))
var mq = new MM.Layer(new MM.TemplatedMapProvider('http://otile1.mqcdn.com/tiles/1.0.0/osm/{Z}/{X}/{Y}.jpg'))

// Insert a layer at index 0
map.insertLayerAt(0, osm);

// Replace that layer with another one
map.setLayerAt(0, mq);

// Remove that layer
map.removeLayerAt(0);

Setting/getting visible area (extent) or center and zoom

To set the Location of the center of the map use setCenter(location). To set the zoom level use setZoom(number). Or use setCenterZoom(location,number) to set both the center and the zoom level at the same time:

map.setCenter(new MM.Location(37.7749295, -122.4194155));
map.setZoom(11);

map.setCenterZoom(new MM.Location(37.7749295, -122.4194155), 11);

To set the map to a location and zoom level that will show a given bounding box (extent) or a set of points, use setExtent(locations) and pass it an array of 2 or more Locations:

var locations = [
    new MM.Location(37.7749295, -122.4194155),
    new MM.Location(37.8043722, -122.2708026),
    new MM.Location(37.8715926, -122.272747)
];
map.setExtent(locations);

You can query the map position using getCenter(), getZoom() and getExtent():

var locations = map.getExtent(); // returns an array of Locations
var loc = map.getCenter() // returns a single Location
var zoomLevel = map.getZoom();

Note that calling map.setCenter(map.getCenter()) should do nothing, but calling map.setExtent(map.getExtent()) could result in a zoom out to ensure that setExtent performs correctly.

Resizing

To set the map size (e.g. in a window.onresize handler) use setSize and pass it a point or two numbers:

// the following are equivalent:
map.setSize(new MM.Point(600,400));
map.setSize(600,400);

Note that the map will automatically resize if you didn't supply initial dimensions in the constructor and your CSS specifies relative sizes such as percentages or ems.

Events / Callbacks

Map can report on several events using a simple callback system. To be notified of map changes subscribe to some or all of the following events: panned, zoomed, extentset, centered, resized, drawn. Each callback will receive the current map as its first argument.

To make overlays that follow the map, or update parts of the page when the map changes, the simplest callback to register is 'drawn':

map.addCallback('drawn', function(m) {
    // respond to new center:
    document.getElementById('info').innerHTML = m.getCenter().toString();
});

Map also exposes a removeCallback method for keeping things tidy, and uses dispatchCallback internally to notify listeners of changes.

We're considering changing to an extremely simple callback model with only one event (perhaps only the 'drawn' event). We'd welcome your feedback on this.

Internal Map functions

At time of writing, Map also exposes several functions which are only for internal use. We're working on moving the javascript patterns we use for these objects so that these internal APIs don't leak into your work. For the record, we don't expect you to use any of the following methods (unless you're doing work on the Modest Maps internals yourself, of course): getStats, enforceLimits, draw, getTileComplete, requestRedraw, getRedraw, createOrGetLayer, checkCache, getCenterDistanceCompare.

Callbacks and Queues

The CallbackManager and RequestManager classes are used internally and should not considered stable APIs.

Namespace

The long name of Modest Maps, com.modestmaps, is by default aliased to MM. If another object wants to occupy MM, one can call MM.noConflict() and Modest Maps will only inhabit its extended name, com.modestmaps.