ch12.htm

CGI programming is the hottest stuff to look out for in this book

<BLOCKQUOTE>
<TT><FONT FACE="Courier">&lt;A HREF=http://www.anyfirm.com/cgi-bin/imagemap.cgi&gt;&lt;IMG
SRC=http://&Acirc;www.anyfirm.com/pics/mercator.gif ISMAP&gt;&lt;/A&gt;</FONT></TT>
</BLOCKQUOTE>
<P>
If I were to then click on Toronto, the URL the browser would
try to invoke would be
<BLOCKQUOTE>
<TT><FONT FACE="Courier">http://www.anyfirm.com/cgi-bin/imagemap.cgi?200,90</FONT></TT>
</BLOCKQUOTE>
<H2><A NAME="FlatlandRevisitedAnIntroductiontoth"><FONT SIZE=5 COLOR=#FF0000>Flatland
Revisited-An Introduction to the Standard Imagemap System</FONT></A>
</H2>
<P>
To begin, I'll start by telling you that you won't be seeing any
imagemap-handling source code any time soon. I hate to say this
as it gives me great joy to both read and write the stuff. Conventional
imagemap source code has become so standardized that there's no
point in my going into it immediately. However, I will write my
own nonconventional imagemap handler later on in this chapter
to show you that you <I>don't</I> have to rely on the standard
software if it doesn't fit your purposes. Instead, right now I'll
go into the theory of how imagemaps work.
<P>
In the 19th century, a Shakespearean scholar named Edwin Abbott
wrote a book called <I>Flatland</I>. It was a satirical description
of the lives of two-dimensional creatures inhabiting a plane.
The social status of a flatlander was almost entirely based on
their geometry. I'm reminded of flatland when it comes to standard
imagemaps, as they are a description of what to do when a particular
two-dimensional geometry is encountered.
<H3><A NAME="ImagemapcTheStandardImagemapHandler">Imagemap.c-The
Standard Imagemap Handler</A></H3>
<P>
The National Center for Supercomputing Applications (ncSA) released
the first HTTP server that really caught on as well as the first
Web browser, called Mosaic. It has also supported quite a lot
of other Web-related projects, including the creation and distribution
of imagemap.c, the standard imagemap handler. This C source code
comes with the ncSA HTTPd distribution and will be automatically
compiled with the HTTPd and installed in the /cgi-bin/ directory
of the Web server. However, if this isn't the case with your installation
or if you wish to get a newer version of the code, you may find
it through the following URL:
<BLOCKQUOTE>
<TT><FONT FACE="Courier"><A HREF="http://hoohoo.ncsa.uiuc.edu/docs/tutorials/imagemapping.html">http://hoohoo.ncsa.uiuc.edu/docs/tutorials/imagemapping.html</A></FONT></TT>
</BLOCKQUOTE>
<P>
In fact, this link will tell you just about everything you need
to know about the standard imagemap system.
<P>
<CENTER><TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR><TD><B>Note</B></TD></TR>
<TR><TD>
<BLOCKQUOTE>
The ncSA and Apache World Wide Web servers have become the &quot;modern standard&quot; in the field. In the beginning, though, CERN was King. This is quite understandable-Tim Berners-Lee of CERN (Conseil Europeen pour la Recherche Nucleaire) was the 
driving force behind HTML and HTTP.</BLOCKQUOTE>
<BLOCKQUOTE>
CERN proposed its own imagemap-handling system that was quite popular for a while. In case you ever run across it, you can find a discussion at</BLOCKQUOTE>
<BLOCKQUOTE>
<TT><FONT FACE="Courier"><A HREF="http://www.w3.org/pub/WWW/Daemon/User/CGI/HTImageDoc.html">http://www.w3.org/pub/WWW/Daemon/User/CGI/HTImageDoc.html</A></FONT></TT>
</BLOCKQUOTE>
<BLOCKQUOTE>
The main difference between the CERN and ncSA imagemap-handling systems is that the .map files aren't quite the same. However, there is a 1:1 correspondence between the two map file types. Conceptually, the two schema are virtually identical.</BLOCKQUOTE>

</TD></TR>
</TABLE></CENTER>
<P>
<P>
I'll start here where I left off in the previous section. Through
HTML, an x,y coordinate pair corresponding to a mouse-click on
an image can be generated and sent to a CGI program. This program
is then responsible for obtaining this information from the <TT><FONT FACE="Courier">QUERY_STRING</FONT></TT>
string environment variable. So, the question now becomes what
to do with this coordinate pair. The ncSA standard imagemap system
offers one possible solution.
<P>
Consider the following URL:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">&lt;A HREF=http://www.anyfirm.com/cgi-bin/imagemap.cgi/pathinfo/mapfile.map&gt;&lt;IMG
&Acirc;SRC=imageURL ISMAP&gt;&lt;/A&gt;</FONT></TT>
</BLOCKQUOTE>
<P>
This HTML is almost identical to the HTML in the previous section,
except that now imagemap.cgi has more information following it.
This information tells imagemap.cgi to look into a .map file;
.map files contain a geometrical description of the image in question
and tell imagemap.cgi what to do when it finds a mouse-click lying
within a given shape. The next section is an in-depth examination
of .map files.
<P>
<CENTER><TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR><TD><B>Caution</B></TD></TR>
<TR><TD>
<BLOCKQUOTE>
Note that this line will vary depending on whether or not your imagemap executable is named imagemap.cgi or simply imagemap, whether or not it is located within the /cgi-bin/ directory, and what sort of <TT><FONT FACE="Courier">pathinfo</FONT></TT> you 
supply it with. If the imagemap executable file is not kept in the server's specified /cgi-bin/ directory, then it must be named imagemap.cgi. Within the /cgi-bin/ directory, it may or may not possess this extension.
</BLOCKQUOTE>

</TD></TR>
</TABLE></CENTER>
<P>
<P>
<TT><FONT FACE="Courier">pathinfo</FONT></TT> is a strange fixture
of CGI programming at best, but it becomes even stranger in the
context of the standard imagemap handler. A path string can be
appended after any URL that terminates in a file. The CGI programmer
can find this string in the <TT><FONT FACE="Courier">PATH_INFO</FONT></TT>
environment variable. In the case of the standard imagemap handler,
one of two things can be done with this string:
<BLOCKQUOTE>
It can be used to directly reference the .map file associated
with the image that has been ISMAPed.
</BLOCKQUOTE>
<BLOCKQUOTE>
It can be used as an alias by the imagemap program to reference
the imagemap.conf file.
</BLOCKQUOTE>
<P>
The HTML code given earlier shows the usage when <TT><FONT FACE="Courier">PATH_INFO</FONT></TT>
is used to directly reference a .map file. In this context, imagemap.cgi
will try to access the .map file that could be referenced by the
URL:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">http://www.anyfirm.com/pathinfo/mapfile.map</FONT></TT>
</BLOCKQUOTE>
<P>
Note that <TT><FONT FACE="Courier">pathinfo</FONT></TT> could
have many different directory levels included within.
<P>
<CENTER><TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR><TD><B>Note</B></TD></TR>
<TR><TD>
<BLOCKQUOTE>
Some servers are configured to recognize .map files as being specifically associated with imagemaps. If that is the case, the server will prevent you from accessing a .map file directly through its URL as I pointed out earlier.</BLOCKQUOTE>

</TD></TR>
</TABLE></CENTER>
<P>
<P>
If <TT><FONT FACE="Courier">pathinfo</FONT></TT> is used as an
alias, imagemap.cgi will look in its own directory for a file
called imagemap.conf. If imagemap.conf is found, imagemap.cgi
will parse it for references that match the <TT><FONT FACE="Courier">pathinfo</FONT></TT>.
Following these references, there will be map file names, which
are then used. I have grabbed the following from <TT><FONT FACE="Courier"><A HREF="http://www.anadas.com/">http://www.anadas.com/</A></FONT></TT>
at my UNIX shell to show how it would look directly:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">% ls -l *.map *.conf<BR>
-rw-r-----&nbsp;&nbsp;1 anadas&nbsp;&nbsp;www&nbsp;&nbsp;590 Apr
16 02:55 button.map<BR>
-rw-r-----&nbsp;&nbsp;1 anadas&nbsp;&nbsp;www&nbsp;&nbsp;&nbsp;38
Mar 23 17:42 imagemap.conf<BR>
-rw-r-----&nbsp;&nbsp;1 anadas&nbsp;&nbsp;www&nbsp;&nbsp;507 Apr
17 08:53 swatch.map<BR>
% cat imagemap.conf<BR>
swatch: swatch.map<BR>
button: button.map<BR>
</FONT></TT>
</BLOCKQUOTE>
<P>
<CENTER><TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR><TD><B>Tip</B></TD></TR>
<TR><TD>
<BLOCKQUOTE>
To do much in the way of CGI programming, a good working knowledge of UNIX is almost essential. <TT><FONT FACE="Courier">ls</FONT></TT> will list the contents of a directory. <TT><FONT FACE="Courier">cat</FONT></TT> will concatenate the contents of a file. 
These commands are roughly equivalent to <TT><FONT FACE="Courier">dir</FONT></TT> and <TT><FONT FACE="Courier">type</FONT></TT> in DOS.
</BLOCKQUOTE>

</TD></TR>
</TABLE></CENTER>
<P>
<P>
Finally, an example of how <TT><FONT FACE="Courier">pathinfo</FONT></TT>
aliases and the imagemap.conf files are put into practice:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">&lt;A HREF=&quot;exe/imagemap.cgi/swatch&quot;&gt;&lt;IMG
SRC=&quot;pics/swatch.jpg&quot; ISMAP&gt;&lt;/A&gt;</FONT></TT>
</BLOCKQUOTE>
<H3><A NAME="mapFilesDescribingShapestheImagema">.map Files-Describing
Shapes the Imagemap Way</A></H3>
<P>
Since the time of the Babylonians, people have been obsessed with
geometry. Farmers, architects, and mathematicians-even lowly computer
programmers-have all found it useful to be able to precisely describe
shapes. We've come up with quite a few systems of doing so and
a bunch of standardized shapes to work with. Of this vast storehouse
of knowledge, the standard imagemap system recognizes only four
methods: rectangles, circles, polygons, and points.
<P>
The basic idea behind the standard imagemap system is that whenever
a mouse-click is registered corresponding with one of these shapes
in an imagemap, a URL is invoked. This is accomplished by having
the imagemap handler issue a Location directive via the Web server.
A .map file is the means through which shapes are defined and
the standard imagemap program knows how to tie which URL to what
shape. The imagemap program gets the mouse-click coordinates and
determines which shape contains the click.
<P>
<CENTER><TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR><TD><B>Note</B></TD></TR>
<TR><TD>
<BLOCKQUOTE>
A Web server can issue three general sorts of header statements and be understood by a Web browser:</BLOCKQUOTE>
<UL>
<LI>A Content Type description
<LI>A Server Error description
<LI>A URL Location
</UL>
<BLOCKQUOTE>
The first is issued when all is well. As you have probably guessed, the second occurs when something has gone wrong. The last redirects the Web browser to the URL the server has supplied. The Location directive, among other uses, is how imagemap software 
turns a mouse-click into a new Web page for the mouse-clicker.</BLOCKQUOTE>

</TD></TR>
</TABLE></CENTER>
<P>
<P>
A rectangle can be uniquely identified by specifying its top-left
and bottom-right coordinates within an image as x<FONT SIZE=1>1</FONT>,y<FONT SIZE=1>1</FONT>
and x<FONT SIZE=1>2</FONT>,y<FONT SIZE=1>2</FONT>. A circle can
be uniquely identified by specifying its center, x<FONT SIZE=1>cen</FONT>,y<FONT SIZE=1>cen</FONT>,
and any point on its circumference, x<FONT SIZE=1>cir</FONT>,y<FONT SIZE=1>cir</FONT>.
A polygon can be uniquely specified by a list of all its vertices:
x<FONT SIZE=1>1</FONT>,y<FONT SIZE=1>1</FONT>, x<FONT SIZE=1>2</FONT>,y<FONT SIZE=1>2</FONT>,
x<FONT SIZE=1>3</FONT>,y<FONT SIZE=1>3</FONT>, .. x<FONT SIZE=1>n</FONT>,y<FONT SIZE=1>n</FONT>.
To make computation easier, imagemap handlers usually limit the
number of vertices a polygon may possess to some large number,
usually 100. For the purposes of .map files, rectangles are abbreviated
to rect and polygons to poly.
<P>
Obviously, a point is fully described by itself: x,y. In the context
of imagemap.cgi, if a mouse-click lies outside of any defined
region (rect, circle, or poly), it is compared against all specified
point coordinates. The imagemap handler will redirect the user
to the URL specified on the point line whose coordinates are nearest
to the mouse-click. As it is stated so eloquently in the ncSA
Imagemap tutorial, &quot;The nearest point wins.&quot;
<P>
The point method makes sense only if there is more than one point
line in a file. Otherwise, the one point that is defined would
always &quot;win.&quot; If that's what you actually want to happen,
you should use the default method. This is invoked when two conditions
are met: The mouse-click isn't found to lie within any of the
described shapes, and there are no point lines in the .map file.
<P>
Every line in a .map file has a very straightforward syntax. For
all lines except default, it is
<BLOCKQUOTE>
<TT><FONT FACE="Courier">shape URL coordinates</FONT></TT>
</BLOCKQUOTE>
<P>
This syntax differs for default to make it even simpler:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">default URL</FONT></TT>
</BLOCKQUOTE>
<P>
Putting all these concepts together, we get a logical .map file:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">rect URL x1,y1 x2,y2<BR>
circle URL xcen,ycen xcir,ycir<BR>
poly URL x1,y1 x2,y2 x3,y3 .. xn,yn<BR>
point URL x,y<BR>
..<BR>
point URL x,y<BR>
default URL</FONT></TT>
</BLOCKQUOTE>
<P>
You may have as many rect, circle, poly, and point lines in a
.map file as you need. Also, blank lines are skipped, and lines
beginning with the <TT><FONT FACE="Courier">#</FONT></TT> character
(also known as &quot;number,&quot; &quot;pound,&quot; or finally
&quot;hash&quot; to the truly hackish) are ignored as comments.
<P>
<CENTER><TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR><TD><B>Tip</B></TD></TR>