Using Apache Imagemaps

Imagemaps can provide a graphical interface to a web site. If the mouse is clicked over an imagemap image the co-ordinates of that click are sent to the server. The server can decide what page to return based on the location of the click.

Traditionally, imagemaps have been implemented at the server end with a CGI program (usually called 'imagemap'). This is configured with a map file which listed what regions on the image correspond to what documents to return. Apache can use CGI imagemaps, but it is more efficient to use the internal imagemap module. This module, compiled in by default, means that the server does not need to run a separate process to handle the image clicks. It is fully upwardly compatible, and also adds some new features. Both of these approaches implement what are called server-side imagemaps because all the processing happens on the server.

The main problem with server-side imagemaps is that the user does not get any indication of which areas of the image contain links. An extension to HTML allows client-side imagemaps which tell the browser what areas on the image correspond to what documents. The browser can then highlight or show the active areas as desired. It is possible to use both client-side and server-side imagemaps at once, so that the maximum number of browsers are supported.

Older versions of Apache came with an imagemap program in the cgi-src directory. This could be compiled and placed into a CGI directory (typically cgi-bin). The internal imagemap module is faster than using the CGI program and it has replaced all of the functionality.

If you are using the imagemap program, you can easily move over to using the imagemap module. First, ensure that an appropriate AddHandler line is enabled in your srm.conf file (see the following section). Then all you need to do is update the HTML documents that refer to the imagemap program. You will probably be using something similar to this:

  <A HREF="/cgi-bin/imagemap/maps/mapfile">
    <IMG SRC="image.gif" ISMAP></a>

You need to first of all rename your mapfile to have a suitable extension (as given on the AddHandler imap-file line, for example, .map) if is does not already have this extension. Then change the HTML like this:

  <A HREF="/maps/mapfile.map">
    <IMG SRC="image.gif" ISMAP></a>

Note that the HREF is now simpler because the /cgi-bin/imagemap part is not given.

The imagemap module is a core part of Apache, and is compiled in by default. To use it, you first need to configure the Apache server. You should pick a file extension to use for imagemap configuration files, typically .map. The AddHandler command below should be added to your srm.conf file:

  AddHandler imap-file map

You will need to restart the server after making this change, by sending it a -HUP signal. Now, any request for a file ending in .map will be treated as an imagemap request.

To actually create an imagemap you need to do two things:

• Create a 'map' file which maps areas of the image onto documents
• Add the code to an HTML page to tell the browser which image to use and what mapfile.

The map file is a text file containing the information needed for the server to map points on the image onto documents to return (or URL's to redirect to). It can also contain statements to control the behaviour of the imagemap. The imagemap module uses map files in standard NCSA format, with optional extensions.

Areas and positions on the image can be mapped onto documents or URLs with the following commands. All co-ordinates start at the top-left of the image, position (0,0). These statements can be modified to make use of Apache imagemap extensions (such as to give a 'menu text'). This will be covered later.

• rect url x1,y1 x2,y2
  The rectangle (x1,y1) to (x2,y2).
• poly url x1,y1 x2,y2 ....
  The polygon formed by the points given.
• circle url x1,y1 x2,y2
  The circle with its center at (x1,y1) and point (x2,y2) on the circumference.
• point url x1,y1
  The closest point to the clicked position, if the click is not inside any circle, poly or rect.

The url part of each of these statements is the document to return if the point clicked was inside the respective area (or in the case of 'point', the closest). It can be either a absolute URL (starting http://, or a URL relative to the document root (starting /), or a relative URL (not starting with a /, and possibly including ../ components to go to parent directories).

If the URL is relative, it is taken relative to the directory containing the imagemap configuration file, not the original HTML document (if different). However this can be changed by the base statement, see below.

There are various ways to create the co-ordinates for the map file. One is to do it by hand, using positions obtained by (say) an image editing program. Alternatively there are various programs available which will let you mark the shapes on an image and then write out the correct statements, such as those listed in Yahoo's Imagemaps category.

The statements which can be used to control the behaviour of the imagemap are:

• base [ url | map | referer ]
  Use url as the base for any relative URLs within the map file. Alternatively, the word map can be used, which makes URLs relative to the directory containing the map file (this is the default). Alternatively, relative URLs can be made relative to the HTML document which included the imagemap image, with referer. This only works with browsers which support the Referer request header (most modern browsers support this).
• default [ url | error | nocontent | referer | menu ]
  This tells the server what to do if the point clicked was not inside any rect, poly or circle, and there were no point statements. It can either by a URL, or one of these values: error: return a 500 Server Error status; nocontent: return a 204 No Content status, which will cause most browsers to keep the current document; referer: return the document given by the Referer request header, which will be the HTML document which contained the imagemap; menu: return a text (HTML) version of the URLs in the map file. The default is nocontent.

The final part of creating an imagemap is to add suitable HTML code to an HTML document. Images are placed using the code <IMG SRC="...">. To place an imagemap, surround this tag with a <A HREF...> tag which refers to the map file, and include the attribute ISMAP in the <IMG SRC...>. For example:

  <A HREF="/docs/home.map"><IMG SRC="/graphics/image.gif" ISMAP></A>

where docs/home.map is the URL of the map file, relative to the server's document root. The ISMAP attribute in the <IMG SRC...> tag tells the browser that this is an imagemap. When the image is clicked, it sends a request for the given HREF URL, followed by the position of the image click, such as:

  GET /docs/home.map?20,35

if the image was clicked at position (20,35).

One of the big problems with imagemaps in past has been that they do not work with text-only browsers. The imagemap module is written to provide support for text-only browsers, which usually ignore the ISMAP attribute. The imagemap module recognises this and will return a text (HTML) document containing a menu of the possible selections from the map file. In addition, a menu document can be returned if the user of a graphical browser selects a point outside any of the defined areas, if the statement "default menu" is given in the map file.

The type of menu returned can be configured with the ImapMenu directive. This can be placed in a <Directory> or <Location> section, or in a .htaccess file. It takes a single argument which gives the type of menu to return:

• none
  Do not show a menu
• formatted
  Output a formatted document, with a suitable heading and with the map lines shown as <pre> text.
• semiformatted
  Format the map lines as <pre> text, and also show comment text on other lines (comments start with a hash character, #), but do not output a header.
• unformatted
  Do not format map lines as <pre> text, and output text from comment lines, but do not output a header.

The semiformatted and unformatted options let you add additional text and mark-up to the map document. The difference between these two is the with semiformatted, the map links are output as <pre> sections, which forces them onto separate lines. The unformatted option does not impose any restrictions, so it is possible to build up a map document with multiple links on a line, for instance.

The links in the menu document correspond to the URLs for each of the areas defined in the map file. The text of the link will be the URL itself. However this can be replaced with more meaningful text by giving this text as a argument before or after the co-ordinates. For example:

  rect /welcome.html 1,1 20,20 "Welcome to this site"

The imagemap module supports three directives: the first configures the type of menu to return (if any). This is the ImapMenu directive already covered. The other two directives provide alternate ways of setting the base and default actions (see the base and default map configuration statements, above). The corresponding directives are ImapBase and ImapDefault, and they take the same arguments.

The directives can be given in <Directory> and <Location> sections, and in .htaccess files.

Say you have an image which contains two areas you want to make active (see the example image, right): a circle, which should lead onto a contents page (contents.html) and a square which gives information about your company (about.html). The basic map file to do this would be:

  circle contents.html 25,25 0,25
  rect   about.html    50,0 100,50

This would be included in a HTML document like this:

  <A HREF="/maps/home.map"><IMG SRC="/img/logo.gif" ISMAP></A>

If the user clicks inside the circle or square area, they will get the associated document, relative to the mapfile location. The requested files would be: /maps/contents.html and /maps/about.html. This probably is not what is wanted. The URLs in the map file could be given as relative to the document root, for example:

  circle /contents.html 25,25 0,25
  rect   /about.html    50,0 100,50

Alternatively, the base statement could be used to set the base URL, as in:

  base /

  circle contents.html 25,25 0,25
  rect   about.html    50,0 100,50

Rather than putting the URL in the map file like this, it might be better to make all the URLs relative to the location of the HTML document containing the imagemap, with

  base referer

If the user clicks an area outside the circle and the square the will, by default, get a HTML menu of the URLs in the map file. Users of non-graphics browsers will also get this menu. To make it more readable, add some descriptions:

  base referer

  circle contents.html 25,25 0,25  "Contents"
  rect   about.html    50,0 100,50 "About our company"

which will produce the following map document:

        Contents

        About our company

(In this example the links do not go anywhere). The map document produced will just contain these two links. To make it more elaborate, you can either include your own mark-up text (on comment lines), or set the ImapMenu directive to the value formatted. To include your own mark-up, put it on lines which start with a # character:

  base referer

  # <h1>Menu Bar</h1>

  circle contents.html 25,25 0,25  "Contents"
  rect   about.html    50,0 100,50 "About our company"

  # Select one of the options above

which produces:

Menu Bar

        Contents

        About our company

Select one of the options above

This works because the default value for the ImapMenu option is semiformatted, which outputs comment text (after the # symbol) as part of the map document. For more elaborate formatted, you could include ImapMenu unformatted in your access.conf or .htaccess file, and use, say:

  base referer

  # <h1>Menu Bar</h1>

  # Select an option: 
  circle contents.html 25,25 0,25  "Contents"
  # or
  rect   about.html    50,0 100,50 "About our company"

which produces:

Select an option: Contents or About our company

Client-side imagemaps move the processing of the co-ordinate information to the browser. The HTML includes the information about the areas on the image and the documents they lead onto. This means the browsers can give positive feedback when the mouse is over an active area. This obviously only works in browsers which support it, but it is possible to use a single image as both a server-side and client-side imagemap. Here is an example image setup for both server- and client-side imagemap:

  <A HREF="/docs/home.map"><IMG SRC="/graphics/image.gif" ISMAP 
         USEMAP="#thismap"></A>

  <MAP NAME="thismap">
  <AREA SHAPE=CIRCLE COORDS="25,25,25" HREF="contents.html">
  <AREA SHAPE=RECT COORDS="50,0,100,50" HREF="about.html">
  </MAP>

Note that the circle here uses the centre point and a radius, rather than a point on the circumference. An example USEMAP imagemap is shown to the right. The format for client-side imagemaps is defined in RFC1980.