Writing .map files
The primary use of .map files is to handle the requests
generated by clients when using the ISMAP HTML feature
to create clickable pictures.
Example
The following image is an image map. Click anywhere in the picture and see
where it takes you. After each time, go back and click somewhere else. Try out
the rectangle, the triangle, etc. Depending on where you clicked, the browser
will retrieve different documents.

What happens behind the scenes
When you click on such a picture your client will generate a
request to the server with the pixel coordinates appended to
the URL specified. For example, suppose your HTML document contained the
following bit of code:
<A HREF="test.map"><IMG ALT="Image map" SRC="images/test.gif" ISMAP></A>
and the user were to click on the image, the browser might generate a request
like this:
http://www.signum.se/phttpd/docs/user/map/test.map?123,454
That is, it follows the link as it would normally, but because of the ISMAP
attribute of the IMG element, the coordinates of the click are appended to the
URL.
In response to this, the server looks at the test.map
file and
sends back a redirect to the URL corresponding to the coordinates clicked. The
browser then goes out and retrieves the document. If no URL is associated with
the coordinates, the server sends back a special "No response" code and the
browser does nothing.
Setting up your own image map
First, you need to create a text file containing the map coordinates and the
corresponding URLs. In the example above, the map file looked like this:
rect rect.html 10,70,90,90 # this is a rectangle
circle circ.html 30,50,45,50 # this is a circle
poly tri.html 55,65,73,41,90,65 # this is a triangle
point left.html 30,18 # this is the left point
point right.html 73,18 # this is the right point
Each line defines a "hot zone" in the image. The coordinate system has its
origin in the lower left corner (i.e. (0,0) is the left most pixel in the
bottom row). There are four kinds of hot zones that can be defined:
Rectangles, circles, polygons and points. In addition, one can define a
default URL which is to be applied if no other hot zone applies.
Once you have created the map, you point to the image file and this
.map file in your HTML document, by writing something like this:
This is a clickable image:
<P>
<A HREF="sample.map">
<IMG SRC="fine-picture.gif" ISMAP>
</A>
Format of the map file
The server looks at the file line by line and checks if the coordinates match
the specified hot zone. The first line that matches is used, unless it
specifies the default. Everything following a `#' up to the end of the line is
ignored and can be used as a comment. If no line matches, the default URL is
used, or if there is no default, a "No response" status code is
generated.
Both the NCSA server and the CERN server included image map programs in their
distribution since early on, but they each use different formats for their map
files. Since both formats are widely used and since tools exist which can
create maps in either format, the map module was programmed to recognize both
formats.
The map lines can appear in either of these formats:
- NCSA
- shape URL coordinates
- CERN
- shape coordinates URL
In addition, the default URL can be specified as
default
URL
shape defines the shape of the hot zone and can be one of
rect
, circle
, poly
, or
point
. The coordinates are a comma separated list of numbers. In
the CERN format, coordinate pairs are delimited by parentheses. These are the
formats for the various shapes:
| NCSA | CERN
|
---|
rect | x1,y1 x2,y2 | (x1,y1) (x2,y2)
|
---|
circle | x1,y1 x2,y2 | (x1,y1) r
|
---|
poly | x1,y1 x2,y2 ... | (x1,y1) (x2,y2) ...
|
---|
point | x1,y1 | (x1,y1)
|
---|
Notes:
- For rectangles, the two coordinate pairs determine the location of two
diagonally opposed corners.
- In the NCSA format, circles are defined by the center point (x1,y1) and
a point on the circle itself (x2,y2). In the CERN format, circles are
defined by the center point (x1,y1) and the radius (r).
- Polygons are automatically closed if the last point is not the same as
the first point.
- Points do not actually define hot zones, but act as default values. If
no other hot zone matches, the point that is closest to the user's
click is used. Points always override any default URL.
What if the browser does not support image maps?
There may be a number of reasons why a browser does not support the ISMAP
attribute in images. The most common one is that the browser does not display
graphics. If a user follows the link to the map file using such a browser, a
request is issued without or with invalid coordinates. In such cases, the
server attempts to display the map as a menu of URLs. This should allow users
of text-based systems or blind users to make use of image maps as well. Here
is an example of an invalid map URL:
test.map
Try to follow the link and see what happens. You should get a textual display
of the map.