Click to toggle dark text on white

Mapbox: Zoomable jQuery Map Plugin

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.

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. 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,//is the map zoomable?
            pan: true,//is the map draggable?
            defaultLayer: 0,//this is an array type of number (zero being the first layer), which indicates which layer is shown by default
            layerSplit: 4,//this is how many zoom levels each layer has.  The higher this number is, the smoother the transition will be between each layer
            mapContent: ".mapcontent",//this is the class that goes on the layer which holds any content you will manually place onto the map
            defaultX: null,//if not set, the map will be centered on the x-axis.  If set, the left side of the map will be here
            defaultY: null,//defaultY is the same as defaultX, but for the y-axis
            callBefore: function(layer, xcoord, ycoord, viewport) {},//callback which happens when the left mouse button is held down, and gives access to the layer node, the x and y coordinates, and the viewport node.
            callAfter: function(layer, xcoord, ycoord, viewport) {},//callback which happens when the left mouse button is released
            beforeZoom: function(layer, xcoord, ycoord, viewport) {},//callback which occurs before the map zooms in either direction.
            afterZoom: function(layer, xcoord, ycoord, viewport) {},//callback which occurs after the map zooms in either direction.
            mousewheel: false //false by default only because it 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:

Left Right Up Down Zoom Back

    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)

Click here for the mapbox.min.js code - Click here for the uncompressed code

© 2006-2010 Abel Mohler How to Hire Me | How Websites are Built | For Developers: jQuery Tooltip Plugin