Imagemaps (Apache: The Definitive Guide, 3rd Edition)

We have experimented with various sorts of indexing. Bearing in mind that words are going out of fashion in many circles, we may want to present an index as some sort of picture. In some circumstances, two dimensions may work much better than one; selecting places from a map, for instance, is a natural example. The objective here is to let the client user click on images or areas of images and to deduce from the position of the cursor at the time of the click what she wants to do next.

7.3.1. HTML File

The document we serve up is ... /htdocs/sides.html:

<!DOCTYPE HTML PUBLIC "//-W3C//DTD HTML 4.0//EN"
<html>
<head>
<title>Index to Butterthlies Catalogues</title>
</head>
<body>
<h1>Welcome to Butterthlies Inc</h1>
<h2>Which Side of the Bench?</h2>
<p>Tell us on which side of the bench you like to sit
</p>
<hr>
<p>
<p align=center>
<a href="bench.map">
<img ismap src="bench.jpg" alt="A picture of a bench">
</a>
<p align=center>
Click on the side you prefer
</body>
</html>

This displays the now-familiar picture of the bench and asks you to indicate which side you prefer by clicking on it. You must include the ismap attribute in the <IMG> element to activate this behavior. Apache's ImageMap handler then refers to the file .../site.imap/htdocs/bench.map to make sense of the mouse-click coordinates.

7.3.2. Map File

It finds the following lines in the file .../site.imap/htdocs/bench.map:

rect left.html 0,0 118,144
rect right.html 118,0 237,144

#point left.html 59,72
#point right.html 177,72

#poly left.html 0,0 118,0 118,144 0,144
#poly things 0,0 118,0 118,144 0,144
#poly right.html 118,0 237,0 237,144 118,114

#circle left.html 59,72 118,72
#circle things 59,72 118,72
#circle right.html 177,72 237,72

default default.html

The coordinates start from 0,0, the top-lefthand corner of the image. rect s are rectangles with the top-left and bottom-right corners at the two x,y positions shown. point s are points at the x,y position. poly s are polygons with between 3 and 100 corners at the x,ys shown. circle s have their center at the first x,y — the second is a point on the circle. The point nearest to the cursor is returned; otherwise, the closed figure that encloses the cursor is not returned. As it stands only the rect s are left uncommented. They set up two areas in the left and right halves of the image and designate the files left.html and right.html to be returned if the mouse click occurs in the corresponding rectangle. Notice that the points are expressed as x,y <whitespace>. If you click in the left rectangle, the URL www.butterthlies.com/left.html is accessed, and you see the message:

You like to sit on the left

and conversely for clicks on the right side. In a real application, these files would be menus leading in different directions; here they are simple text files:

You like to sit on the left
You like to sit on the right

In a real system, you might now want to display the contents of another directory, rather than the contents of a file (which might be an HTML document that itself is a menu). To demonstrate this, we have a directory, ... /htdocs/things, which contains the rubbish files 1, 2, 3. If we replace left.html in bench.map with things, as follows:

rect things 0,0 118,144
rect right.html 118,0 237,144

we see:

Index of /things
. Parent Directory
. 1
. 2
. 3

You do not have to restart Apache when you change bench.map, and the formatting of this menu is not affected by the setting for IMapMenu.

How do we know what the coordinates of the rectangles are (for instance, 0,0 118,144)? If we access sides.html and put the cursor on the picture of the bench, Netscape/MSIE helpfully prints its coordinates on the screen — following the URL and displayed in a little window at the bottom of the frame. For instance:

http://192.168.123.2/bench.map?98,125

It is quite easy to miss this if the Netscape window is too narrow or stretches off the bottom of the screen. We can then jot down on a bit of paper that the picture runs from 0,0 at the top-left corner to 237,144 at the bottom-right. Half of 237 is 118.5, so 118 will do as the dividing line.

We divided the image of the bench into two rectangles:

0,0 118,144
118,0 237,144

These are the center points of these two rectangles:

59,72
177,72

so we can rewrite bench.map as:

point left.html 59,72
point right.html 177,72

and get the same effect.

The version of bench.map for polygons looks like this:

poly left.html 0,0 118,0 118,144 0,144
poly right.html 118,0 237,0 237,144 118,114

For circles, we use these points as centers and add 118/2=59 to the x-coordinates for the radius. This should give us two circles in which the cursor is detected and the rest of the picture (right in the corners, for instance) in which it is not:

circle left.html 59,72 118,72
circle right.html 177,72 237,72

When things go wrong with ImageMaps — which we can engineer by setting circlesin bench.map and clicking on the corners of the picture — the action to take is set first by a line in the file bench.map :

default [error|nocontent|map|referer|URL]

The meanings of the arguments are given under the ImapDefault above. If this line is not present, then the directive ImapDefault takes over. In this case we set:

default default.html

and the file default.html is displayed, which says:

You are clicking in the wrong place.

7.3. Imagemaps

7.3.1. HTML File

7.3.2. Map File