Skip to content
This repository has been archived by the owner on Apr 24, 2024. It is now read-only.

API Design Patterns

tristen edited this page Jul 19, 2012 · 1 revision

This is a set of patterns - some will survive, others won't. Feel free to contribute, and ping on the issue tracker to discuss

Maps with reasonable defaults

Maps have features, like zoom buttons, legends, and attribution. By default MapBox Wax has made these opt-in. This might reverse that pattern, making a reasonable set of controls 'standard' but easily disabled.

mapbox.map('el').zoom(false)

TileJSON is automatically instantiated

Wax created the pattern of calling most controls with a TileJSON blob. This was necessary to allow for user customization, multiple sources of TileJSON, and compatibility with multiple frameworks with different implementations (wax.mm.interaction, wax.leaf.interaction, etc). This might be able to make more assumptions.

mapbox.load('tilejsonurl', function(options) {
  map.addLayer(options.markers); // instantiated markers layer
});

Modest Maps is the standard

mapbox.js should target a single map framework, which at this point will be Modest Maps. This allows it to make assumptions and eliminate an unnecessary learning curve.

Attachment to jQuery should be reasonable

None of the MapBox javascript libraries have had hard dependencies to jQuery. This should not either, but some level of integration would probably make this feel more accessible and make this easier to learn for people used to jQuery interfaces.

// Create a map and returns a reference to it
var map = $('#el').mapbox();

// jQuery is extended to allow this map reference to be easily used later, without
// the map variable handy
$('#el').mapbox().addLayer(markers);

// And you can remove the mapbox map from that reference
$('#el').mapbox().remove();

So, in this possibility, .mapbox() is a 'map creator' as well as a reference to created maps.