FAQ

How do I...

I get a lot of questions, and I am happy to help whenever I can! I also am well aware that it can be hard to figure out how to solve a tricky problem with imagemapster. You can always shoot me an email (my address is on the About page) but try this first:

• Take a look at the demos page -- especially the very last section, "Fiddle With It." I've linked to a number of online demos on jsfiddle where you can see the code and tinker with it yourself. This is the best way to learn!
• Check out githib - there are lots of questions in the issues section. I've flagged some of them as "support", but just use the great "search" tool to see if someone's asked a similar question.
• Look at the "feedback" page -- a lot of one-off questions have been asked and answered there.
• Check StackOverflow -- There's a small but growing archive of ImageMapster-related questions, and I always try to answer them when I see them there. We're not quite the beatles, but we're big in Europe, I hear.

.... if you still can't figure it out, feel free to post a question on StackOverflow, or contact me directly, and I'll do my best to help you.

Is ImageMapster free?

Yes. You can use it in any way you want to, under the terms of the MIT license. If you use ImageMapster in your work, especially in a public web site, I would appreciate you telling me about it. You don't have to, I just like knowing what people are doing with it.

If you feel ImageMapster has been extraordinarily useful to you, you can contribute directly to my coffee fund:

Other ways to contribute:

• Write code: Fork the project on github. Add features, or write tests to fill out some areas currently not well covered by the test suite.
• Share your public project: Send me an interesting demonstration to add to the web site, or let me link to your site using ImageMapster.
• Help me with this web site: At a minimum, the docuementation could be better. I am a bad technical writer.
• Let me know how it works for you: In particular I am interested in feedback from users of mobile devices. I test on an iPad and my Motorola Android phone, but have very little information about how it works on many other devices.

What are the dependencies?

The only dependency is jQuery. It should with with 1.4 or later, though I do not test with older versions on a regular basis. If you find a problem related to an older verison of jQuery let me know about it, or just upgrade.

Can I use Zepto instead of jQuery?

As of the current development release (post 1.2.4) ImageMapster can work with Zepto as a drop-in replacement for jQuery. Unless your application is targeting only webkit/mobile environments specifically supported by Zepto, you should make sure to test the user agent and load either jQuery of Zepto as appropriate before loading ImageMapster.

ImageMapster can be run with a subset of Zepto: it requires only the core zepto.js and event.js modules. The animated resize method also requires fx.js

There's a separate build of ImageMapster for use with Zepto, jquery.imagemapster.zepto.js. It's called this because it works with jQuery OR Zepto. The regular build only works with jQuery. This is because I had to add code to fill some holes in Zepto for ImageMapster to work right. Because this increases the size of ImageMapster a little bit, and this extra weight isn't needed for jQuery (as those features exist already in jQuery), I decided to distribute two different builds. If your application is designed to use either Zepto or jQuery depending on the client's browser, then you can safely use the Zepto build for all users- there's no downside except a little extra code.

What browsers are supported?

ImageMapster supports all major browsers:

• Chrome 4+
• Firefox 2+
• Internet Explorer 6+
• Opera 9+
• Safari & other webkit browsers

Are there any known bugs or features that don't work in some supported browsers?

• With Internet Explorer 6-8, the altImage feature is not supported, as HTML5 canvas support is needed for this. ImageMapster will still fall back to normal fill rendering if this feature is used with IE6-8.
• With Firefox 3.6masks do not work properly and the outer area may not be highlighted. This is because of a bug in Firefox 3.6. It would be possible to code around it but I've decided it's not worth creating a new code branch to support one specific, old browser version. Marks work properly in older and newer versions of Firefox.

Does it work on iPhones / iPads / Androids / mobile / touchscreen devices?

Yes. It works on any device that supports HTML5 canvases, and that includes all of these, that I know of. I test regularly on an iPad and Android phone with Opera Mobile, Dolphin HD, and the native browser.

Caveats: I have found that iPads and iPhones work reliably in complex scenarios. On some older Android devices, the native web browser does not seem to handle image load events well, and complex scenarios may require special handling. For example, the demo page on this web site is a complex scenario: there are 2 imagemaps in the site header (the github logo, and the header). The content is loaded asychronously, and contains 6 more imagemaps that are bound when the content is loaded. Some of the imagemaps use alternate images, which must be loaded completely before binding.

On this web site, I have disabled ajax navigation for Android devices to deal with this. There may be a better solution, but I'm not really a mobile developer so I haven't taken the time to investigate it thoroughly. Like anything else, always test thoroghly. If you find scenarios where binding does not work properly, please let me know by creating an issue on github. I am always trying to make things better.

How do I make image maps?

There are lots of ways to do this.

1. Use an online tool. Image Mapper is my favorite. It's deceptively simple looking, but it works great. It will only create polygons, though. If you want to create circles or rectangles you can still use it to get coordinates, but you'll have to code the area manually. Most of the time, though, you want polygons anyway.
2. Commercial drawing tools like Photoshop have capabilities to create imagemaps.
3. If you're creating a map for a geographical entity, like states or countries, someone's probably done it already. Google is your friend. Check Wikipedia Commons for public domain maps, too.

How can I scale image maps to a different size?

You can let ImageMapster do it for you with the scaleMap option. It will automatically adjust the map data when it detects that an image is not being shown in its native size. Most of the time, this is what you'd want, because most of the time an HTML image map would be designed around the native size of an image. If you don't want this behavior for some reason, you can turn set scaleMap: false and ImageMapster will not try to adjust your image map no matter what.

If you just want to use an image at a different size than the imagemap you happen to have represents, and would rather not have your users download an image at a larger size than you need, then you can transform it to the correct size using the Image Map Resizer tool on my blog. This tool will also let you define a clipping area if you want to create a new imagemap that represents a cropped area within a map you already have.

Couldn't I do something like this with CSS3?

With CSS3 you can accomplish some similar functionality, but managing the data is much more difficult, and irregularly shaped areas would be next to impossible to implement. More sophistocated effects would also be impossible without the use of canvases.

What about SVG?

An imagemap doesn't really do anything other than let the browser detect when the mouse enters and leaves predefined areas. You can do the same thing with SVG data, but SVG doesn't exist in some older browsers, whereas imagemaps exist in all browsers.

You can convert SVG data to an HTML imagemap without too much trouble. Here are a couple resources:

• Create a PNG or JPEG image map from SVG
• Inkscape Map

The actual data and shapes used by SVG and HTML image maps are pretty much identical so it's really a matter of transforming the markup. If I ever need to do this I'll probably write a script, it just hasn't come up for me yet.