Layers and Providers

Layers are levels of tiles or elements that can be added, removed, and rearranged on a map. They're similar to layers in Leaflet, OpenLayers and elsewhere, and Modest Maps gives a nice interface for adding, rearranging, and removing them.

Most layers in Modest Maps are tile layers, that are made up of tiled images, typically 256x256, though you can change that by changing map.tileSize. These layers typically 'have' providers, which delivers specific data to the layer, like tile URLs, based on map coordinates.

For instance, a layer might look like

var layer = new MM.Layer(new MM.MapProvider(function(coord) {
    var img = parseInt(coord.zoom) +'-r'+ parseInt(coord.row) +'-c'+ parseInt(coord.column) + '.jpg';
    return 'http://osm-bayarea.s3.amazonaws.com/' + img;
}));

See that there's one class, MM.Layer, that takes another, MM.MapProvider as an argument: the layer keeps track of images, requests, moving the map around, and the provider simply lets the layer know what tiles correspond to which coordinates (see MM.Coordinate).

If you want to switch layers in response to a button press, you can call map.setLayerAt with a new layer instead.

MapProvider

The MapProvider class expects a callback function that can turn a Coordinate into a URL string:

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

TemplatedLayer

The TemplatedLayer is an easier interface to MapProvider which takes a string with attractive mustache syntax to generate tile URLs:

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

The TemplatedLayer also takes a template argument {S}, that replaces part of the URL with one of an array of strings. You can use this for subdomains of a tile server.

var template = 'http://{S}tile.openstreetmap.org/{Z}/{X}/{Y}.png';
var subdomains = [ '', 'a.', 'b.', 'c.' ];
var provider = new MM.TemplatedLayer(template, subdomains);

So in total they accept the tokens:

• {Z} - zoom level
• {X} - tile column
• {Y} - tile row
• {S} - subdomain
• {Q} - quadkey for Microsoft-style quadkey tilesets

Using the X, Y, and Z tokens in combination gives easy access to sites that use OpenStreetMap-style slippy tile names.

The TemplatedLayer is similar to the OpenLayers.Layer.XYZ class, or Leaflet's L.TileLayer

Providers also implement a few properties and functions that alter how Modest Maps loads tiles (or does not load tiles) such as outerLimits and sourceCoordinate, and the functions used by map to convert to and from Locations and Coordinates: locationCoordinate(location) and coordinateLocation(coord).

Layer

new in 1.0.0

Layers wrap Providers and do much of the work of requesting and manages the tiles that Providers suggest.

Constructor

// Create a new layer with OpenStreetMap tiles
var osmProvider = new MM.TemplatedMapProvider('http://{S}tile.openstreetmap.org/{Z}/{X}/{Y}.png');
var osmLayer = new MM.Layer(osmProvider);

Instance Methods

// Change a layer's provider
layer.setProvider(newProvider);

Layer Setters and Getters

• setLayerAt(index, layer)
• remoteLayer(layer)
• insertLayerAt(index, layer)
• removeLayerAt(index)
• swapLayersAt(i, j)
• addLayer(layer)
• getLayers()