Overview

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

See the ImageMapster website for full documentation including how to get started, demos, and live examples.

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 still incorporates some of the core rendering algorithm.

Example Usage

Basic usage using default options:

$('img[usemap]').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: 'data-text',           // 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 external list that matches it with 
                                // the image map. These values should correspond with the 
                                // mapKey values from the imagemap.
    listSelectedAttribute:      // an attribute that will be created or removed from the external list
        'checked',              // element 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" data-text="Hawaii" shape="poly" coords="169,391,170,389,172,388,172,389,170,391,169,391">
    .... // additional areas
</map>

The attribute named "data-text" is used to comply with HTML5 standards for data attributes. You are not required to use attribute names beginning with "data", however. This attribute name 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 list. In this example we are using a function 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>');
}