Most Recent Blog Post: jQuery Mapbox Updated

Click to toggle dark text on white

Mapbox: Zoomable jQuery Map Plugin

Get latest code here.

Or get the outdated (but still working) version:
[ Click here for the mapbox.min.js code - Click here for the uncompressed code ]

$().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

<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script>
<script type="text/javascript" src="/js/mousewheel.js"></script>
<script type="text/javascript" src="/js/map.js"></script>

Then, some CSS. This is how I styled the map in this example, though you may use any rules you like (the Middle Earth map has an odd proportion):

<style type="text/css">
    #viewport {
        width: 469px;
        height: 400px;
        cursor: move;
        margin: 20px auto;
        overflow: hidden; /*keep map contents from spilling over if JS is disabled*/
    }
</style>

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:

<div id="viewport">
    <div style="background: url(images/layer1.png) no-repeat; width: 469px; height: 400px;">
        <!--top level map content goes here-->
    </div>
    <div style="height: 1097px; width: 1286px;">
        <img src="images/layer2.jpg" alt="" />
        <div class="mapcontent">
            <!--map content goes here-->
        </div>
    </div>
    <div style="height: 1794px; width: 2104px;">
        <img src="images/layer3.jpg" alt="" />
         <div class="mapcontent">
            <!--map content goes here-->
        </div>
    </div>
    <div style="height: 2492px; width: 2922px;">
        <img src="images/layer4.jpg" alt="" />
         <div class="mapcontent">
            <!--map content goes here-->
        </div>
    </div>
</div>

The jQuery:

<script type="text/javascript">
    $(document).ready(function() {
        $("#viewport").mapbox({mousewheel: true});
    });
</script>

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:


    jQuery(document).ready(function() {
        $("#viewport2").mapbox({
            mousewheel: true,
            layerSplit: 8//smoother transition for mousewheel
        });
        jQuery(".map-control a").click(function() {//control panel
            var viewport = $("#viewport2");
            //this.className is same as method to be called
            if(this.className == "zoom" || this.className == "back") {
                viewport.mapbox(this.className, 2);//step twice
            }
            else {
                viewport.mapbox(this.className);
            }
            return false;
        });
    })

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)

Latest code here - OUTDATED CODE HERE (but still good - prior version)

Most Recent Blog Post: jQuery Mapbox Updated

Privacy Policy | Click Here | jQuery Plugins by Wayfarer | Freelance Jobs Available | Random JavaScript Code Samples | Share a Random Link | JavaScript Jobs