Copyright ©1996, Que Corporation. All rights reserved. No part of this book may be used or reproduced in any form or by any means, or stored in a database or retrieval system without prior written permission of the publisher except in the case of brief quotations embodied in critical articles and reviews. Making copies of any part of this book for any purpose other than your own personal use is a violation of United States copyright laws. For information, address Que Corporation, 201 West 103^rd Street, Indianapolis, IN 46290 or at support@mcp .com.

Notice: This material is excerpted from Special Edition Using CGI, ISBN: 0-7897-0740-3. The electronic version of this material has not been through the final proof reading stage that the book goes through before being published in printed form. Some errors may exist here that are corrected before the book is published. This material is provided "as is" without any warranty of any kind.

CHAPTER 9 - How to Handle Custom Image Maps

How an Image Map Functions

http://your.server.xxx/map_program?x,y

Concepts/Object
Types	Description
circle	This object creates a hyperlinked circle within your image map. In some versions of the image map program, the circle is defined with the center point and another point located on the circumference of the circle, and in others with the center point and radius.
default	This object is used to simply define the URL to which user are to be taken if they click an area that's not defined by any other line in the configuration file. No coordinates are defined with this object type.
poly	You can use the polygon object when the area you want to hyperlink in your image isn't a perfect circle or rectangle. The polygon is usually defined with up to 100 points, located at the vertices of the selected area you're trying to hyperlink. If, for example, you want to hyperlink a pentagon, you would configure the five points in your map file.
point	The point is defined with a single coordinate. Clicks closest to that point on your image map will be taken to the URL specified with this object type.
rect	The rect object is used to define the four sides of a rectangle. You can also use the poly object to do this, but the rectangle is so commonly used that it saves extra coordinate points you would need to label. The rect object is defined with two coordinate points-the upper left and bottom right corners of the rectangle.
Other Image Map Concepts
URL	The URL is the location of the Web page that you want the object type and coordinate points on the configuration line to take the user. URLs can be both local and full, although full URLs are more widely implemented. For example, if you want to access the document http://your.server.xxx/~mypage/, you would use either http://your.server.xxx/~mypage/ or /~mypage/. Keep in mind that when referencing pages not located on your server, you must use a full URL.
Coordinate points	Coordinate points are used to define the locations of the objects within the image of which you're making an image map. The coordinates should be in the format x,y, in terms of pixels across, pixels down. The upper left corner of your image map would be coordinate 0,0. Coordinate points are sent to the image map program or Web server when the user clicks the image map.
Client	This is the browser with which the user is visiting your site. When I use the term client-side image mapping, I'm referring to the fact that the client, a Web browser, handles the configuration files embedded in the HTML file and determines where the user will go based on the click.
Server	The server is the HTTP daemon that's running on your computer. The server sends out files when they're requested by the client and does any necessary configuration and/or parsing of the contents before they're sent out.

Web Server Image Map Configurations

• (Image Mapping Tutorial). This image-mapping tutorial, from NCSA (makers of the original Mosaic and the NCSA HTTPd Web server), also contains the imagemap.c program included in the source of its distribution. The source can be downloaded for compilation on your server.
• Mapserve. MapServe allows Macintosh Web servers to send out image maps to clients.
• Yahoo. Yahoo also hosts an impressive list of other sites that contain information about using image map programs. Many of the sites listed in Yahoo offer shareware or freeware image map programs and simple instructions on how to set up and configure these programs to create your own image maps and map files.

NCSA Image Map Configurations

Versions of the NCSA HTTPd server before version 1.5 uses a CGI image map program written in C. Version 1.5 of NCSA's HTTPd server has a built-in image map function, so you no longer have to launch an external CGI script in order to handle image map requests.

See  "Configuring CGI with the NCSA Server,"  for more information on getting your NCSA server to recognize CGI scripts. 

The creation of the image map configuration file is pretty much the same for both methods; the only difference lies in the URL with which you reference your map configuration file. The basic setup of a configured map file is

object URL coordinates

All the preceding elements in a common NCSA configuration map file are described in the beginning of this chapter under "How an Image Map Functions." The NCSA image map configuration file can include comment lines, which are designated with a # as the first character on that line. These are often useful if you want to remember what sections of your map configuration file are set to the image map. All other lines, which aren't blank, should use the preceding format with the object first-be it a rect, poly, circle, or point. The image map configuration file shown in listing 9.1 corresponds to the image in figure 9.1.

Some earlier versions of the NCSA HTPPd Web server required that all image map files be relayed through one central registry file. This file usually had limited access, which only the server administrator could access. If this is the case, you should upgrade to the latest version of the image map program, which removes this restriction.

Fig. 9.1

This simple image map will be used as the template for all map files created in the next few sections of this chapter.

Listing 9.1 Basic Map Configuration File for NCSA Server
# Basic Map Configuration File For NCSA Server
# Corresponds to Basic Image
# Written on: 1/12/95        Last Modified on: 1/12/95
# Map File Created by: Matt Wright

# Default URL if user clicks outside of hyperlinked areas

default http://www.server.xxx/

# Circle URL.  URL used if user clicks in the circle.

circle http://www.server.xxx/circle.html 35,35 67,35

# Rectangle URL.  URL used if user clicks in the rectangle.

rect http://www.server.xxx/rect.html 71,3 199,65

# Point URL.  URL used if user clicks on the dot.

point http://www.server.xxx/point.html 326,30

# Triangle URL.  URL used if user clicks in the triangle.

poly http://www.server.xxx/poly.html 225,63 296,63 261,4

To call your image map inside your HTML document, you must set the ISMAP attribute on your <img> tag as well as call the image map program and the path to your basic.map file. This is where the versions of NCSA HTTPd begin to differ. If you have a version before 1.5 or are using the image map.c program, you'll need to call your image map configuration file in your document, like this:

<a href="http://www.server.xxx/cgi-bin/imagemap/url/to/basic.map">
<img src="http://www.server.xxx/url/to/basic.gif" ISMAP>
</a>

Here, I've included the full URLs to make the example clear. After you reference the image map program with the URL, you must then append the URL of the location of your map file on your server. That's what the /url/to/basic.map must be. The ISMAP attribute to the <img> tag alerts browsers that they'll need to send the coordinates where user clicked appended to the URL so that the image map program can work effectively.

Version 1.5 of the NCSA HTTPd has built-in image mapping capabilities. These can be turned on by adding a new type, just as you would with CGI extensions. The Webmaster or system administrator has to do this in the configuration files of the server. It can be added by simply including the line in the server's srm.conf configuration file:

AddType text/x-imagemap .map

The server must also be started with IMAGEMAP_SUPPORT defined, which is the default.

If you have access to NCSA version 1.5 or later, you should use the built-in image map handling, rather than the external CGI program, because the relay of the URL to the user will be much quicker than using a CGI image map program.

Apache Image Map Configurations

Similar to NCSA version 1.5, the Apache Server 1.0 has image map capabilities built into the server, so you don't need an outside CGI script to do the work. When adding a new MIME type to support image maps such as you did with the AddType for NCSA, the Apache server requires you to use the following MIME type:

AddType application/x-httpd-imap map

This enables all files with a .MAP extension to be parsed as though they're image map configuration files. This saves server response time and the stress put on the server to execute external CGI programs. Similar to the NCSA server is the order in which the lines call the objects and coordinates in the map configuration file:

object URL coordinates

The format of an Apache map file is slightly different from that of NCSA's. One of the major differences is in the use of a base_uri command. The options for the base_uri command are described in the following table.

Option	Description
map	This provides the default behavior of most older image map programs, where all URL references are relative to the URL of the map configuration file.
referer	This attribute to the base_uri command treats
	all URLs relative to the HTTP_REFERER
	environment variable. This is very useful if
	you have a base directory at
	http://www.server.xxx/, and this is the page
	at which your image map will appear. You can
	set base_uri to referer and then make all
	other URL references relative to that URL. So
	if you're referencing, as in
		http://www.server.xxx/circle.html
		http://www.server.xxx/rect.html
		http://www.server.xxx/poly.html
	set the base_uri to referer and then just use
	relative URLs to the referer, such as
	circle.html, rect.html, and poly.html. If you
	use the referer option, all URLs will be
	relative to the page with the image map.
Actual URL	You can also set your base_uri to an actual URL.
	For instance, taking the example I described
	earlier for the referer attribute, you could use a
	definition such as base_uri
	http://www.server.xxx/.
	All your URL references inside your map
	configuration file can be relative to this
	base_uri. This saves typing time and makes the URL
	references more concise.

Listing 9.2 is the configuration file for the same image as used in the NCSA example. This time, however, the map file has been tailored for the Apache server.

Listing 9.2 Basic Map Configuration File for Apache Server
# Basic Map Configuration File For Apache Server
# Corresponds to Basic Image
# Written on: 1/12/95        Last Modified on: 1/24/95
# Map File Created by: Matt Wright

# Default URL if user clicks outside of hyperlinked areas

default http://www.server.xxx/

# Base URL.  All URLs will be relative to this URL.

base_url http://www.server.xxx/

# Circle URL.  URL used if user clicks in the circle.

circle circle.html 35,35 67,35

# Rectangle URL.  URL used if user clicks in the rectangle.

rect rect.html 71,3 199,65

# Point URL.  URL used if user clicks on the dot.

point point.html 326,30

# Triangle URL.  URL used if user clicks in the triangle.

poly poly.html 225,63 296,63 261,4

Referencing your map file and your image map through your HTML document can be accomplished in much the same way as you referenced the two in the NCSA version 1.5 configuration example. Following is the example repeated:

<a href="http://www.server.xxx/path/to/basic.map">
<img src="http://www.server.xxx/path/to/basic.gif" ISMAP>
</a>

CERN and W3C Image Map Configurations

The CERN and W3C HTTPd servers come with the source to a CGI program called htimage, which allows you to link your images up with a map file, much like the other servers. After your htimage script is compiled, you need to add the Exec rule to the server's configuration file. Most likely, if you aren't a system administrator, you won't be able to do this, but it has probably already been configured. For more information on adding the Exec rule to your server, take a look at the documentation provided online at this site.

See  "Configuring CGI with the CERN HTTPd Server,"  for more information on how to configure CGI scripts with the CERN HTTPd Web server. 

The major difference between the CERN and W3C servers and NCSA and Apache is that the CERN/W3C htimage program doesn't recognize the point object in your map configuration file. The map configuration file also has a slightly different format, which takes the form of

object coordinates URL

Listing 9.3 is the basic.map, rewritten to follow the htimage format, which is the program used by CERN and W3C.

Listing 9.3 Basic Map Configuration File for the CERN and W3C Servers
# Basic Map Configuration File For CERN and W3C Servers
# Corresponds to Basic Image
# Written on: 1/12/95         Last Modified on: 1/24/95
# Map File Created by: Matt Wright

# Default URL if user clicks outside of hyperlinked areas

def http://www.server.xxx/

# Circle URL.  URL used if user clicks in the circle.  The
# htimage program must have the Center and Radius of the 
# circle defined.

circle (35,35) (32) http://www.server.xxx/circle.html

# Rectangle URL.  URL used if user clicks in the rectangle.

rect (71,3) (199,65) http://www.server.xxx/rect.html

# Point URL.  URL used if user clicks on the dot.  htimage
# is not point compatible with the point method, so we will
# represent it with a circle with a radius of 2, which will
# create a small point.

circ (326,30) 2 http://www.server.xxx/point.html

# Triangle URL.  URL used if user clicks in the triangle.

poly (225,63) (296,63) (261,4) http://www.server.xxx/poly.html

As you can see in the preceding example, there are a few differences between the NCSA and Cern/W3C servers. For one, you can abbreviate the circle and default configuration objects with circ and def, rather than have to spell them out (circle and default). The htimage programs also require that you configure your circle coordinates in the form of (x,y) for the center and then the radius of the circle. Because the htimage program doesn't have the point capability built in, I simply defined a circle with a radius of 2 to make it seem as though it's a point. The other difference you may notice in the preceding configuration file is that the URL is placed after the coordinates on each line, as opposed to before the coordinates as is done with other programs. The coordinates in this map configuration file must also be placed in parentheses, with the radius of a circle following the center coordinates but not inside of the parentheses.

To call your image map from your Web page, you can use almost the same syntax as was used in the previous examples:

<a href="http://www.server.xxx/url/to/htimage/url/to/basic.map">
<img src="http://www.server.xxx/url/to/basic.gif" ISMAP>
</a>

Netscape Image Map Configurations

Netscape servers come with the image map program built in, so you don't need an external CGI script to do the parsing of the coordinate points. The first thing you need to do is create your map file for the image map that you want to use.

The NCSA and Netscape servers have the same configuration file; you can refer to the NCSA map file in listing 9.1 for more background information. The difference between the Netscape and NCSA servers is that you don't have to call on an external CGI program before calling the map file. Instead, simply place a reference like

<a href="http://www.server.xxx/url/to/basic.map">
<img src="http://www.server.xxx/url/to/basic.gif" ISMAP>
</a>

into your HTML document. Your map file should end with the .MAP extension for the Netscape server to recognize it as an image map configuration file.

See  "Configuring Netscape for CGI,"  for more information on setting up the Netscape Web server for CGI programs. 

The Netscape server has a 100-point limit when defining polygons; however, by the time you start nearing this limit, your configuration line will also get too large for Netscape servers to handle. If this happens, simply spread your points out more evenly throughout the polygon.

Apple Internet Server Image Maps

You can download several image-map programs for the Apple Internet server. One of these is Mac-Imagemap, which can be downloaded from

• URL

This program handles map files in the same configuration setup as NCSA map files, so refer to listing 9.1 if you have problems setting up your map files. Full details and installation instructions for Mac-Imagemap can be found at the preceding URL.

Client-Side Image Maps

Listing 9.4 Example of a Client-Side Image Map Configuration
<MAP NAME="basic_map">

<!-- The Circle Shape. Users will be taken to circle.html if they
click inside of the circle. Like the htimage program, the circle
coordinates should be defined with the center and the radius. All
three numbers are comma separated. The Alt tag will be seen by
non-graphical browsers. -->

<AREA SHAPE=CIRCLE COORDS="35,35,32" HREF="circle.html" ALT="Circle">

<!-- The Rectangle Shape. Users will be taken to rect.html if they
click inside of the rectangle. The coordinates for the rectangle
should be the upper left (1) and lower right corners (2) of the
rectangle separated by commas, ie. COORDS="x1y1x2y2"-->

<AREA SHAPE=RECT COORDS="71,3,199,65" HREF="rect.html" ALT="Rectangle">

<!-- The Triangle is represented with a polygon shape. Coordinates
from the triangle vertices are comma separated. You can have as
many vertices as you wish, except for the fact that HTML limits an
attribute's value to 1024 characters in size. -->

<AREA SHAPE=POLY COORDS="225,63,296,63,261,4" HREF="poly.html" ALT="Triangle">

<!-- The Point attribute is not supported by the current Client-side
Image Maps specification, but to get around that we will use a
circle reference with a radius of 2, to create a point. -->

<AREA SHAPE=CIRCLE COORDS="326,30,2" HREF="point.html" ALT="Dot">
</MAP>

Attribute	Description
SHAPE	This attribute can be defined as CIRCLE, RECT, or POLY, depending on what shape you're defining. If this attribute isn't present, SHAPE=RECT is assumed. The POINT value to the SHAPE attribute isn't supported, but you can get around that by including a circle with a radius of 1.
COORDS	This is the attribute that defines the coordinates of SHAPE. For RECT and POLY shapes, the coordinates are simply shown as x1,y1,x2,y2,...,xn,yn, whereas in a circle you define the center x,y coordinate pair and the radius of the circle. Coordinate values should be represented in pixels, like all other image map specifications.
HREF	This is the URL to the Web page you want this element to link to. It can be expressed as a full URL, or as a URI relative to the current page.
ALT	This attribute contains the alternative text you want to be displayed if the user is using a non-graphical browser or has images turned off.

<img src="basic.gif" USEMAP="#basic_map">

<a href="http://www.server.xxx/url/to/imagemap/url/to/basic.map">
<img src="basic.gif" USEMAP="#basic_map" ISMAP>
</a>

<a href="no_map.html">
<img src="basic.gif" USEMAP="#basic_map">
</a>

<img src="basic.gif" USEMAP="maps.html#basic_map">

Image Map Tools

Fig. 9.2

This is WebMap for the Macintosh, after you open the image file and highlighted a selected region.

Most browsers don't support PICT images; therefore, these images should be converted to GIF or JPEG format before you incorporate them into your HTML pages.

After you completely trace all your locations in the image map and fill in the URL and comments box for each one, you can save the file. When the save dialog box pops up, it looks similar to figure 9.3. WebMap supports NCSA and CERN image map formats, so you can choose which one you want to save to. Choose the name for your map file and then click the Save button.

Fig. 9.3

WebMap offers two choices when saving files: CERN or NCSA format.

Windows

The following sections provide step-by-step instructions for two popular Windows NT image map programs: Map This version 1.20 and Web Hotspots version 2.0 by 1automata. These programs are also Windows 95 compatible.

Map This Version 1.20

Map This runs under all Windows platforms, from 3.1 (running Win32s) to Windows 95, and including Windows NT. A very fast image mapping program for the Windows platform, Map This is probably one of the best on the Net. One of the top features of this program is that it's freeware, so you don't need to worry about registration fees.

Map This version 2.0 is included on the CD-ROM located in the back of this book. If you're using Windows 3.1 to run Map This, you also need to install version 1.3 of Win32s, also located on the CD-ROM.

After installing Map This, open the program, pull down the File menu, and choose New. The dialog box that appears tells you that you need to select an image to correspond to your map file if you want to continue (see fig. 9.4). Click Let's Go Find One! if you want to continue.

Fig. 9.4

Click the Let's Go Find One! button to continue creating your image map file.

After opening your image, choose the basic.gif file from figure 9.1, and your screen will look something like figure 9.5.

Fig. 9.5

Basic.gif opens inside Map This.

Notice the tools located above your image in figure 9.5. The leftmost tool allows you to create a rectangular area. Moving across the toolbar, the next one is the circle tool, followed by the polygon tool, which allows you to trace around an object of many sides. Using this toolbar and the cursor, click the tool you want and then select the vertices of rectangles and polygons, or outline the circle until all the portions of the image you want to be included in your map file are highlighted. After they're all outlined, your image should look similar to figure 9.6.

Fig. 9.6

This is what your image map file should look like after you highlight the areas inside of it.

Rectangle tool

Circle tool

Polygon tool

Now that you've selected all the areas on your image map, pull down the Mapping menu and choose Area List. The Area List dialog box shows all the areas that you've highlighted in your image (see fig. 9.7). With this dialog box, you can delete and edit any of the areas that you've specified. All areas you want to keep must be edited and their proper URLs filled in before you can create a map file from the image.

Fig. 9.7

The Area List dialog box lists all selected areas in the image map and allows you to edit and delete them.

To edit a selected portion of the image, click the choice in your Area List and click the Edit button. This brings up a dialog box similar to figure 9.8.

Fig. 9.8

The Area dialog box shows you the type of image and allows you to fill in the URL and comments.

The Area dialog box shows the type of area you're working with, its position in the image map, and the dimensions of the image. You need to fill in the URL text box and, if you want, can also add a comment about the area. You can now choose to Delete the area, or click OK to continue. Continue to edit all portions of the image map that you selected. After you finish editing, choose Save from the File menu and the dialog box in figure 9.9 appears.

Fig. 9.9

After filling out the information in the Info About This Mapfile dialog box, Map This allows you to save your image map file.

Fill in the Title, Author, Default URL, and Description text boxes accordingly and choose your file format. Map This now supports NCSA, CERN, and Client-Side ImageMapping (CSIM) standards. Click OK and then choose a file name to which you can save the map file.

Web Hotspots Version 2.0

Web Hotspots provides an easy-to-use interface with which you can create server-side and client-side image map configuration files. Web Hotspots is shareware and can be found at http://www.hooked.net/users/1auto/hotspots.html, or on the CD-ROM accompanying this book.

To begin a new image map file, install the Web Hotspots program and then start the program. After you start it, choose New from the File menu. A dialog box appears, asking you to specify the file name of the image from which you want to create the image map configuration file. Select one of the images from your hard drive and click OK to open the image inside the Web Hotspots program (see fig. 9.10).

Fig. 9.10

The toolbar in Web Hotspots allows you to create circles, rectangles, polygons, and more.

Now go through the steps to create a basic image map configuration file as if your image was basic.gif (refer to fig. 9.1). The first object you need to define is the circle. Select the circle tool from the menu bar at the left. Starting from the upper right of the circle, drag to the lower left to select a circular area that you want to highlight with a URL. Notice that a temporary URL has popped into the URL box at the bottom of your Hotspots screen. You must edit this URL to point to the correct URL for the circle: http://www.server.xxx/circle.html. Figure 9.11 shows the image map after highlighting the circle and changing the URL.

Fig. 9.11

After you highlight a portion of your image map, fill in the URL at the bottom of the screen.

You can continue to designate hot spots on your image with the different tools at the left. You'll need to use the polygon tool to hyperlink the triangle and the rectangle tool to hyperlink the rectangle. Because there's no point specification with this program, you must use the circle shape to create a very small circle around the dot in the image map.

After all the hyperlinks and portions of the image map are defined, you need to open the File menu and select Page New.

You're now presented with the Image Map Variety dialog box, which asks you to choose whether you want to create one of many different kinds of image map configuration files (see fig. 9.12). The options for image map configuration files are Client-Side, External Client-Side, Server-Side, Client-Side with Server-Side Support, and External Client-Side with Server-Side Support. The following table describes what each choice from the Image Map Variety dialog box does.

Fig. 9.12

You're allowed to choose from five variations of map files to fit the needs of your server and client software specification.

Option	Description
Client-Side	When you choose this type of map file, you're presented with another dialog box, which asks the file name to which you want to save the map. Hotspots then creates this file, with the image and the map file referenced in one Web page.
External	This map file is very similar to that of
Client-Side	the Client-Side option, except when you
	choose this type, your image is called from
	one document and the map source file
	resides in another HTML document.
Server-Side	After you select this option, a file-save dialog box appears, asking what you want to call your map file. It will default to a .MAP extension with NCSA formatting. You can also choose to have it saved in CERN formatting, if you use the CERN or W3C servers. The use of a Server-Side image map configuration file requires you to have an image map program on your server or a server that can handle image maps. Refer to the configuration of each server, which was discussed earlier in the section "Web Server Image Map Configurations."
Client-Side with	This includes an HTML file that references
Server-Side Support	both a client-side implementation of image
	maps and a server-side for those browsers
	that don't currently support client-side
	image mapping.
External Client-Side	This is similar to Client-Side with Server-
with Server-Side	Side Support, except the configuration tags
Support	for the client-side image mapping are kept
	in another HTML document and are referenced
	when they're called on. This includes
	backward compatibility with versions of Web
	browsers that don't support client-side
	image mapping.

After you pick the type of image map you want to create, a dialog box, as shown in figure 9.13, appears, to let you choose the path to the file in which you want to save your map.

Fig. 9.13

This dialog box appears when you try to save a map file.

Client-side image maps are saved in files called .htm, while server-side implementations are saved in files with a .map extension. After you save the image map file, a Host Specification dialog box appears (see fig. 9.14). After you enter the Page Title and Image URL, your map file is saved.

Fig. 9.14

The final configuration needed for your map file is the host specification.

UNIX

Many standard image-viewing utilities come with most UNIX operating systems that allow you to find coordinates in the image and plot them into a standard map file. Currently, no UNIX-based image map programs available on the Internet offer a friendly interface and provide the tools necessary to make image map files. Instead, you must load your favorite UNIX image editor and click various spots in the image to locate the position of the image you want to highlight inside the larger image. After you find these coordinates, you need to manually create a map file, as demonstrated earlier in this chapter. Choose the server you use, and then tailor your map file to resemble the format. Understandably, UNIX isn't a popular platform for creating image map files.

Generating Images in Real Time

% gunzip giflib-2.2.tar.gz
% tar xvf giflib-2.2.tar

You can download FLY from its Web site at this site , where the current versions are always located. This site also contains complete instructions on how to install and use FLY.

Using FLY

FLY is usually invoked with the path to a file containing the FLY commands, and then the path to which you want the image to be output. There are also options that allow you to specify whether you want to read input from the command line and send the image to STDOUT.

FLY allows for the easy creation of rectangles, polygons, circles, lines, and many other objects. You can choose what color to fill your images, or leave them without color. FLY also has the option of copying and pasting from other images. This is useful when it comes to making counter programs, because you can have a set of premade number files and then simply copy and paste the correct ones into the new image and send that back to the client. More information on using FLY can be found on the Web page.