mod_imap.html revision 25503838e438bb909e3ff880125732c7ed5e64ad
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graff<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graff<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graff BGCOLOR="#FFFFFF"
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graff TEXT="#000000"
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graff LINK="#0000FF"
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graff VLINK="#000080"
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graff ALINK="#FF0000"
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graff<!--#include virtual="header.html" -->
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael GraffThis module is contained in the <CODE>mod_imap.c</CODE> file, and is
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graffcompiled in by default. It provides for <CODE>.map</CODE> files,
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graffreplacing the functionality of the <CODE>imagemap</CODE> CGI
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graffprogram. Any directory or document type configured to use the handler
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael GraffHREF="mod_mime.html#addhandler">AddHandler</A> </CODE> or <CODE><A
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael GraffHREF="mod_mime.html#sethandler">SetHandler</A></CODE>) will be
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graffprocessed by this module.
f9df80f4348ef68043903efa08299480324f4823Michael GraffThis module is in the default Apache distribution. The following directive will
fccf7905e8a06067d49ec00c53d4d57a38a71e52Michael Graffactivate files ending with <CODE>.map</CODE> as imagemap files:
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graff<BLOCKQUOTE><CODE>AddHandler imap-file map</CODE></BLOCKQUOTE>
f9df80f4348ef68043903efa08299480324f4823Michael GraffNote that the following is still supported:
f9df80f4348ef68043903efa08299480324f4823Michael Graff <BLOCKQUOTE><CODE>AddType application/x-httpd-imap map</CODE></BLOCKQUOTE>
f9df80f4348ef68043903efa08299480324f4823Michael GraffHowever, we are trying to phase out "magic MIME types" so we are deprecating
97e7d389d54a9e3a1ba8313ed140b04afabc7081Michael GraffThe imagemap module adds some new features that were not
97e7d389d54a9e3a1ba8313ed140b04afabc7081Michael Graffpossible with previously distributed imagemap programs.<P>
f9df80f4348ef68043903efa08299480324f4823Michael Graff<LI>URL references relative to the Referer: information.
f9df80f4348ef68043903efa08299480324f4823Michael Graff<LI>Default <BASE> assignment through a new map directive
f9df80f4348ef68043903efa08299480324f4823Michael Graff<LI>No need for <CODE>imagemap.conf</CODE> file.
f9df80f4348ef68043903efa08299480324f4823Michael Graff<LI>Point references.
f9df80f4348ef68043903efa08299480324f4823Michael Graff<LI>Configurable generation of imagemap menus.
f9df80f4348ef68043903efa08299480324f4823Michael Graff><STRONG>Syntax:</STRONG></A> ImapMenu <CODE>{none, formatted, semi-formatted,
fccf7905e8a06067d49ec00c53d4d57a38a71e52Michael Graff><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR>
97e7d389d54a9e3a1ba8313ed140b04afabc7081Michael Graff HREF="directive-dict.html#Compatibility"
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graff><STRONG>Compatibility:</STRONG></A> ImapMenu is only available in Apache
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graff1.1 and later.<P>
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael GraffThe ImapMenu directive determines the action taken if an imagemap file
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graffis called without valid coordinates.
f9df80f4348ef68043903efa08299480324f4823Michael Graff <DD>If ImapMenu is
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graff <CODE>none</CODE>, no menu is generated, and the <CODE>default</CODE>
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graff action is performed.
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graff <DD>A <CODE>formatted</CODE> menu is the simplest menu. Comments
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graff in the imagemap file are ignored. A level one header is
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graff printed, then an hrule, then the links each on a separate line.
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graff The menu has a consistent, plain look close to that of
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graff a directory listing.
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graff <DD>In the <CODE>semiformatted</CODE> menu, comments are printed
97e7d389d54a9e3a1ba8313ed140b04afabc7081Michael Graff where they occur in the imagemap file. Blank lines are turned
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graff into HTML breaks. No header or hrule is printed, but otherwise
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graff the menu is the same as a <CODE>formatted</CODE> menu.
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graff <DD>Comments are printed, blank lines are ignored. Nothing is
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graff printed that does not appear in the imagemap file. All breaks
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graff and headers must be included as comments in the imagemap file.
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graff This gives you the most flexibility over the appearance of your
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graff menus, but requires you to treat your map files as HTML instead
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graff of plaintext.
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graff><STRONG>Syntax:</STRONG></A> ImapDefault <CODE>{error, nocontent,
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graff><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR>
f9df80f4348ef68043903efa08299480324f4823Michael Graff HREF="directive-dict.html#Compatibility"
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graff><STRONG>Compatibility:</STRONG></A> ImapDefault is only available in Apache
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graff1.1 and later.<P>
97e7d389d54a9e3a1ba8313ed140b04afabc7081Michael GraffThe ImapDefault directive sets the default <CODE>default</CODE> used in
97e7d389d54a9e3a1ba8313ed140b04afabc7081Michael Graffthe imagemap files. It's value is overridden by a <CODE>default</CODE>
9178881e1bf6a4b01db886b355406c8bed61cc2aMichael Graffdirective within the imagemap file. If not present, the
97e7d389d54a9e3a1ba8313ed140b04afabc7081Michael Graff<CODE>default</CODE> action is <CODE>nocontent</CODE>, which means
97e7d389d54a9e3a1ba8313ed140b04afabc7081Michael Graffthat a <CODE>204 No Content</CODE> is sent to the client. In this
97e7d389d54a9e3a1ba8313ed140b04afabc7081Michael Graffcase, the client should continue to display the original page.
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff><STRONG>Syntax:</STRONG></A> ImapBase <CODE>{map, referer, URL}</CODE><BR>
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR>
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff HREF="directive-dict.html#Compatibility"
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff><STRONG>Compatibility:</STRONG></A> ImapBase is only available in Apache
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff1.1 and later.<P>
d68838693666ba930ec4143f848c18bff2bfc244Michael GraffThe ImapBase directive sets the default <CODE>base</CODE> used in
d68838693666ba930ec4143f848c18bff2bfc244Michael Graffthe imagemap files. It's value is overridden by a <CODE>base</CODE>
d68838693666ba930ec4143f848c18bff2bfc244Michael Graffdirective within the imagemap file. If not present, the
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff<CODE>base</CODE> defaults to <CODE>http://servername/</CODE>.
d68838693666ba930ec4143f848c18bff2bfc244Michael GraffThe lines in the imagemap files can have one of several formats:
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff<CODE>directive value "Menu text" [x,y ...]</CODE><BR>
70fd62761dfe44f2254fb63ac3ded1b02663713fMichael Graff<CODE>directive value x,y ... "Menu text"</CODE><BR>
d68838693666ba930ec4143f848c18bff2bfc244Michael GraffThe directive is one of <CODE>base</CODE>, <CODE>default</CODE>,
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff<CODE>poly</CODE>, <CODE>circle</CODE>, <CODE>rect</CODE>, or
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff<CODE>point</CODE>. The value is an absolute or relative URL, or one
d68838693666ba930ec4143f848c18bff2bfc244Michael Graffof the special values listed below. The coordinates are
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff<CODE>x,y</CODE> pairs separated by whitespace. The quoted text is
d68838693666ba930ec4143f848c18bff2bfc244Michael Graffused as the text of the link if a imagemap menu is generated. Lines
d68838693666ba930ec4143f848c18bff2bfc244Michael Graffbeginning with '#' are comments.
70fd62761dfe44f2254fb63ac3ded1b02663713fMichael GraffThere are six directives allowed in the imagemap file. The directives
d68838693666ba930ec4143f848c18bff2bfc244Michael Graffcan come in any order, but are processed in the order they are found
d68838693666ba930ec4143f848c18bff2bfc244Michael Graffin the imagemap file.
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff<DD>Has the effect of <CODE><BASE HREF="value"></CODE>. The
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff non-absolute URLs of the map-file are taken relative to this value.
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff The <CODE>base</CODE> directive overrides ImapBase as set in a
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff .htaccess file or in the server configuration files. In the absence
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff of an ImapBase configuration directive, <CODE>base</CODE> defaults to
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff <CODE>base_uri</CODE> is synonymous with <CODE>base</CODE>. Note that
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff a trailing slash on the URL is significant.
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff<DD>The action taken if the coordinates given do not fit any of the
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff <CODE>poly</CODE>, <CODE>circle</CODE> or <CODE>rect</CODE>
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff directives, and there are no <CODE>point</CODE> directives. Defaults
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff to <CODE>nocontent</CODE> in the absence of an ImapDefault
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff configuration setting, causing a status code of <CODE>204 No
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff Content</CODE> to be returned. The client should keep the same
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff page displayed.
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff<DD>Takes three to one-hundred points, and is obeyed if the user selected
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff coordinates fall within the polygon defined by these points.
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff<DD>Takes the center coordinates of a circle and a point on the circle. Is
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff obeyed if the user selected point is with the circle.
70fd62761dfe44f2254fb63ac3ded1b02663713fMichael Graff<DD>Takes the coordinates of two opposing corners of a rectangle. Obeyed
70fd62761dfe44f2254fb63ac3ded1b02663713fMichael Graff if the point selected is within this rectangle.
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff<DD>Takes a single point. The point directive closest to the user
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff selected point is obeyed if no other directives are satisfied.
97e7d389d54a9e3a1ba8313ed140b04afabc7081Michael Graff Note that <CODE>default</CODE> will not be followed if a
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff <CODE>point</CODE> directive is present and valid coordinates are
d68838693666ba930ec4143f848c18bff2bfc244Michael GraffThe values for each of the directives can any of the following:
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff <DD>The URL can be relative or absolute URL. Relative URLs can
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff contain '..' syntax and will be resolved relative to the
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff <CODE>base</CODE> itself will not resolved according to the current
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff value. A statement <CODE>base mailto:</CODE> will work properly, though.
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff <DD>Equivalent to the URL of the imagemap file itself. No
70fd62761dfe44f2254fb63ac3ded1b02663713fMichael Graff coordinates are sent with this, so a menu will be generated
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff unless ImapMenu is set to 'none'.
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff <DD>Equivalent to the URL of the referring document.
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff Defaults to <CODE>http://servername/</CODE> if no Referer:
70fd62761dfe44f2254fb63ac3ded1b02663713fMichael Graff header was present.
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff <DD>Sends a status code of <CODE>204 No Content</CODE>,
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff telling the client to keep the same page displayed. Valid for
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff <DD>Fails with a <CODE>500 Server Error</CODE>. Valid for all but
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff <CODE>base</CODE>, but sort of silly for anything but
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff <DD>A coordinate consists of an <TT>x</TT> and a <TT>y</TT> value
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff separated by a comma. The coordinates are separated from each other
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff by whitespace. To accommodate the way Lynx handles imagemaps, should a
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff user select the coordinate <CODE>0,0</CODE>, it is as if
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff no coordinate had been selected.
70fd62761dfe44f2254fb63ac3ded1b02663713fMichael Graff <DD>After the value or after the coordinates, the line optionally may
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff contain text within double quotes. This string is used as the
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff text for the link if a menu is generated:<BR>
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff <CODE><a HREF="http://foo.com/">Menu text</a></CODE><BR>
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff If no quoted text is present, the name of the link will be used
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff as the text:<BR>
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff <CODE><a HREF="http://foo.com/">http://foo.com</a></CODE><BR>
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff It is impossible to escape double quotes within this text.
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff#Comments are printed in a 'formatted' or 'semiformatted' menu. <BR>
97e7d389d54a9e3a1ba8313ed140b04afabc7081Michael Graff#And can contain html tags. <hr> <BR>
d68838693666ba930ec4143f848c18bff2bfc244Michael Graffbase referer <BR>
d68838693666ba930ec4143f848c18bff2bfc244Michael Graffpoly map "Could I have a menu, please?" 0,0 0,10 10,10 10,0 <BR>
d68838693666ba930ec4143f848c18bff2bfc244Michael Graffrect .. 0,0 77,27 "the directory of the referer"<BR>
d68838693666ba930ec4143f848c18bff2bfc244Michael Graffcircle http://www.inetnebr.com/lincoln/feedback/ 195,0 305,27 <BR>
d68838693666ba930ec4143f848c18bff2bfc244Michael Graffrect another_file "in same directory as referer" 306,0 419,27 <BR>
d68838693666ba930ec4143f848c18bff2bfc244Michael Graffrect mailto:nate@tripod.com 100,150 200,0 "Bugs?" <BR>
d68838693666ba930ec4143f848c18bff2bfc244Michael Graff<IMG ISMAP SRC="/images/imagemap1.gif"> <BR>
f9df80f4348ef68043903efa08299480324f4823Michael Graff<!--#include virtual="footer.html" -->