# WASD Hypertext Services - Environment Overview

## 5 - Clickable Image Support

> 5.1 - Image Configuration File
> 5.2 - Examples

[next] [previous] [contents] [full-page]

Clickable image support is provided as an integral part of HTTPd functionality (i.e. it is does not require script execution), and so can be quite efficient. It will process both NCSA and CERN configuration formats (in the same file if necessary, although for clarity that should be avoided).

###
Digression ... How It Works

When the image specified in the anchor is clicked upon the browser sends a mapping configuration file URL, specified in the HTML anchor, along with the pixel coordinate of the click, as a query string, to the HTTPd server. The server interprets region specifications in the configuration file to determine which region corresponds to the coordinates in the query string. A matching specification's URL, or a default if none match, is then accessed by the server (if local), or sent back to, and then transparently reaccessed by the browser (redirected, if a different protocol or host).

###
Steps For Using a Clickable Image

1. create an image configuration file (see 5.1 - Image Configuration File), mapping pixel coordinates of regions within the image to URLs

2. specify an HTML anchor using an inline "<IMG...>" tag, the "HREF=" specifies the path to the image configuration file

3. specify "ISMAP" in the "<IMG...>" tag

   For example:

         <A HREF="ismap_demo.ismap">
         <IMG SRC="ismap_demo.gif" ISMAP></A>

###
5.1 - Image Configuration File

Image configuration is done using a plain-text file containing region keywords specifying image pixel coordinates and associated URLs. Clicking within these coordinates results in the corresponding URL being returned. Four keywords defining geometrically shaped series of coordinates are provided, along with a default keyword. These can be supplied in either of two formats. The NCSA format may be more commonly used.

1. NCSA

   - circle URL x1,y1 x2,y2
     URL to be returned when the click is within a circle of centre-point x1,y1 and a circumference specified by the edge-point x2,y2.

   - rectangle URL x1,y1 x2,y2
     URL to be returned when the click is within a rectangle having opposite corners x1,y1 and x2,y2.

   - point URL x,y
     With multiple points specified, the URL of the point closest to the click.

   - polygon URL x1,y1 x2,y2 x3,y3 [... xn,yn]
     URL to be returned when the click is within an arbitrary polygon having adjacent verticies specified by the series of coordinates (x1,y1) through to (xn,yn). If the polygon is not explcitly closed it is treated as if the first and last coordinates were connected.

   - default URL
     URL to be returned when the click is not within any of the specified coordinates, and there has been no point specified.

2. CERN

   - circle (x,y) r URL
     URL to be returned when the click is within a circle of radius r at centre-point (x,y).

   - rectangle (x1,y1)(x2,y2) URL
     URL to be returned when the click is within a rectangle having opposite corners (x1,y1) and (x2,y2).

   - point (x1,y1) URL
     With multiple points specified, the URL of the point closest to the click (strictly speaking, this is NCSA only).

   - polygon (x1,y1)(x2,y2)...(xn,yn) URL
     URL to be returned when the click is within an arbitrary polygon having adjacent verticies specified by the series of coordinates (x1,y1) through to (xn,yn). If the polygon is not explcitly closed it is treated as if the first and last coordinates were connected.

   - default URL
     URL to be returned when the click is not within any of the specified coordinates, and there has been no point specified.

For online examples of rule usage within configuration files see 5.2 - Examples below. Note that:

- There must be only one region keyword on each line.

- The region keywords are scanned from first towards last, the first one with coordinates encompassing the click having its URL returned. Region coordinates within other regions should be defined first.

- Either full URLs (protocol://host/path) or partial URLs (/path) may be specified against the keywords. As an extension to NCSA and CERN capability, this image mapper will also accept relative URLs (path, ../path, etc.).

- The image mapping utility may return textual error messages if the configuration keywords or parameters are incorrect.

- The keywords may be abbreviated to circ, rect, poly, poin and def.

- Blank lines are ignored.

- Commentary must be preceded by a "#" or "!" character.

> hint ...

> To establish the region keywords and coordinates required for the configuration file it may be necessary to use a program such as "XV" to display the image, then by using the mouse locate the required parts of the image, reading off and noting the coordinate pairs, and finally using these to compose the configuration file.

###
5.2 - Examples

See example in the HT_ROOT:[EXERCISE] directory.

[next] [previous] [contents] [full-page]