ImageMapster: A jQuery Plugin to make image maps useful

ImageMapster activates the areas in HTML image maps so you can highlight and select them. It has lots of other features for manual control, tooltips, resizing, and more. It is designed to be compatible with every common platform, and is tested with Internet Explorer 6-10, Firefox 3.0+, Safari, Opera, and Chrome. It works on mobile devices and doesn't use Flash.

Release Information

See the change log for details on the release history and roadmap.

Read the release notes for 1.2.5, the last significant feature update.

Getting Started

Installation

NPM

This package can be installed via NPM:

npm install jquery imagemapster --save

Browser

⚠️ Warning

As of ImageMapster v1.3.0, if targeting ES5 browers, you must include a Promise polyfill such as es6-promise. See Issue 341 for details.

Download the latest version of ImageMapster from the Releases page and include in your webpage:

<!-- Optional: If targeting ES5 browers, as of ImageMapster v1.3.0, a Promise polyfill is required! -->
<script
  type="text/javascript"
  src="https://cdn.jsdelivr.net/npm/es6-promise/dist/es6-promise.auto.min.js"
></script>
<script
  type="text/javascript"
  src="https://ajax.googleapis.com/ajax/libs/jquery/3.7.1/jquery.min.js"
></script>
<script type="text/javascript" src="jquery.imagemapster.min.js"></script>

Alternatively, you can include ImageMapster from one of the following CDNs:

1. jsDelivr - https://www.jsdelivr.com/package/npm/imagemapster
2. cdnjs - https://cdnjs.com/libraries/imagemapster

Usage

Activate all image maps on the page with default options: on mouseover areas are highlighted with a gray fill with no border, and clicking an area causes it to become selected.

$('img[usemap]').mapster();

Activate all image maps on the page with some specific options.

$('img[usemap]').mapster({
  fillColor: 'ff0000',
  stroke: true,
  singleSelect: true
});

Methods

There are lots of ways to manipulate the image map from Javascript. Here area a few, see the ImageMapster web site for complete documentation.

select: Cause an area to become "selected"

$('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');

set: select or deselect an element. If selected is true, the area is selected, if false, it is deselected.

$('area').mapster('set', selected);

You can also select or deselect areas using a their mapKey. This is an attribute on each area in your HTML that identifies it. You define a mapKey using a configuration option: mapKey: 'data-key'.

$('img[usemap]').mapster('set', true, 'key1,key2');

If two areas share the same value for the mapKey they will be automatically grouped together when activated. You can also use the values of the mapKey to select areas from code.

You can pass options to change the rendering effects when using set as the last parameter:

$('img[usemap]').mapster('set', true, 'key', { fillColor: 'ff0000' });

MapKeys can contain more than one value. The first value always defines groups when you mouse over. Other values can be used to create logical groups. For example:

<img id="usamap" src="map.jpeg" usemap="#usa" />
<map name="usa">
  <area data-key="maine,new-england,really-cold" shape="poly" coords="..." />
  <area
    data-key="new-hampshire,new-england,really-cold"
    shape="poly"
    coords="..."
  />
  <area data-key="vermont,new-england,really-cold" shape="poly" coords="..." />
  <area data-key="connecticut,new-england" shape="poly" coords="..." />
  <area data-key="rhode-island,new-england" shape="poly" coords="..." />
  <area data-key="massachusetts,new-england" shape="poly" coords="..." />
  <!-- more states... -->
</map>

$('#usamap').mapster({ mapKey: 'data-key' });

Mousing over each state would cause just that state to be higlighted. You can also select other logical groups from code code:

// select all New England states
$('#usamap').mapster('set', true, 'new-england');

// select just Maine, New Hampshire & Vermont
$('#usamap').mapster('set', true, 'really-cold');

Groups created this way are independent of the primary group. If you select "new-england" from code, you can't unselect just "MA" by clicking on it. You would have to unselect "new-england" from code.

To simply indentify a set of areas to turn on or off, but not treat them as a logical group, you can use CSS classes and select areas directly, or use the keys option to identify the primary keys associated with a group (see documentation).

Options

Please see the ImageMapster web site for complete documentation.

Demos

ImageMapster includes several examples. To view the examples:

1. Clone the repo
2. Open index.html directly from your file system in a browser

ℹ️ Note

By default, examples will run using jQuery. To run examples using Zepto, modify the examples HTML file per the information in Development -> Examples.

Zepto Compatibility

As of ImageMapster v1.3.2, ImageMapster contains full support for Zepto v1.2.0. The latest Zepto compatible version of ImageMapster is 1.6.0.

Prior to ImageMapster v1.3.2 and with any version of Zepto except v1.2.0, ImageMapster is unlikely to work as expected. In the early versions of ImageMapster, Zepto support was maintained, however due to changes in Zepto, as of v1.2.5 of ImageMapster, support for Zepto compatability was not maintained as it required too much effort and pushing ImageMapster forward with jQuery was the priority.

⚠️ Warning

Given that Zepto is no longer actively developed and with plans in the ImageMapster Roadmap to convert to a Native JS Library, ImageMapster will be officially dropping support of Zepto as of ImageMapster v2.0.0.

To use ImageMapster >= v1.3.2 < 2.0.0 with Zepto v.1.2.0, Zepto must contain the following Zepto Modules at a minimum:

• zepto
• event
• ie
• fx
• touch
• selector (required as of v1.5.0)

Browser - Zepto

⚠️ Warning

As of ImageMapster v1.3.0, if targeting ES5 browers, you must include a Promise polyfill such as es6-promise. See Issue 341 for details.

Download the latest Zepto version of ImageMapster from the Releases page and include in your webpage making sure to use jquery.imagemapster.zepto.min.js or jquery.imagemapster.zepto.js:

<!-- Optional: If targeting ES5 browers, as of ImageMapster v1.3.0, a Promise polyfill is required! -->
<script
  type="text/javascript"
  src="https://cdn.jsdelivr.net/npm/es6-promise/dist/es6-promise.auto.min.js"
></script>
<script type="text/javascript" src="/path/to/your/custom/zeptodist"></script>
<script
  type="text/javascript"
  src="/path/to/cdn/for/v1.6.0/dist/jquery.imagemapster.zepto.min.js"
></script>

Alternatively, you can include the Zepto version of ImageMapster from one of the following CDNs:

1. jsDelivr - https://www.jsdelivr.com/package/npm/imagemapster?version=1.6.0
2. cdnjs - https://cdnjs.com/libraries/imagemapster/1.6.0

NPM - Zepto

The maintainers of Zepto decided not to support any module loaders so there is no official support of Zepto using AMD/CJS/etc. Given this, the Zepto version of ImageMapster expects a dependency of jquery when using a module loader. The Zepto version of ImageMapster will work with jQuery or Zepto. If you'd like to utilize Zepto, there are some projects that wrap Zepto and support UMD such as zepto-modules. In order to use Zepto, you will need to configure your bundler to map jquery to your Zepto build.

Using webpack and zepto-modules as an example:

Install from NPM

npm install zepto-modules imagemapster@1.6.0 --save

src/yourzepto.js

var $ = require('zepto-modules/zepto');

require('zepto-modules/event');
require('zepto-modules/ie');
require('zepto-modules/fx');
require('zepto-modules/touch');
require('zepto-modules/selector');

module.exports = $;

src/yourmodule.js

import $ from './yourzepto.js';
import im from 'imagemapster/dist/jquery.imagemapster.zepto.js';

$(yourImage).mapster({
  // your config here
});

webpack.config.js

module.exports = {
  resolve: {
    alias: {
      jquery: path.resolve('./src/yourzepto')
    }
  }
};

Find out More

Please see how to obtain ImageMapster Support.

Contributing

Please see our Contributing Guidelines.

Development

Build

The source code is broken into several modules to make management easier and to make it possible to create feature-targeted builds. ImageMapster is built using grunt and can be invoked as follows:

1. Clone the repo
2. Install NPM dependencies - npm install
3. Generate a Build:
   • Debug Build (uncompressed) - npm run build
   • Release Build (uncompressed/compressed/sourcemap) - npm run dist

Debug

1. Clone the repo
2. Install NPM dependencies - npm install
3. Run the debug task - npm run debug

Tests

1. Clone the repo
2. Install NPM dependencies - npm install
3. Run the test task - npm run test

ℹ️ Note

By default, tests will run using the latest version of jQuery. The library to use when running tests can be changed via the dropdown.

Examples

1. Clone the repo
2. Install NPM dependencies - npm install
3. Run the example task - npm run example

ℹ️ Note

By default, examples will run using jQuery. To run examples using Zepto, modify the examples HTML file (e.g., USA) as follows, commenting out references to jQuery scripts and uncommenting references to zepto scripts.

...

+ <!--
  <script type="text/javascript" src="redist/jquery.3.7.1.min.js"></script>
  <script
    type="text/javascript"
    src="../dist/jquery.imagemapster.js"
  ></script>
+ -->
- <!-- <script type="text/javascript" src="redist/zepto.1.2.0.min.js"></script>
+ <script type="text/javascript" src="redist/zepto.1.2.0.min.js"></script>
  <script
    type="text/javascript"
    src="../dist/jquery.imagemapster.zepto.js"
- ></script> -->
+ ></script>

...

Docs

ℹ️ Note

The docs have not been maintained and therefore are not under version control.

1. Clone the repo
2. Install NPM dependencies - npm install
3. Run the doc task - npm run doc

License

Copyright © 2011-24 James Treworgy. Licensed under the MIT License.