Clickable Imagemaps

Imagemaps are a popular way of handling a lot of "buttons" on your home page. You can send one graphic and then send back different pages based on where the viewer clicked on the graphic. Beware: Folks using text-only browsers or who have turned images off for speed can't use your imagemap! Its usually a better idea to break your graphic up into several sections and link each section to an appropriate page rather than using an imagemap. Folks using Lynx will thank you!

If you've decided to use imagemaps anyway, this document provides a step-by-step tutorial for designing and serving graphical maps of information resources with the built in imagemap support in Why? InterNetworking's web server. Through such a map, users can be provided with a graphical overview of any set of information resources; by clicking on different parts of the overview image, they can transparently access any of the information resources (possibly spread out all across the Internet).

Requirements
Compiling the Imagemap Script
Your First Imagemap
Internal Imagemap Support
A Complete Example
Real-World Examples

Note: Certain newer browsers support Client Side Imagemaps. For more information on Client Side Imagemaps, check out the Spyglass tutorial.

This document is based largely on the tutorial provided with NCSA httpd.

Your First Imagemap

In this section we walk through the steps needed to get an initial image map up and running.

First: create an image.

There are a number of image creation and editing programs that will work nicely (e.g. Adobe Photoshop)

Second: create an imagemap map file.

This file maps regions to URLs for the given image. For a list of tools that may help you create a map file, see Yahoo's Imagemap Directory. For instance, there is a program called mapedit that you could use.

A common scheme for an imagemap is a collection of points, polygons, rectangles and circles, each containing a short text description of some piece of information or some information server; interconnections are conveyed through lines or arcs. Try to keep the individual items in the map spaced out far enough so a user will clearly know what he or she is clicking on.

Lines beginning with # are comments. Every other non-blank line consists of the following:

method URL coord1 coord2 ... coordn

method is one of the following:

default - For the default URL: Coordinates: none
circle - For a circle: Coordinates: center edgepoint
poly - For a polygon of at most 100 vertices: Coordinates: Each coordinate is a vertex.
rect - For a rectangle: Coordinates: upper-left lower-right
point - For closest to a point: Coordinate: thePoint

URL is one of the following:

A Local URL: ex. /docs/tutorials
A Full URL: ex. http://www.yahoo.com/

coord#

Each coord entry is a coordinate, format x,y. The number depends on the method.

Notes:

each method is evaluated in the order it is placed in the configuration file. If you have overlapping areas, such as a circle inside of a rectangle, you should place whichever one you want evaluated first before the other in the map file. In this case, we would put the circle before the rectangle.
Also note that it does not make sense to use the default method with the point method because if even one point method is specified, anywhere you click will be considered close to the point and the URL specified by point will be serviced.
If you will be serving access authentication-protected documents through your imagemap, you MUST use fully qualified URLs, for example
http://www.dirtside.com/path/to/protected/file.html

otherwise access will be denied.

Here is an example imagemap linked from the Mosaic Demo page. Here is what a map file looks like:

default /X11/mosaic/public/none.html

rect http://cui_www.unige.ch/w3catalog    15,8    135,39
rect gopher://rs5.loc.gov/11/global       245,86  504,143
rect http://nearnet.gnn.com/GNN-ORA.html  117,122 175,158

The format is fairly straightforward. The first line specifies the default response (the file to be returned if the region of the image in which the user clicks doesn't correspond to anything).

Subsequent lines specify rectangles in the image that correspond to arbitrary URLs -- for the first of these lines, the rectangle specified by 15,8 (x,y of the upper-left corner, in pixels) and 135,39 (lower-right corner) corresponds to URL http://cui_www.unige.ch/w3catalog.

So, what you need to do is find the upper-left and lower-right corners of a rectangle for each information resource in your image map. A good tool to use on UNIX for this is xv (also on ftp.x.org in /contrib) -- pop up the Info window and draw rectangles over the image with the middle mouse button.

When you upload your .map files, don't forget that you have to use "text" or "ascii" mode! If you use the raw or binary mode, you will get strange results.

Third: referencing your imagemap in your HTML file.

To reference your new map, you construct URLs pointing to it.

For example, if your username is newbie and you have created a sample.map file in the subdirectory called foo in your www directory, and used the image sample.gif for the map, the following line of HTML will reference it:

<A HREF="http://www.dirtside.com/~newbie/foo/sample.map">
<IMG SRC="/~newbie/gifs/sample.gif" ISMAP>
</A>

Fourth: Try it out!

Load the HTML file, look at the inlined image, click somewhere, and see what happens.

A Complete Example

The fish demo in another section of this manual used the following configuration files:

Map Configuration File

The map configuration file used for this picture was rather lengthy. I used xv to get the coordinates.

Reference the map in HTML document:

<A HREF="/docs/info/fish.map"><IMG SRC="fish33.gif" ISMAP> <A>

Real-World Examples

Following are examples of distributed imagemaps on servers in the real world; they may or may not work at any point in time.

For More Information

For more information, see the NCSA HTTPd documentation. See also: Yahoo's imagemap programa list.