Fork Me on Github
ImageMapster Logo

Using ImageMapster

New! Please see this introduction to ImageMapster for absolute beginners. This is a great place to start if you are a novice with JavaScript and jQuery.

If you haven't already, download the script and include it in your page:

    <script type="text/javascript" src="scripts/jquery.imagemapster.js"><script>

To activate all image maps on the page with the default options, just add this inside a script block:

    $('img').mapster();
Usually, you'll want to target a specific image by id, and maybe define some options for how the areas should appear when highlighted. You do this by passing an object with options when you bind the image:
    $('#myimage').mapster({
        fillColor: 'ff0000',
        fillOpacity: 0.3
    });
Once bound, in addition to responding to click events, you can manipulate the effects from Javascript. This would choose all area elements that had a class group1 and cause them to become selected, as if they'd been clicked by the user:
    $('area.group1').mapster('set',true);
You can also define your own keys to identify areas and group them together. Keys are just a value of an attribute on each area. You tell ImageMapster the name of this attribute with the mapKey option, and then you can identify areas or groups of areas by key:
    // an imagemap of the U.S.A

    <img src="..." usemap="#mymap">
    <map name="mymap">
         <area data-key="AZ" href="#" coords="..." />
         <area data-key="AK" href="#" coords="..." />
         <area data-key="AR" href="#" coords="..."/>
         <area data-key="AL" href="#" coords="..." />
         <area data-key="CO" href="#" coords="..." />
         ...
    </map>
    
    // bind using "data-key" as a mapKey, and select four states

    $('#myimage')
        .mapster({
            mapKey: 'data-key'
        })
        .mapster('set',true,'AK,AZ,AR,AL');
There are a lot more options you can use to control how things appear. Keep reading!

Terminology

For many of the concepts and functionality described below, it will help to explain the basic terminology used:

  • area - an area on an image map, specifically, defined by an area tag in the HTML markup.
  • area group - one or more areas that are grouped together logically, each defined by an area tag. Area groups can be manipulated as if they were a single area. Often when discussing functionality I may use "area" and "area group" interchangeably. In most cases, functionality applies an area group, which can be one or more areas. If the distinction is important, though, I will probably say "a specific area."
  • map key - a token used to identify an area or group. While you can use ImageMapster to manipulate things by selecting actual area elements from your HTML, it is often more convenient to refer to an area group. The map key refers to an identifier that you provide for each area, which also creates groups (when you use the same identifier for multiple areas). If you don't want to create any groups and don't want to refer to areas other than via their HTML tags, you do not have to provide a map key.
  • primary key - an area can contain more than one key in the attribute identified by mapKey, separated by commas. The first one is the primary key and defines what areas are higlighted together when an area is clicked. However, you can add more keys to create other groupings, which can be activated using the set method.
  • select - when you select something, it becomes active until deselected. Selecting is like checking a box. It remains selected until deselected.
  • highlight - a highlight, unlike a selection, is temporary, and can only apply to a single area at once. Usually something is highlighted when the user moves their mouse pointer over it, but a highlight can be set programatically as well.
  • static state - areas may also be "static state" which means that their selection state cannot be changed. A static state can either be true or false; when true, an area appears selected, but can never be deselected. Static state does not affect selection state. When querying the state of a static state area, even if it appears selected (because it's static state is true), it's selection stae will always be false.

Methods

  • select - cause an area to become selected or active
  • deselect - cause an area to become deselected or inactive
  • set - select, deselect, or toggle the state of an area or areas
  • get - return the selected state of an area, or a list of all selected areas
  • highlight - set or clear the highlighted area, or return highlighted area
  • unbind - remove ImageMapster bindings, restore everything to it's original state
  • snapshot - remove ImageMapster bindings, but leave appearance unchanged
  • rebind - update options and redraw the imagemap using the new options
  • resize - change the size of a bound image and image map
  • keys - get the map keys for an area, areas or key group
  • set_options - change options without redrawing
  • get_options - get current or effective options for a bound image map
  • tooltip - show or hide tooltips

Options

The following are global options. Each option has the default value in bold, and other possible values separated by a pipe | character. If the value is a type (e.g. boolean, function) then any valid value for that type is acceptable.
  • mapKey: '' | string
    the name of an attribute found on area HTML elements used to identify it for any future operations, and to create groups of areas that function together. When not assigned, all hotspots are activated as unique areas
  • mapValue: '' | string
    the name of an attribute found on area HTML elements used to identify it for any future operations, and to create groups of areas that function together
  • clickNavigate: false | true
    Clicking on a link should cause the browser to navigate to the href whenever it's not a hash sign (#).
  • listKey: '' | string
    an attribute found on elements in a boundList that corresponds to the value of the mapKey attributes.
  • listSelectedAttribute: 'selected' | string
    a boolean attribute that will be added or removed from list target elements when its corresponding map area is selected or deselected.
  • listSelectedClass: null | string
    a CSS class name that will be toggled on a list target elements when its corresponding map area is selected or deselected.
  • areas: [{}, {}, ...]
    define area-specific options; each object in the array must contain a "key" property identifying a valid mapKey, and additional rendering options specific to that area or group
  • singleSelect: false | true (milliseconds)
    delay before removing highlight after mouse leaves an area
  • wrapClass: null | classname | true
    add "classname" class to the wrapper created around the image, or copy classes from the image if "true"
  • wrapCss: null | classname | true
    add CSS to the wrapper created around the image
  • mouseoutDelay: 0 | -1 | n (milliseconds)
    delay before removing highlight after mouse leaves an area
  • sortList: true | false
    when true, sort onGetList data by mapValue key
  • configTimeout: 10000 | integer
    Time in milliseconds to wait for images to load
  • scaleMap: true | false
    Automatically scale image maps to the display size of the image
  • noHrefIsMask: true
    Treat areas with a nohref attribute as masks: if they fall within another area, they will be excluded from the group.
  • boundList: null | jQuery object
    A list of objects bound to the imagemap that will be updated when areas are selected or deselected

Rendering Options

The following are rendering options. Each option has the default global value, and can also be set on a per-area basis using areas option. In additon, rendering options can be set individually for the highlight or select effect, by including them i n special option object render_select and render_highlight. That is, if you put one of these options inside an option called "render_highlight", it will only apply to the highlight effect. You can also put theeffect-specific options into an area-specific option.

For example, this code will cause the stroke effect for both highlights & selections using the default stroke width for selections, and a stroke width of 2 for highlights, for all areas. For the specific area with key "somearea", the stroke is disabled, and for selections only, the fill opacity is 1 (completely opaque) for that area. Finally, for another area with key "someotherarea", the fill effect is disabled, so only the stroke effect which was previously defined globally would apply.

   $(img).mapster({
        stroke: true,
        render_highlight: {
            strokeWidth: 2
        },
        areas: [{
            key: 'somearea',
            stroke: false,
            render_select: { 
                fillOpacity: 1 
            }
        },
        { 
            key: 'someotherarea',
            fill: false
        }]
    });
would cause the stroke effect to apply to both rendering and highlighting; the strokeWidth to be the default value (1) for selecting, and 2 for highlighting, and the fillOpacity to be 1 only for theselection effect, only in the area or group "somearea."
  • fade: true | false
    fade effect - can only be applied to "render_highlight".
  • fadeDuration: 150
  • highlight: null | true | false
    highlight areas on mouseover. When null (default), the behavior is disabled for mobile browsers. You can explicitly enable or disable it by setting this option to a boolean value.
  • staticState: null | true | false
    set an area or the entire map to be permanently selected or permanently deselected
  • selected: false | true
    Set an area to be initially selected.
  • isSelectable: true | false
    Allow an area to be click-selected. When false, an area will still highlight but cannot be selected.
  • isDeselectable: true | false
    Allow an area to be click-deselected. When false, an area can be selected but not unselected by clicking.
  • altImage: null | 'path/to/image.png'
    Use an alternate image of the same size as the imagemap as the source for highlight or select effects
  • altImageOpacity: 0.7,
  • fill: true,
  • fillColor: '000000',
  • fillColorMask: 'FFFFFF',
  • fillOpacity: 0.5,
  • stroke: false,
  • strokeColor: 'ff0000',
  • strokeOpacity: 1,
  • strokeWidth: 1,
The following are area-specific options only (e.g. options defined in the areas array).
  • includeKeys: null | 'key1,key2,...'
    A list of other areas, identified by key, that should be activated whenever this area is activated.
  • isMask: false | true
    Identifies this area as a mask; that is, instead of being rendered, it will be exluded from a surrounding area.

Tooltip Options

  • showToolTip: false | true
    enable tooltips for the image map
  • toolTipContainer: '<div> ... <div> | html string | jQuery object
    markup or jQuery object to wrap tooltips
  • toolTip: null | html | jQuery object
    (area-specific option) the content of the tooltip to be shown for this area
  • toolTipClose: ['area-mouseout', ...]
    define events that cause tooltips to close

Events

The following are events or callbacks - these options can be assigned functions to handle specific input-driven events and take action.
  • onClick: null | function
    callback when a hotspot area is clicked. Return false to cancel default select action, or true to navigate to the 'href'
  • onMouseover: null | function
    callback when a hotspot is entered
  • onMouseout: null | function
    callback when a hotspot is left
  • onGetList: null | function
    callback on map binding containing area group data
  • onConfigured: null | function
    callback when the map has finished intial binding/setup, and it is safe to call other methods
  • onStateChange: null | functon
    callback when an area changes state, either highlight or select
  • onShowToolTip: function
    callback when a tooltip is displayed

Usage

mapster: Bind to all selected images.

$('img').mapster(options);
    

All images in the jQuery object will be bound. The specific example above will attempt to bind to all images present on the page. Each image must be bound to an image map identified with the usemap attribute. If there is no usemap attribute, or it does not refer to a valid map, then the image will be ignored. Therefore you can use this syntax to activate all imagemaps on a page. Because pages often contain many images, though, it will be faster to select just the image you are targeting using a more specific selector.

Images are often not completely loaded when script execution begins. ImageMapster will ensure that all images are loaded before it permits interaction from the client. If an alternate image is specified, this will also be preloaded.

Because images are loaded asynchronously, code execution will often return to your script before the ImageMapster is available. If you apply other methods to it (such as selecting or deselecting areas), these commands will be queued until the image has been loaded, and then executed automatically. So you don't need to worry about using callbacks for initial configuration. You can assign a function to a callback when configuration is complete if needed to perform other setup activities on the page.

Methods

select: Cause an area to become selected. This is similar to a user click, but will not cause a click event to be fired.

$('area').mapster('select');
    

Programatically select elements from the image map. The programmatic selection/deselection methods will not honor the staticState property.

deselect: Cause an area to become deselected

$('area').mapster('deselect');
    

The opposite of select, this causes an area to become deselected. If it was not previously selected, nothing changes.

set: select or deselect an area

$('area').mapster('set',selected,options);
    $('img').mapster('set',selected,key,options);
    ---    
    selected: (optional) bool _whether the area should be selected or deselected_. If missing or false, the area will be deselected.
    options: (optional) object _rendering options_. You can override the default rendering options by supplying an object with additional rendering options.
    

Select or deselect elements from jQuery objects wrapping "area" tags on the map based on truthiness of selected. If the area represents a bound area on the imagemap, it will be selected or deselected. The method can be called from an AREA, or from a bound image, passing a specific key as a 2nd parameter

If the selected parameter is omitted (or anything other than "true" or "false") then the state of each area will be toggled.

You can include an object containing rendering options as the last parameter. When present, these will supercede the default and area-specific rendering options.

get: get keys for all selected areas

$('img').mapster('get',key);
    ---
    key: (optional) string _a single mapKey identifying an area or area group_
    

When no "key" parameter is included, returns a comma-separated list of keys representing the areas currently selected. If specified, returns true or false indicating whether the area specified is selected.

highlight: highlight, clear, or return highlight state

$('img').mapster('highlight')        --> returns map key of current highlighted area or null
    $('img').mapster('highlight',"key")  --> highlight area identified by "key"
    $('img').mapster('highlight',false)  --> remove highlight
    $('area').mapster('highlight');      --> highlight 'area'
    

This method is used to control or obtain the current highlight state. Setting the highlight does not mimic a mouseover, rather, it only sets the highlight. Events and tooltips will not be activated. Even using these methods, it is not possible to highlight more than one area at a time. If another area is highlighted programatically, any existing highlight will be removed.

Once set this way, the highlight will be removed when any user-event that would normally cause a highlight to be removed occurs (e.g. moving the mouse into any area), or it is removed programatically.

unbind: unbind ImageMapster from an image

$('img').mapster('unbind');
    

Removes the ImageMapster binding from an image and restores it to its original state. All visible elements (selections, tooltips) will be removed.

$('img').mapster('unbind',preserveState);
    ---
    preserveState: bool _preserve the current state when unbinding including tooltips and selection overlay_
    

If the optional "preserveState" parameter is true, the selection overlay and any active tooltips will be preserved. Tooltips can still be dismissed by a user click, but once unbound, the selection states can no longer be controlled either by the user or programatically. To remove them, the actual DOM elements must be removed.

Notes: When a mapster is first bound, several things happen. A div element is created which wraps the image. A copy is made of the original image, and the original image is set be transparent. This allows creating visible elements for the selections & highlights without interfering with the image map. Additionally, canvas elements are created (for HTML5 browsers), or a VML elements are created for Internet Explorer, to render the effects. Profile information about each bound image map is stored in memory, and finally, event handlers are bound to the image map.

The "unbind" method cleans up these resources: it removes the wrapper, restores the image to its original visibility state, and releases internal resources. When using 'preserveState', the internal resources are cleaned up and event handling is disabled, but HTML elements are not removed. Each element created by ImageMapster is assigned a class of "mapster_el", which can be used to target them for later removal, though it is not easy to complete this process manually because of the wrapper and styles applied during configuration, which will be left intact when using "preserveState."

snapshot: take a "snapshot" of the current selection state, and reset ImageMapster

This option is similar to unbind with preserveState. After a snapshot, any active selections will still appear as they did at the time of the snapshot, but they are no longer part of the ImageMapster. This is useful for configuring an initial state, or creating complex representations that may not be easily accomplished with area configuration options.

For example, you could bind in image with a specific set of options; programatically select some areas; and take a snapshot; then set new options that cause a different rendering mode. This way you could have certain areas appear differently from the selection highlight, but be "highlighted again" using the new rendering options. Any effects in place at the time of the snapshot essentially become part of the image and are not affected by future operations.

rebind: rebind ImageMapster with new options

$('img').mapster('rebind',options);
    ---
    options: object _a JavaScript object containing ImageMapster options_
    

This method is similar to set_options, in that its purpose is to change options for an existing bound map. However, unlike set_options rebind will immediately apply all the new options to the existing map. This means that rendering options will change areas that are already selected to be rendered with the new options. If you pass area-specific options, these will also be applied, e.g. you could cause new areas to be selected by passing selected: true in an area specific options.

set_options, in contrast only changes the options, and does not apply them to any existing data. When using set_options the new options only apply to future actions.

resize: change the size of the image and map

$('img').mapster('resize',width,height,duration);
    ---
    image: new width of the image  OR
    height: new height of the image
    duration: (optional) 0 | milliseconds (to animate the resizing)
    

This will resize the image map to the dimensions specified. Note that either width or height should be passed, and the other will be calculated in the same aspect ratio as the original image. If you pass both, only the width will be used to calculate the new dimensions: the proportions must remain the same as the original image. (Though I intend to allow scaling without constraining proportions, it will be difficult to make work for certain shapes -- e.g. circles, which would have to become ovals).

This method will recalculate and re-render the entire imagemap, so it will work exactly the same under the new sizing scheme. When the image is unbound, the imagemap will be restored to its original condition.

When using HTML5 canvases, any existing selections, etc. will be preserved during the animation. VML data cannot be resized dynamically, however, so in IE<9 the selections will be erased, then redrawn when the animation is complete.

keys: get the primary mapKey (or comma-separated list of keys) for an area, set of areas, or key group. Version 1.2.4.050

$('img').mapster('keys',key,all);
    $('area').mapster('keys',all);
    ---
    key: string _a single mapKey._ This is required when calling keys against an image.
    all: (optional) bool _when true, returns ALL keys and not just the primary keys.
    

This method allows you to obtain the primary mapKey (or keys) associated with another key, or one or more areas. If the all parameter is true, the method returns all keys or groups that include the area.

When using area groups, it is possible for more than one key to be associated with a map area. It's also possible for an area to be highlighted from code as part of a group, but be inaccessible to the end-user. This is because area groups are separate physical entities from the areas defined by their primary key. They can have different options, and are highlighted independently. Note: the way area groups work is not well documented here yet. I am working on a more comprehensive tutorial for the site. In the meantime please see this example which describes area groups in detail, and shows how they work through an active demonstration.

There are reasons you may want to be able to access the primary keys that make up an area group directly. Perhaps you want to select a group of areas using the options from a group - but not as a separate group. Perhaps you want to be able to compare the area clicked against a group you have defined to take some action if the area is a member of a certain group. This method provides access to that information.

This method allows working with groups in a variety of ways by providing access to a complete list of primary keys in any group, or all keys which contain a given primary key.

set_options: set active options

$('img').mapster('set_options',options);
    ---
    options: object _a JavaScript object containing only options to be updated_
    

When called without the "options" parameter, returns an object with all active options. When the parameter is included, the active options are updated for the imagemap, and any area options are merged with existing area options. Unlike "rebind", this will not rebind or reapply any options, but only update the state. This may affect future actions, but it will not change any existing state information.

get_options: get active options

$('img').mapster('get_options');
    $('img').mapster('get_options',key);
    $('img').mapster('get_options',key,effective);
    ---
    key: string _a single mapKey _
    effective: bool _when true, returns effective rather than assigned options_
    

When called with no parameters, returns the options that the mapster was configured using. When called with a single key it returns the area-specific options assigned to that area. The final parameter effective determines whether the actual options in effect for this area, or the specific options assigned are returned.

Areas inherit the global options assigned, but can be overridden by area-specific options. The "effective" options contain all options including those that are inherited, as well as any specifically assigned to the area.

tooltip: show/hide tooltips from code

$('area').mapster('tooltip')        --> activate tooltip bound to the applied area
    $('img').mapster('tooltip',"key")   --> activate tooltip for area identified by "key"
    $('img').mapster('tooltip');        --> remove active tooltip
    

See the tooltip options section below for options to control how tooltips appear and are dismissed.

This method can be used to manipulate tooltips from code. If the global showToolTip option is false, these methods will still work, so you have the ability to control tooltips bound to areas completely using your own logic, if desired. These methods can also be used to have better control over events needed to close the tooltip, e.g. you could have no tooltip closing event, but add a "close" button to your contianer that will cause the tooltip to close when clicked.

Options and Area Options

Options can be assigned when creating a mapster in the usual jQuery plugin fashion as an object with each property representing an option name and value. Some options can also be applied on a per-element basis (if it makes sense), e.g. any rendering options, selected, staticState, toolTip. To apply options to an area, pass them as an array of objects in the areas option, with a property called key that identifies the area for which these options should apply. The value of key should match one of the keyValues from the areas. For example, if two-letter state codes are used as keys, the following would cause Texas and Alabama to be selected initially:

$('#some_img').mapster({
        areas:  [{
               key: "TX", 
               toolTip: "Don't mess with Texas",
               selected: true
            },
            { 
               key: "AL",
               selected: true
            }]
    });
    

How to use this section

Each option is shown in the following format:

optionName: defaultValue | other | values
    

That is, the first value shown is the default, and any other possible values are shown. If only specific values are permitted, then those values will be explicitly listed separated by a bar |. If any value of a particular type, e.g. string is allowed, then the type will be shown.

Area highlight/selection rendering options

The options below control the way highlighted areas are rendered. Each can be applied globally to the map, or to each element, using the areas option to pass area-specific options. These options apply to either highlighted or selected areas. Highlighting occurs when the mouse enters an area on the image map. Selection occurs when an area is clicked, and selection is enabled. These options will be applied to both situations if present in the root of the options object. They can also be applied to one or the other situations specifically using the render_highlight and render_select options. For example:

options={
        stroke: true,
        fillColor: '222222',
        render_highlight: {
            fillOpacity: 0.2
        },
        render_select: {
            fillOpacity: 0.8
        }
    }
    

The options for stroke and fillColor would be applied to both highlighting and selecting, but different fill opacities would apply to the two different situations. The options which apply are:

fill: true | false
    

Areas should be flood-filled when moused over or highlighted.

fillColor: '000000'

The color used for flood fill.

fillOpacity: 0.2

The opacity of the fill. This is a number from 0 to 1.

stroke: true

Areas should be outlined when moused over or highlighted.

strokeColor: 'ff0000'

The color of the outline.

strokeOpacity: 1

The opacity of the outline.

strokeWidth: 1

The width of the outline.

fade: true

Use a fade effect when highlighting areas on mouseover.

fadeDuration: 150

The duration of the fade-in effect, in milliseconds.

altImage: an image to use as the source of the mouseover and highlight effect.

altImage: 'path/to/image.[gif|png|jpg]'

When specified, the mapster will highlight areas using the image data obtained from the same area in an alternate image, instead of using a fill effect to highlight or select the area. This feature is currently available in browsers with HTML5 canvas support. In practical terms, this means it will work in all commonly used browsers except IE 8 or lower.

If this feature is enabled when an unsupported browser is used, it will fall back to the normal highlight method.

The fill, stroke and opacity effects can be specified independently from those used for the normal higlight effect. This ensures that when your page is viewed with a non-supported browser, you can still control the rendering as would be appropriate for a normal fill/stroke effect, which may be different from when you're using an alternate image.


    altImageFill: true,
    altImageStroke: false,
    altImageOpacity: 0.7
    

At this time, these are the only options that can be specified independently for alternate images from the normal highlighting options. All other effect options will be shared by both highlight rendering methods (e.g. strokeWidth).

Area selection state options

The following options determine behavior for areas.

isSelectable: the map or an area on the map can be selected (or deselected).

isSelectable: true | false
    

When true, the image map will function like a multiple-select menu. Users can click any area to select or deselect it. When applied to the entire map, it determines whether or not the click-selection functionality is enabled. When applied to an area, it determines whether that individual area (or group) can be selected. By default, the map and all areas are selectable.

isDeselectable: the map or area on the map can be deselected.

isDeselectable: true | false
    

Normally true, this option can be used to prevent users from unselecting items once they have been selected. When combined with singleSelect, the effect is that one and only one option can be selected at any given time. Users cannot deselect the active option. This provides a menu-like functionality. It is possible for zero items to be selected if this is the default state (or the only selected item is deselected programatically).

singleSelect: only one area can be selected at a time

singleSelect: false | true
    

When true, only one or zero areas can be selected at any given time. If an area is selected and the user selects another area, the previously selected area will become deselected. Unlike "staticState", this property cannot be overridden by setting areas programatically, only one (or zero) areas can ever be selected when this option is true.

staticState: the map or area is permanently in a selected or deselected state.

staticState: null | true | false
    

When true or false, the map or area to which this option applies will be permanently selected or deselected. Typically this is more useful applied to individual areas that you want to exclude from the interactive part of the map.

staticState forces an area to be always selected or deselected. If set, this will supercede isSelectable. Something with a staticState will always be in that state and it cannot be changed by the user. Note that when setting states programatically, this option will not be honored; it only affects user interaction.

selected: initial selection state of an area.

selected: false | true
    

The area in question is selected. To set default selections when creating a new mapster, use this option for a specific area (see above).

Area grouping and metadata options

mapKey: an attribute identifying each imagemap area.

mapKey: '' | string 
    

If specified, this refers to an attribute on the area tags that will be used to group them logically. Any areas containing the same mapKey will be considered part of a group, and rendered together when any of these areas is activated. If you don't want this functionality, ensure each key is unique. When mapKey is omitted, then each area is considered to be independent from the other and no grouping is applied.

When mapKey is present, any area tags that are missing this attribute will be excluded from the image map e ntirely. This is functionally identical to setting staticState=false for these areas, except they will be inaccessible through the API.

ImageMapster will work with any attribute you identify as a key. If you wish to maintain HTML compliance, it's recommeded that you use attribute names starting with "data-", for example, data-mapkey. Any such names are legal for the HTML5 document type. If you are using older document types, the class attribute is part of the HTML spec for area and will not cause any visual effects, so this is also a good choice. It is not recommended to use id, since the values of this attribute must be unique. title and alt also will cause possibly undesired side effects.

You can specify more than one value in the mapKey attribute, separated by commas. This will cause an area to be a member of more than one group. The area may have different options in the context of each group. When the area is physically moused over, the first key listed will identify the group that's effective for that action.

mapValue: an attribute on each area tag containing additional descriptive information about an area.

mapValue: '' | string | null
    

This option is applicable only when using onGetList. When set, the data provided to the callback function will include the value of this attribute for each group. This can be used to simplify building a list with associated information, without having to match against another resource. It also ties this information to the image map itself. It is not required to use this option when using onGetList.

For example, you could set mapValue: 'data-statename' to an imagemap of the united states, and add an attribute to your areas that provided the full name of each state, e.g. data-statename="Alaska". This text would be included in the onGetList callback, and so you could use it to construct an external list of states.

If there are grouped areas (areas with the same key), then the value from the first area found with data in this attribute will be used.

includeKeys: when rendering an area or area group, also render the areas in the other group (or groups) specified

includeKeys: '' | 'group1,group2,...'          
    

This is an area-specific option that allows you to create supergroups. A supergroup is a collection of groups that will all be highlighted simultaneously, but only when the area that defines the supergroup is moused over or activated through code.

When the area for which this option has been set is activated, all the areas specified in the includeKeys list will also be rendered. This is a one-way relationship. Defining a supergroup in an area causes all the other groups to be highlighted, but not the other way around.

A typical use of this is to define areas that you want to be highlighted when the mouse enters some specific area, but that you do not want to be highlighted on their own if the target area is moused over. This could be a hidden menu, for example: you want the menu to display when the hotspot is moused over, but when it's hidden, mousing over the menu area itself should have no effect.

clickNavigate: Clicking on a link should cause the browser to navigate to the href whenever it's not a hash sign (#). Version 1.2.4.050 and later

clickNavigate: false | true                   
    

By default, ImageMapster will prevent the default browser behavior in image maps, and "select" areas when they are clicked. If you want to navigate to the url for an area, use this option. When enabled, all areas that have an href attribute, and its value is not empty or "#" (just a hashtag).

When area grouping is used, if an href is present for any area in the primary group, this will be used as the navigation target. This way you don't need to copy the url for every area in groups, rather, you can include it on just one, and clicking any area will cause the appropraite navigation.

isMask: the area is a mask rather than a highlighted area.

isMask: false | true                   
    

Normally, every area in an imagemap is an active area, and would be highlighted when moused over (unless its behavior was otherwise specified with staticState). The isMask option allows you to identify an area as being a mask. When a mask is part of an area group, the masked area will be specifically excluded from the rendering of a highlight or selected state.

This is usually used in conjunction, or instead of, the nohref attribute of the area tag. When nohref is specified on an area tag, that area is specifically excluded from the hotspot of any area that encompasses it. It will not respond to mouse events, and will not be highlighted. This can be used to create "holes" in hotspots. By default, ImageMapster will treat any area with nohref or no href tag as masks, the same as if this option had been applied.

Sometimes you won't be able to use nohref to identify something as a mask, for example, if you intend to re-use an area has both a mask, and an independent hotspot. This would be typical if you wanted to a selectable area that was completely included within another selectable area, but functioned independently, such as concentric circles. In this case, you would need to identify the inner circle as both a mask, and a hotspot. The nohref attribute would make it not act as a hotspot, and only function as a mask. You couldn't also select the inner area. You can solve this problem by including the inner circle in two different groups - one group which is a mask for the main area, and another which is an independent selectable area. You can specify different options for each group, so even though it's just one area, it can function as two completely independent ones.

For example, the markup for two concentric circles, both of which are selectable, might look like:

<area shape="circle" group="outer-circle" coords="100,81,59" href="#">
    <area shape="circle" group="inner-circle,outer-circle-mask" coords="101,81,36" href="#">
    

the ImageMapster options would be:

{
        areas: [
            { key: "outer-circle",
              includeKeys: "outer-circle-mask"   // causes the mask to be included when this area is highlighted
            },
            {
                key: "outer-circle-mask",
                isMask: true                     // causes the inner circle to be treated as a mask, but only
                                                 // in the context of the "outer-circle-mask" group
            }
            // no special options needed for "inner-circle" - we want it to be treated normally on mouseover
        ];
    }
    

Please go to the shapes example to see this in action.

There may also be situations where you do not want an area marked with nohref to be treated as a mask. For example, given "area1" and "area2," you may want to create a configuration where mousing over "area1" causes both "area1" and "area2" to be highlighted, but "area2" should not be highlighted on its own when it is moused over. In this situation, you'll need to use "nohref" to prevent the hover behavior for the area, but you still want it to be treated normally when it's rendered as a result of mousing over "area1." You can accomplish this using the noHrefIsMask global option, below.

Generally, masked areas will appear as a window to the underlying image. If stroke is in effect, the stroke will be rendered for the mask as well as the areas, to create both inner and outer borders. You can always specifically enable or disable this, or any other effect, for any area as desired.

noHrefIsMask: Treat areas containing the onhref attribute (or missing the href attribute) as masks. This is true by default.

noHrefIsMask: true | false                  
    

Set this to "false" to disable automatic masking of these areas. You can control them explicitly by creating independent groups for areas you wish to mask and assigning the isMask area-specific option when using this option.

There are some things to be aware of when using nohref and masking:

  • You must put the area that include the nohref attribute before other areas that overlap it, or it will be ignored.
  • You should also explicitly omit the href tag when using nohref.
  • Due to limitations in rendering with VML (e.g. Internet Explorer 6-8), it is not possible to create a true mask, which would allow the underlying image to show through the masked area. Instead, the "masked" areas are rendered on top of the highlighted area in a different color. This can be specified for each area (see the fillColorMask option below) to create the best possible effect.

scaleMap: Automatically scale imagemaps to match the size of a dynamically-scaled image.

scaleMap: true | false
    

When you render an image, you can optionally define a size through CSS or using the "height" and "width" attributes. If omitted, the image will be displayed in its native size. If included, browsers will automatically resize the image to display in the dimensions you have provided.

Starting with 1.1.3, ImageMapster will automatically recalculate all area data to match the effective size of the image. This means that you can set the size of your image to anything you want and ImageMapster will work with no changes at all needed to the "area" data.

If this behavior is not desired for some reason, this can be disabled by setting this option to false.

External list options

boundList: a jQuery object whose elements are bound to the map.

boundList: null | jQuery-object
    

boundList can be any list of objects. To be bound to the map, they must contain an attribute whose name is identified by the option listKey, and whose value matches the value in an area tag's mapKey attribute. If more than one element in the list has the same value, the action will affect all matching elements.

Example of using boundList

listKey: an attribute on items in a boundList that corresponds to the value of the mapKey attributes.

listKey: 'value' | string
    

This is used to synchronize the actions on the imagemap with the actions on a boundList. Each value should match a value from the imageMap mapKey tag. Any item in the boundList with missing or mismatched data will be ignored.

listSelectedAttribute: attribute to set or remove when an area is selected or deselected

listSelectedAttribute: 'selected' | null
    

If boundList is present, when a map area is selected, set or remove this attribute on the list element that matches that area based on their respective keys.

listSelectedClass: a class to add or remove when an area is selected or deselected

listSelectedClass: null | string
    

If a boundList is present, when a map area is selected, this class is added or removed from the corresponding list element. This can be used to easily create any kind of associated action when areas on the map are changed.

Tooltip options

showToolTip: enable tooltips

showToolTip: false | true
    

When showToolTip is true, mapster will look for a property called toolTip in the areas option for a an area. If present, a tool tip dialog will be shown on mouseover for that area. It will automatically be closed according to the behavior specified by toolTipClose. This option does not apply at the item level, but rather enables tooltips for the entire map. At the item level, only the presence of tooltip data is necessary for a tooltip to appear.

Example option defining a tooltip for an area with key "TX":

$('#some_img').mapster({
        ...
        areas:  [{
               key: "TX", 
               toolTip: "Don't mess with Texas"
            }
        });
    

toolTipContainer: HTML describing the popup that will be created for tooltips.

toolTipContainer: '<div> ... </div>' | html string | jQuery object
    

A div with some simple styling is included as the default tooltip container. This can be replaced with anything using this option.

When tooltips are rendered, the code attempts to determine the best place for it. It will try to position it in near the top-left part of the area, and continue to try other corners in order to render it within the confines of the container where the image map resides. If it can't be placed within the image, it will be placed in the lower-right corner and extend outside the image.

toolTip: tool tip data for an area

toolTip: 'text' | jQuery object
    

When this area-specific option is present and showToolTips = true, a toolTipContainer will be created this will be inserted into it, either as inner text (if only text as passed) or as HTML if a jQuery object is passed. In order to pass anything other than plain text using this option you must use a jQuery object. Any string will be treated as plain text (and special characters rendered correctly).

toolTipClose: specify the behavior that causes a toolTip to close.

toolTipClose: ['area-mouseout', ...] | null
    

This option should be passed an array of strings that define the events that cause active tooltips to close. The array can include one or more of the following stings:

  • 'area-mouseout' - tooltips close when the mouse pointer leaves the area that activated it. This is the default.
  • 'area-click' - tooltips close when another area (or the same one) is clicked
  • 'tooltip-click' - tooltips close when the tooltip itself is clicked anywhere
  • 'image-mouseout' - tooltips close when the mouse pointer leaves the image itself.

Under any circumstances, active tooltip will disappear when a new one is created. You don't have to define an automatic closing behavior; setting this option to an empty array will result in tooltips never closing, leaving it to you to close them manually though the tooltip method.

onShowToolTip: callback when a toolTip is created

onShowToolTip: null | function
    

This will call a function when a tooltip is shown, with the following data:

function showToolTipHandler(data) {
         // this = area element bound to the tooltip
          //data = {
                toolTip: jQuery object of the tooltip container
                areaOptions: { area_options },
                key: map key for this area,
                selected: true | false - current state of the area
         };
    } 
    

This can be used to control tooltip closing behavior directly, if desired.

mouseoutDelay: delay removing highlight when mouse exits an area (1.2.5b36)

mouseoutDelay: 0 | -1 | n (milliseconds)
    

Normally, when the user's mouse pointer exits an area, the highlight effect is removed immediately. This behavior can be changed with this option. Setting it to a positive number causes a delay of n milliseconds before the effect is removed. Setting to -1 causes the effect to remain active until another hotspot is entered (e.g., it will only be removed when superceded by a different area being highlighted).

When using mouseoutDelay, the onMouseover event will still be fired at the time the user's mouse pointer leaves the area. However, the onStateChange event will be delayed until the highlight is actually removed.

Whether or not you are using mouseoutDelay, only one area can be highlighted at a time. That is, whenever the mouse pointer moves onto a new active area, any previously highlighted area will become un-highlighted, regardless of any delay in effect. Hovering over a new area will always supercede any delay and cause the new area (and only the new area) to be highlighted at that time. So, for dense imagemaps where most areas adjoin one another, this option may not have much effect within the boundaries of the imagemap. Rather, it is intended to help keep the higlights active for imagemaps that are sparse, or have very small areas.

Callbacks and events

onConfigured: a callback when the mapster has finished initial configuration

onConfigured(success): null | function
    --
    this: mapster bound image
    success: true or false
    

This event is fired when the mapster configuration completes. When control execution continues after a first-time bind operation, the mapster is not guaranteed to be configured, because images are loaded asynchronously by web browsers. If a mapster is bound to an image that is not yet loaded, it will attempt to rebind every 200 milliseconds. This event will be fired when it is eventually successful, or the length of time specified by configTimeout is exceeded (default of ten seconds).

The altImage option will also increase the time needed to configure, because the alternate image is loaded by the client at configure time to ensure it is available immediately when needed.

onClick: a callback when an area is clicked.

onClick(data): null | function
    

This event occurs when the usual click event happens, but includes data from the mapster about the area:

function clickHandler(data) {
        //this = area element clicked
        //data = {
            e: jQuery eventObject
            listTarget: $(item) from boundList
            key: mapKey for this area
            selected: true | false
        };
    }
    

This can be used to perform additional actions on a click without binding another event and having to obtain information manually.

onStateChange: callback when area state is changed (either highlight or select).

onStateChange: function({
                                key: (string) map key,
                                state: (string) "highlight" | "select",
                                selected: (bool) true or false, indicating the current state (following the event)
                              }
    

onStateChange can be used to get more specific information than the mouseover or click events.

onMouseover: callback when mouse enters a bound area.

onMouseover: null | function
    

This function is called when the mouse enters a bound area. The function passes a parameter of the following structure:


    {
        e: object,             // jQuery event object
        options: object  ,     // object of area-specific options
        key: 'string',         // area key
        selected: bool         // true if area is currently selected
    }
    
    

onMouseout: callback when mouse leavesd a bound area.

onMouseout: null | function
    

Callback when the mouse leaves a bound area. The data structure passed to the callback is the same as onMouseover.

onGetList: a callback on mapster initialization that provides summary data about the image map, and expects a jQuery list to be returned.

onGetList: null | function
    

This callback allows you to dynamically provide a boundList based on summary data from the imagemap itself, rather than providing the list up front. The event passes an array of AreaData objects, of the following structure:


    { 
       key: 'key',       // primary mapKey for this area or area group
       value: 'value',   // mapValue for this area or group
       options = {}      // area-specific options defined for this group.
       areas = []        // array of areas that make up this group
    }
    
    
The client should return a jQuery object containing all the elements that make up the bound list, the same as if it was assigned manually. Typical function structure is as follows:

function getListHandler(data) {
        for (var i=0;i<data.length;i++) {
            element = ... // create an HTML element using data[i].key & data[i].value 
            myListContainer.append(element);
        }
        // do not return the container - only the actual elements that make up the list
        return myListContainer.children();
    }
    

The client should return a jQuery object containing all the elements that make up the bound list, the same as if it was assigned manually. Typical function structure is as follows:

sortList: sort the values before calling onGetList

sortList: false | 'asc' | 'desc'
    

If a non-false value or "asc" is passed, the list will be sorted in ascending order by the area value from mapValue. If "desc" is passed, the list will be sorted in descending order.

configTimeout: time (in milliseconds) to wait for images to load before giving up

configTimeout: 10000 | integer
    

When first bound, ImageMapster has to wait for the source image,and any altImage images to load before it can finish binding. This is necessary because otherwise it's not alwasy possible to know the native size of the images. After this period of time, ImageMapster will give up. If you have particularly large pages or images, you may want to increase this to account for long load times.