Overview

Image Mapster: A Jquery Plugin to make image maps useful.

Visit the external project home page which hosts a demo, but the current code will be here.

See an online demonstration

Go to Options

Details

Compatible with

• IE 6-9
• Firefox 2-4
• Safari 3-5
• Chrome -10
• Opera 9-10

This plugin started as an extension to code originally written by David Lynch for http://davidlynch.org/js/maphilight/docs/. It was completely rewritten at version 1.0.3 but still incorporates some of the original code and core rendering algorithms.

Example Usage

Basic usage using default options:

$('img').mapster();

This example shows a usage incorporating most of the options.

var img = $('#usa_image');
img.mapster({
    isSelectable: true,         // areas can be selected/deselected
    mapKey: 'title',            // the attribute on each area tag that identifies
                                // it uniquely (or as part of a group with the same value)
    mapValue: 'full',           // a user-defined attribute on the area tag that will be passed
                                // in onGetList - can be used for quick and dirty listmaking
    listKey: 'name',            // the attribute on the list elements that matches it with 
                                // mapKey
    listSelectedAttribute:      // an attribute that will be created or removed from the list element
        'checked',              // matching an area when it is selected or deselected
    onGetList: buildStateList,  // a function to build a list from the areas
    onClick: 
        styleElementWrapper     // event when item is clicked
    showToolTip: true,          // enable tooltips for the map, individual data is provided
                                // in jQuery data("mapster") associated with area tags
    toolTipContainer: 
        getToolTipContainer();  // HTML or jQuery object that will be rendered for tooltips
    sortList: "asc",            // the list of values will be sorted when passed to onGetList function
    areas: [                    // an array of area-specific configuration options
    {
        key: "OK",
        tooltip: "Oklahoma is OK!",
        selected: true
    },
    {
        key: "TX",
        tooltip: "Don't mess with Texas."
    }
    ]
});

The last option, areas, adds area-specific configuration options. The key property will apply these options to areas with a matching mapKey. If there are multiple areas that are part of a group, as is common with complex maps, they are all treated as a single area, and these options will apply to the entire group matching the key. HTML for the above might look like:

<img src="images/usamap.png" usemap="#usamap">
<map name="usamap">
    <area href="#" title="HI" full="Hawaii" shape="poly" coords="169,391,170,389,172,388,172,389,170,391,169,391">
    .... // additional areas
</map>

"full" is not a real HTML attribute, but is a custom attribute used to provide a full name for each area. This is identified with the mapValue option, and is used to simplify creating associated lists. The onGetList callback will provide the keys & values for each unique area.

Setting initial selected state

Startup selected state can be set with area-specific option when the mapster is created, as in the Oklahoma area-specific data above. A programmatic interface is also provided for selecting and deselecting areas.

// Set these states to be initially selected
img.mapster('set',true,'AR,AZ,OK,ME');

Callback options

Several options are events or callbacks, to which you can assign a function to take further action. The function below is an example of a callback for the onGetList option. This shows how the option can be used to generate an associated list dynamically when the mapster is created.

function buildStateList(data) {
    for (var i = 0; i < data.length; i++) {
        var item = $('<div><input type="checkbox" name="' + data[i].key + '">' 
          + data[i].value + '</div>');
        stateslist.append(item);
    }
    /// return the actual elements that you want to be part of the list -- not a container.
    return stateslist.find("input:checkbox");
};

The next function is an example for the onClick callback. In this example we use it to do some additional work when an area is selected or deselected: style the wrapper item for a list element.

function styleElementWrapper(area,object_data) {
    if (object_data.selected) {
        listTarget.parent().addClass('selected');
    } else {
        listTarget.parent().removeClass('selected');
    }
}

This function below is used in the example to return a jQuery object that represents the tooltip container. This could have been applied directly to the option as a string, or as a jQuery object, in this example we are just returning a string to keep the code clean in the configuration above.

function getToolTipContainer() {
  return $('<div style="border: 2px solid black; background: #EEEEEE; 
      position:absolute; width:160px; padding:4px; margin: 4px;"></div>');
}