# jQuery maphilight documentation

maphilight applies to images with a 'usemap' attribute, and outlines the areas defined in their map on mouseover.

It provides a single jQuery function: `$('.foo').maphilight()`

This would hilight every image with a map on the page: `$('img[usemap]').maphilight()`

## Demos

The simple demo (with awful art, and examples of data attributes)

A map of the world

A map of the USA

A few feature-demonstrations

## Plugin methods

`maphilight( [options] )`: returns jQuery
  Add hilight behavior to an imagemap
`$.maphilight.defaults`
  Default settings for all maphilight calls

### `maphilight( [options] )`

- Overview
- Options

The method that adds hilight behavior to an imagemap.

#### Arguments:

`options` (optional)

  A set of key/value pairs that configures the map. All options are optional.

  All options can be overridden with the jQuery `data` method, per-`img` and per-`area`.

  The metadata plugin is also supported.

  Order of inheritance:

  1. `$(area).data('maphilight')`
  2. `$(area).metadata()`
  3. `$(img).data('maphilight')`
  4. `$(img).metadata()`
  5. `$(img).maphilight(options)`

  Example: to make one particular hilight green:

      <area ... class="{fillColor:'00ff00'}">

#### Options:

`fill` (Boolean. Default: true)
  Whether to fill the shape
`fillColor` (String. Default: '000000')
  The color to fill the shape with
`fillOpacity` (Number. Default: 0.2)
  The opacity of the fill (0 = fully transparent, 1 = fully opaque)
`stroke` (Boolean. Default: true)
  Whether to outline the shape
`strokeColor` (String. Default: 'ff0000')
  The color of the outline
`strokeOpacity` (Number. Default: 1)
  The opacity of the outline (0 = fully transparent, 1 = fully opaque)
`strokeWidth` (Number. Default: 1)
  The thickness of the outline
`fade` (Boolean. Default: true)
  Whether to fade in the shapes on mouseover
`alwaysOn` (Boolean. Default: false)
  Whether to always show the hilighted areas
`neverOn` (Boolean. Default: false)
  Whether to never show the hilighted areas
  (This only makes sense to use as per-area metadata, of course.)
`groupBy` (String. Default: false)
  The name of an attribute to group areas by
  If this is present then all areas in the map which have the same attribute value as the hovered area will hilight as well
`wrapClass` (String/bool. Default: false)
  If true, applies the class on the <img> to the wrapper div maphilight created.
  If a string, that string is used as a class on the wrapper div.
`shadow` (Boolean. Default: false)
  Whether to apply a shadow to the shape. (Only works with canvas-supporting browsers. So, everything but IE below version 9.)
`shadowPosition` (String. Default: 'outside')
  Where to position the shadow. Can be 'outside', 'inside', or 'both'.
`shadowFrom` (String/bool. Default: false)
  What to use to cast the shadow. Can be 'stroke' or 'fill'. If false, choose a value based on the shadow position. (Generally it looks better if it's being cast from a fill when it's outside the shape, and from a stroke when it's inside the shape.)
`shadowX` (Number. Default: 0)
  Horizontal offset of the shadow from the shape.
`shadowY` (Number. Default: 0)
  Vertical offset of the shadow from the shape.
`shadowRadius` (Number. Default: 6)
  Size of the shadow.
`shadowColor` (String. Default: '000000')
  Color of the shadow.
`shadowOpacity` (Number. Default: 0.8)
  Opacity of the shadow.

### `$.maphilight.defaults`

The defaults for all uses of maphilight can be set here. If you manually replace this, you have to specify all options.

    $.fn.maphilight.defaults = {
    	fill: true,
    	fillColor: '000000',
    	fillOpacity: 0.2,
    	stroke: true,
    	strokeColor: 'ff0000',
    	strokeOpacity: 1,
    	strokeWidth: 1,
    	fade: true,
    	alwaysOn: false,
    	neverOn: false,
    	groupBy: false,
    	wrapClass: true,
    	shadow: false,
    	shadowX: 0,
    	shadowY: 0,
    	shadowRadius: 6,
    	shadowColor: '000000',
    	shadowOpacity: 0.8,
    	shadowPosition: 'outside',
    	shadowFrom: false
    }

## Changelog

- 1.2.2: New options groupBy and wrapClass. Allow .data to override options/metadata. Work around a jQuery bug with Opera.
- 1.2.1: Fix a Chrome bug. Apply the class on the img to the wrapper div created by maphilight.
- 1.2: Made `alwaysOn` work per-area with metadata plugin.
- 1.1: Added `alwaysOn` option. Fixed behavior in Firefox2/Safari/Opera.
- 1.0: First release.

## Tested with

- Firefox
- IE 6, 7, 8, 9
- Safari 3, 4, 5
- Chrome
- Opera 9, 10

## Contributors

These people have contributed in some way to the project:

- Billy Earney (@ University of Missouri): fixed alwaysOn for IE
- Travis Balzarini (@ Sonoma County Web Team): fixed IE 8
- SolutionYogi: Also fixed IE 8 :)
- Florian Staudacher: provided the initial version of shadows