Mapbox: Zoomable jQuery Map Plugin

$().mapbox(). Version 0.5

The jQuery mapbox() plugin is for creating relatively small scale, zoomable, draggable maps with multiple layers of content. This framework could be applied to games, development plans, or any layout that could benefit from being able to zoom in and pan to get a better view.

Mousewheel will zoom the map. Drag to pan.

* New feature: by default, the map will now zoom to the cursor position when the mousewheel is used. This is an intuitive means by which a user may explore different areas of the map.

The code:Before using Mapbox, you must link to jQuery and mapbox.js. I do this in the HEAD of my document. I always use the minified jQuery that is hosted by Google. Also, if you want the map's zoom to be activated by the mousewheel, you must include the mousewheel plugin: plugins.jquery.com/project/mousewheel

Then, some HTML. The structure of your map must be almost exactly like this, though you may have as many or few layers as you wish. I recommend at least 2. Every layer DIV must have a height and width set to it. I did it inline in this example only for ease of understanding. IMG tags must be used for every layer except the starting one, which you should notice is structured much differently than the other layers. You currently must include the .mapcontent class on the inner layers, even if you aren't planning to add additional content to the map:

That is all! (requires mousewheel plugin: http://plugins.jquery.com/project/mousewheel). If you don't require the mousewheel, the map may be created simply as $("#viewport").map(). Of course, there are some more advanced settings. Here are all of the settings and their defaults:

<script type="text/javascript">
$("#viewport").mapbox({
zoom: true, // does map zoom?
pan: true, // does map move side to side and up to down?
defaultLayer: 0, // starting at 0, which layer shows up first
layerSplit: 4, // how many times to split each layer as a zoom level
mapContent: ".mapcontent", // the name of the class on the content inner layer
defaultX: null, // default positioning on X-axis
defaultY: null, // default positioning on Y-axis
zoomToCursor: true, // if true, position on the map where the cursor is set will stay the same relative distance from the edge when zooming
doubleClickZoom: false, // if true, double clicking zooms to mouse position
clickZoom: false, // if true, clicking zooms to mouse position
doubleClickZoomOut: false, // if true, double clicking zooms out to mouse position
clickZoomOut: false, // if true, clicking zooms out to mouse position
doubleClickMove: false, // if true, double clicking moves the map to the cursor position
clickMove: false, // if true, clicking moves the map to the cursor position
doubleClickDistance: 1, // number of positions (determined by layerSplit) to move on a double-click zoom event
clickDistance: 1, // number of positions (determined by layerSplit) to move on a click zoom event
callBefore: function(layer, xcoord, ycoord, viewport) {}, // this callback happens before dragging of map starts
callAfter: function(layer, xcoord, ycoord, viewport) {}, // this callback happens at end of drag after map is released "mouseup"
beforeZoom: function(layer, xcoord, ycoord, viewport) {}, // callback before a zoom happens
afterZoom: function(layer, xcoord, ycoord, viewport) {}, // callback after zoom has completed
mousewheel: false /* requires mousewheel event plugin: http://plugins.jquery.com/project/mousewheel*/
}
)
</script>

In addition to the settings, there are some methods that may be passed to any map once it has been created:

<script type="text/javascript">
$("#viewport").mapbox("zoom");//zooms in 1 level (determined by layerSplit option)
$("#viewport").mapbox("zoom", 2);//zooms in 2 levels
$("#viewport").mapbox("back");//zooms out 1 level
$("#viewport").mapbox("back", 2);//zooms out 2 levels
$("#viewport").mapbox("zoomTo", 2);//zooms to the default size of the third layer (0 being the first)
$("#viewport").mapbox("left");//move the current layer left 10 pixels
$("#viewport").mapbox("right");//move the current layer right 10 pixels
$("#viewport").mapbox("up");//move the current layer up 10 pixels
$("#viewport").mapbox("down");//move the current layer down 10 pixels
$("#viewport").mapbox("left", 20);//move the current layer left 20 pixels
$("#viewport").mapbox("right", 20);//move the current layer right 20 pixels
$("#viewport").mapbox("up", 20);//move the current layer up 20 pixels
$("#viewport").mapbox("down", 20);//move the current layer down 20 pixels
$("#viewport").mapbox("center");//centers current layer
$("#viewport").mapbox("center", {
x: 200,
y: 400
});//centers current layer at positions 200px, 400px on the x and y axis
</script>

Here's an example using some of these methods to implement a control panel for the map:

Bandwidth costs money. Please donate.

$5 US

€5 EUR

The JavaScript error on this page is due to the Chili (code highligher) plugin. It is not due to a conflict with mapbox, and is an exception triggered in jQuery's each() function. Anyone care to help me figure out what is going on? (use my contact form)