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.

Image map

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:
  1. For rectangles, the two coordinate pairs determine the location of two diagonally opposed corners.
  2. 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).
  3. Polygons are automatically closed if the last point is not the same as the first point.
  4. 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.