Imagemaps (Apache: The Definitive Guide)

7.3. Imagemaps

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 he or she wants to do next.

Recently, browsers have improved in capability and client-side mapping (built into the returned HTML script) is becoming more popular. It is also possible to embed an imagemap in the HTML (see http://home.netscape.com/assist/net_sites/html_extensions_3.html). However, here we do it at the server end. The httpd.conf in ... /site.imap is as follows:

User webuser
Group webgroup
ServerName www.butterthlies.com
DocumentRoot /usr/www/site.imap/htdocs

AddHandler imap-file map
ImapBase map
#ImapDefault default.html
#ImapDefault error
ImapDefault referer
ImapDefault map

ImapMenu Formatted

The seven lines of note are the last. AddHandler sets up imagemap handling using files with the extension .map.

7.3.1. ImapBase

ImapBase [map|referer|URL]
Default: http://servername
Server config, virtual host, directory, .htaccess

This directive sets the base URL for the imagemap, as follows:

map: The URL of the imagemap itself.
referer: The URL of the referring document. If this is unknown, http://servername/ is used.
URL: The specified URL.

If this directive is absent, the map base defaults to http://servername/, which is the same as the DocumentRoot directory.

7.3.2. Imap Errors

When things go wrong with imagemaps -- which we shall engineer by setting circles in 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 next item. If this line is not present, then the directive ImapDefault takes over.

7.3.3. ImapDefault

ImapDefault [error|nocontent|map|URL]
Default: nocontent
Server config, virtual host, directory, .htaccess

There is a choice of actions (if you spell them incorrectly, no error message appears and no action results):

error: This makes Apache serve up a standard error message, which appears on the browser (depending which one it is) as something like "Internal Server Error."
nocontent: Apache ignores the request.
map: Apache returns the message Document moved here.
URL: Apache returns the URL. If it is relative, then it will be relative to the imagemap base. On this site we serve up the file default.html to deal with errors. It contains the message:

You're clicking in the wrong place

7.3.4. HTML File

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

<html>
<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> tag 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. It finds the following lines in that file:

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

which 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

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 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 are not limited to rectangles enclosing the cursor. We can have the following objects:

polygons: Invoked with poly, followed by 3 to 100 points. Apache returns the polygon that encloses the cursor.
circles: Invoked with circle, followed by the center and a point on the circle (so if the center is x,y and you want it to have a radius R , the point could be x+R,y or x,y-R). Apache returns the circle that encloses the cursor.
points: Invoked with point, followed by its coordinates. Apache returns the nearest point to the cursor.

We divided the image of the bench into two rectangles:

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

The center points of these two rectangles are:

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 the points above 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

The useful thing about circles for this exercise is that if we click in the corners of the picture we generate an error condition, since the corners are outside the circles, and thereby exercise ImapDefault.

There is a third directive for the configuration file.

7.3.5. ImapMenu


ImapMenu [none|formatted|semiformatted|unformatted]
Server config, virtual host, directory, .htaccess

This directive applies if mapping fails or if the browser is incapable of displaying images. If the site is accessed using a text-based browser such as Lynx, a menu is displayed showing the possibilities in the .map file:

MENU FOR /BENCH.MAP
--------------------------------------
       things
       right.html

This is formatted according to the argument given to ImapMenu. The effect above is produced by formatted. The manual explains the options as follows:

formatted

The argument none redisplays the document sides.html.