Using ImageMapster
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 group1and 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 setmethod.
-
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
JS Tutorial
