W3C httpd Clickable Image Support

W3C httpd versions 2.14 and newer have a htimage program in the distribution, which is an /htbin program handling clicks on sensitive images. For versions 2.15 and newer it is a CGI program (uses the Common Gateway Interface to communicate with httpd). See demo.

In This Section...

htimage installation
Writing documents that contain clickable images
Image configuration file
Output of htimage

Installing htimage Binary

After compiling htimage you should move the executable binary to the same directory as your other server scripts are, and remember to set up an exec rule. For example if your scripts are in /usr/etc/cgi-bin, you could have an Exec rule like this:

        Exec  /htbin/*  /usr/etc/cgi-bin/*

Often htimage is one of the most often used scripts, and it would therefore be nice to refer to it with as short a name as possible, like /img, so you could have a Map rule just before the Exec:

        Map   /img/*    /htbin/htimage/*
        Exec  /htbin/*  /usr/etc/cgi-bin/*

Writing a Document With Clickable Images

To create a clickable image in your HTML document, you'll need to:

specify ISMAP in your inlined image call, and
make that image an anchor, with an HREF to the script handling the request (htimage) with image configuration file name appended to it.

Each clickable image has to be described to htimage via an image configuration file. These files are referred to by the extra path information in the URL causing the call to htimage:

        <A HREF="/htbin/htimage/image/config/file">
        <IMG SRC="Image.gif" ISMAP></A>

Image configuration file can be:

either a virtual path, that is translated through rule system,
or an absolute path in your filesystem.

htimage will look for both of these (afterall, it gets both PATH_INFO and PATH_TRANSLATED environment variables from httpd anyway).

You can even do some very smart mappings in the rule file to allow very short references to htimage and picture configuration files. Let's suppose all your image configuration files are in directory /usr/etc/images. Then you can use the following two rules in your server's configuration file (by default /etc/httpd.conf):

        Map   /img/*    /htbin/htimage/usr/etc/images/*
        Exec  /htbin/*  /usr/etc/cgi-bin/*

In this case you can refer to your image mapper very easily; if you have an image configuration file Dragons.conf in /usr/etc/images directory, all you need to say in the anchor is this:

        <A HREF="/img/Dragons.conf">
        <IMG SRC="Image.gif" ISMAP></A>

Image Configuration File

There are four keywords:

default URL: URL which is used if click is in none of the given shapes. This should always be set!
circle (x,y) r URL: Circle with center point (x,y) and radius r.
rectangle (x1,y1) (x2,y2) URL: Rectangle with (any) two opposite corners having coordinates (x1,y1) and (x2,y2).
polygon (x1,y1) (x2,y2) ... (xn,yn) URL: Polygon having adjacent vertices (xi,yi). If the path given is not closed (first and last coordinate pairs aren't the same) the first and last coordinate pairs will be connected by htimage. So first point is added also as the last one if necessary.

These can be abbreviated as def, circ, rect, poly.

Shapes are checked in the order they appear in config file, and the URL corresponding to the first match is returned. If none match, the default URL is returned.

URLs are

either full URLs (with access method, machine name and path), in which case server sends a redirection to client,
or a partial URL containing only pathname part of it (always starting with a slash), in which case server considers that as the original request, translates it through the rule system, access authorization and serves it normally (faster than sending redirection).

Output Produced by htimage

htimage prints a single Location: field to its stdout, or an error message with preceding Content-Type: text/html so in fact htimage behaves exactly as any other CGI/1.0 program (script), and is not in any way handled specially by the server. Therefore, you can rename htimage to whatever you prefer, like we called it /img in the above example.

Server understands this Location: field, and either directly sends that file to the client (non-full URL), or sends a redirection to client causing it to fetch the document, maybe even from another machine.

Note that URLs returned by htimage may well be other script requests - there is no reason for being limited to just regular documents.

httpd@w3.org, July 1995