How to make clickable images on GN:

Judy Birmingham
Information Specialist
Stark County District Schools
Canton, Ohio, USA

j_birmingham@sparc3.sparcc.ohio.gov
----------------------------------
(This document assumes you have managed to get GN running first, and that your directory for your GN menus is called /GNROOT.)

1. FIRST GET THE IMAGEMAP PROGRAM AND PUT IT IN YOUR GN ROOT DATA DIRECTORY.

mkdir  /GNROOT/cgi
cd /GNROOT/cgi

Get the file ncsa-default.tar.Z (which contains  scripts like imagemap) via anonymous ftp:

ftp ftp.ncsa.uiuc.edu
cd /Web/httpd/Unix/ncsa_httpd/cgi
bin
get ncsa-default.tar.Z
quit

(This compressed archive should end up in your /GNROOT/cgi directory)

uncompress ncsa-default.tar.Z 
tar -xvf ncsa-default.tar

(This will make a subdirectory called cgi-bin under your /GNROOT/cgi directory).

2. TO MAKE A CLICKABLE IMAGE, YOU HAVE TO HAVE AN IMAGE FILE, RIGHT?

Place your favorite image file (*.gif) somewhere in your GN data tree.   For
illustration's sake, let's call the image file, ohio.gif, and it is in /GNROOT/images.

Make sure there is a menu item for your image, so that GN will know where find to it.  

Edit the /GNROOT/images/menu file, so that it includes something like the following lines:

Name=Map of Ohio
Path=I/images/ohio.gif

Now GN knows how to find your image file.  

Next we need to tell GN what to do when a user clicks on any given area of your image.

3. MAKE A .MAP FILE FOR YOUR CLICKABLE IMAGE.

I guess the best place for the .map file is in the same directory as the image file. Sooo...in /GNROOT/images, we would create a file called ohio.map. Let's just say you want to be able to click on or near Ohio's major cities like Cleveland or Columbus, and have GN serve a little text file about that city. Here's what your ohio.map file might look like.

default /0/Ohioinfo/ohio.txt
rect /0/Ohioinfo/columbus.txt 50,100 100,150
rect /0/Ohioinfo/cleveland.txt 100,25 150,75

This just means that if you don't click near Columbus or Cleveland, you will retrieve ohio.txt. If you click anywhere in rectangle around Cleveland or Columbus, you will retrieve the respective city's text file.

Note: If you use a partial url (because you are serving a local file), the path name starts with a slash and includes the document type. Full URLs, e.g. http://sparc2.sparcc.ohio.gov:70/0/Ohioinfo/ohio.txt, may also be used. Make sure that the file ends with a Newline character.

Other clickable areas can be defined as follows:

rect url X1,Y1 X2,Y2 (where X1,Y1 is upper-left and X2,Y2 are lower right.)

circle url x1,y1 x2,y2 (where x1,y1 is the center, and x2,y2 is on the circumference somewhere)

poly url x1,y1 x2,y2 x3,y3 .... xn,yn (where n<=100 and the x,y's are vertices of a polygon.)

Most people use a program called xy (which I guess is a UNIX program), to determine the coordinates of the clickable area. But I used "Graphic Converter" on the Mac, and "Graphics Workshop" on the PC, and they gave me the coordinates just fine. I got both of these shareware programs from the Merit Software Archives. (URL: gopher://gopher.merit.archive.edu/11/.software-archives)

4. MAKE THE DOCUMENTS THAT YOUR IMAGE MAP POINTS TO.

In the example, you would create text documents in the /GNROOT/Ohioinfo directory for ohio.txt, cleveland.txt, and columbus.txt. These are the documents that will be retrieved when a user clicks on your clickable image.

You will also need to make a menu file in the /GNROOT/Ohioinfo directory which makes a menu item for each of these documents.

5. NOW YOU NEED TO TELL THE IMAGEMAP PROGRAM WHICH MAP FILE TO USE WHEN A SPECIFIC IMAGE IS CLICKED UPON.

Make an imagemap.conf file in your GNROOT directory (/GNROOT). The standard location for imagemap.conf is in the gn-x.xx server directory, but I like to keep it in /GNROOT because when I upgrade from one version of GN to the next, I don't like to have to remember to move imagemap.conf to the new version's directory. This also eliminates the need to recompile imagemap.c and specify a new directory for CONF_FILE, each time you upgrade.

For each clickable image, you need a line as follows:

name location-of-map-file

In our example, /GNROOT/imagemap.conf would contain the line:

ohio /GNROOT/images/ohio.map

If you had other clickable images, similar lines would have to be added to
imagemap.conf for each image.

Note: The location needs to be specified as an absolute path, rather than relative. Also, make sure your file ends with a newline character (a blank line).

6. EDIT CONF_FILE IN IMAGEMAP.C AND COMPILE IT.

As you remember, you ftp'd this file from NCSA, and extracted it into the directory /GNROOT/cgi. When you untarred it, the imagemap program (imagemap.c) ended up in /GNROOT/cgi/cgi-bin/src.

cd /GNROOT/cgi/cgi-bin/src

Now edit imagemap.c so that CONF_FILE points to the location of your imagemap.conf file: namely, /GNROOT/imagemap.conf.

Now it's time to compile it. Imagemap is written in ansi-c, so you'd better have the gnu c-compiler on hand.

To compile, make sure you are in /GNROOT/cgi/cgi-bin/src, and type:

make

This will make (replace) binaries/executables for imagemap and several other programs in the /GNROOT/cgi/cgi-bin directory.

7. COPY IMAGEMAP.C TO THE CGI DIRECTORY AND RENAME IT TO IMAGEMAP.CGI

Now copy the imagemap executable to your /GNROOT/cgi directory, renaming it to imagemap.cgi, so that GN won't barf when asked to run imagemap. Here's how:

cd /GNROOT/cgi
cp /GNROOT/cgi/cgi-bin/imagemap ./imagemap.cgi

8. MAKE A MENU LINK TO THE IMAGEMAP.CGI PROGRAM

Make sure that GN knows where to find the imagemap.cgi program... by making a menu item for it in a menu file. Put this in the /GNROOT/cgi/menu file.

Name=imagemap executable
Path=CGI/cgi/imagemap.cgi
Attribute=Invisible

9. MAKE A LINK TO YOUR CLICKABLE IMAGE IN THE APPROPRIATE MENU OR HTML DOCU MENT.

In our example, you could put the clickable image of Ohio on your home page.

Here's how.
Add the following lines in /GNROOT/menu:

httpText=
<A HREF="/CGI/cgi/imagemap.cgi/ohio"><img src="/I/images/ohio.gif" ISMA
P></A>
endText=

Note: Make sure that the quotation marks in the HREF link are right. The doubl e quote comes before, not after, ISMAP.

10. mkcache -r YOUR MENUS.

To make this easy, I make invisible links in the /GNROOT/menu file to all my invisible GN subdirectories, like /GNROOT/images and /GNROOT/cgi. In this way, when I run mkcache -r, it caches all my GN menus, and I don't have to remember to manually mkcache hidden subdirectories.

Here is what those links look like in /GNROOT/menu:

Name=Image directory
Path=1/GNROOT/images
Attribute=invisible

Name=CGI stuff
Path=1/GNROOT/cgi
Attribute=invisible

Be sure you have a menu link in some menu to the directory that holds the documents retrieved when any location is clicked on your map. Make it invisible or visible, depending on your needs, just so long as it gets included when you run mkcache.

11. Now, hold your breath, run Mosaic or some other WWW client that supports ISMAP images, click away on your image, and see what happens.