| <!--%hypertext --> |
| <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> |
| <html> |
| <head> |
| <title>Apache module mod_imap</title> |
| </head> |
| |
| <body> |
| <IMG SRC="../images/apache_sub.gif" ALT=""> |
| <!--/%hypertext --> |
| <h1>Module mod_imap</h1> |
| |
| This module is contained in the <code>mod_imap.c</code> file, and |
| is compiled in by default. It provides for <code>.map</code> files, |
| replacing the functionality of the <code>imagemap</code> CGI program. Any |
| directory or document type configured to use the handler <code>imap-file</code> |
| (using either <code><A |
| HREF="http://www.apache.org/docs/mod_mime.html#addhandler">AddHandler</A> |
| </code> or <code><A |
| HREF="http://www.apache.org/docs/mod_mime.html#sethandler">SetHandler</A></code>) |
| |
| will be |
| processed by this module. |
| |
| <h2>Summary</h2> |
| |
| This module is in the default Apache distribution. The following directive will |
| activate files ending with <code>.map</code> as imagemap files: |
| |
| <blockquote><code>AddHandler imap-file map</code></blockquote> |
| |
| Note that the following is still supported: |
| |
| <blockquote><code>AddType application/x-httpd-imap map</code></blockquote> |
| |
| However, we are trying to phase out "magic MIME types" so we are deprecating |
| this method. |
| |
| <H2>New Features</H2> |
| The imagemap module adds some new features that were not |
| possible with previously distributed imagemap programs.<P> |
| |
| <ul> |
| <LI>URL references relative to the Referer: information. |
| <LI>Default <BASE> assignment through a new map directive |
| <code>base</code>. |
| <LI>No need for <code>imagemap.conf</code> file. |
| <LI>Point references. |
| <LI>Configurable generation of imagemap menus. |
| </ul> |
| <P> |
| |
| <h2>Configuration Directives</h2> |
| <ul> |
| <li><A HREF="#imapmenu">ImapMenu</A> |
| <li><A HREF="#imapdefault">ImapDefault</A> |
| <li><A HREF="#imapbase">ImapBase</A> |
| </ul> |
| |
| |
| <p> |
| |
| <A name="imapmenu"><h3>ImapMenu</h3></A> |
| <strong>Syntax:</strong> ImapMenu <code>{none, formatted, semiformatted, |
| unformatted}</code><br> |
| <Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> |
| <Strong>Override:</strong> Indexes<br> |
| <strong>Module:</strong> mod_imap.c<br> |
| <strong>Compatibility:</strong> ImapMenu is only available in Apache |
| 1.1 and later.<p> |
| |
| The ImapMenu directive determines the action taken if an imagemap file |
| is called without valid coordinates. |
| <dl> |
| <dt><code>none</code> |
| <dd>If ImapMenu is |
| <code>none</code>, no menu is generated, and the <code>default</code> |
| action is performed. |
| <dt><code>formatted</code> |
| <dd>A <code>formatted</code> menu is the simplest menu. Comments |
| in the imagemap file are ignored. A level one header is |
| printed, then an hrule, then the links each on a separate line. |
| The menu has a consistent, plain look close to that of |
| a directory listing. |
| <dt><code>semiformatted</code> |
| <dd>In the <code>semiformatted</code> menu, comments are printed |
| where they occur in the imagemap file. Blank lines are turned |
| into HTML breaks. No header or hrule is printed, but otherwise |
| the menu is the same as a <code>formatted</code> menu. |
| <dt><code>unformatted</code> |
| <dd>Comments are printed, blank lines are ignored. Nothing is |
| printed that does not appear in the imagemap file. All breaks |
| and headers must be included as comments in the imagemap file. |
| This gives you the most flexibility over the appearance of your |
| menus, but requires you to treat your map files as HTML instead |
| of plaintext. |
| </dl> |
| |
| <p> |
| |
| <A name="imapdefault"><h3>ImapDefault</h3></A> |
| <strong>Syntax:</strong> ImapDefault <code>{error, nocontent, |
| map, referer, URL}</code><br> |
| <Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> |
| <Strong>Override:</strong> Indexes<br> |
| <strong>Module:</strong> mod_imap.c<br> |
| <strong>Compatibility:</strong> ImapDefault is only available in Apache |
| 1.1 and later.<p> |
| |
| |
| The ImapDefault directive sets the default <code>default</code> used in |
| the imagemap files. It's value is overridden by a <code>default</code> |
| directive within the imagemap file. If not present, the |
| <code>default</code> action is <code>nocontent</code>, which means |
| that a <code>204 No Content</code> is sent to the client. In this |
| case, the client should continue to display the original page. |
| |
| <p> |
| |
| <A name="imapbase"><h3>ImapBase</h3></A> |
| <strong>Syntax:</strong> ImapBase <code>{map, referer, URL}</code><br> |
| <Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> |
| <Strong>Override:</strong> Indexes<br> |
| <strong>Module:</strong> mod_imap.c<br> |
| <strong>Compatibility:</strong> ImapBase is only available in Apache |
| 1.1 and later.<p> |
| |
| The ImapBase directive sets the default <code>base</code> used in |
| the imagemap files. It's value is overridden by a <code>base</code> |
| directive within the imagemap file. If not present, the |
| <code>base</code> defaults to <code>http://servername/</code>. |
| |
| <hr> |
| <p> |
| |
| <h2>Imagemap File</h2> |
| The lines in the imagemap files can have one of several formats: |
| <blockquote> |
| <code>directive value [x,y ...]</code><br> |
| <code>directive value "Menu text" [x,y ...]</code><br> |
| <code>directive value x,y ... "Menu text"</code><br> |
| </blockquote> |
| The directive is one of <code>base</code>, <code>default</code>, |
| <code>poly</code>, <code>circle</code>, <code>rect</code>, or |
| <code>point</code>. The value is an absolute or relative URL, or one |
| of the special values listed below. The coordinates are |
| <code>x,y</code> pairs seperated by whitespace. The quoted text is |
| used as the text of the link if a imagemap menu is generated. Lines |
| beginning with '#' are comments. |
| |
| <h3>Imagemap File Directives</h3> |
| There are six directives allowed in the imagemap file. The directives |
| can come in any order, but are processed in the order they are found |
| in the imagemap file. |
| <dl> |
| <dt><code>base</code> Directive |
| <dd>Has the effect of <code><BASE href="value"></code>. The |
| non-absolute URLs of the mapfile are taken relative to this value. |
| The <code>base</code> directive overrides ImapBase as set in a |
| .htaccess file or in the server configuration files. In the absence |
| of an ImapBase configuration directive, <code>base</code> defaults to |
| <code>http://server_name/</code>. <br> |
| <code>base_uri</code> is synonymous with <code>base</code>. Note that |
| a trailing slash on the URL is significant. |
| <p> |
| <dt><code>default</code> Directive |
| <dd>The action taken if the coordinates given do not fit any of the |
| <code>poly</code>, <code>circle</code> or <code>rect</code> |
| directives, and there are no <code>point</code> directives. Defaults |
| to <code>nocontent</code> in the absence of an ImapDefault |
| configuration setting, causing a status code of <code>204 No |
| Content</code> to be returned. The client should keep the same |
| page displayed. |
| <p> |
| <dt><code>poly</code> Directive |
| <dd>Takes three to one-hundred points, and is obeyed if the user selected |
| coordinates fall within the polygon defined by these points. |
| <p> |
| <dt><code>circle</code> |
| <dd>Takes the center coordinates of a circle and a point on the circle. Is |
| obeyed if the user selected point is with the circle. |
| <p> |
| <dt><code>rect</code> Directive |
| <dd>Takes the coordinates of two opposing corners of a rectangle. Obeyed |
| if the point selected is within this rectangle. |
| <p> |
| <dt><code>point</code> Directive |
| <dd>Takes a single point. The point directive closest to the user |
| selected point is obeyed if no other directives are satisfied. |
| Note that <code>default</code> will not be followed if a |
| <code>point</code> directive is present and valid coordinates are |
| given. |
| </dl> |
| |
| |
| |
| <h3>Values</h3> |
| The values for each of the directives can any of the following: |
| <dl> |
| <dt>a URL |
| <dd>The URL can be relative or absolute URL. Relative URLs can |
| contain '..' syntax and will be resolved relative to the |
| <code>base</code> value. <br> |
| <code>base</code> itself will not resolved according to the current |
| value. A statement <code>base mailto:</code> will work properly, though. |
| <p> |
| <dt><code>map</code> |
| <dd>Equivalent to the URL of the imagemap file itself. No |
| coordinates are sent with this, so a menu will be generated |
| unless ImapMenu is set to 'none'. |
| <p> |
| <dt><code>menu</code> |
| <dd>Synonymous with <code>map</code>. |
| <p> |
| <dt><code>referer</code> |
| <dd>Equivalent to the URL of the refering document. |
| Defaults to <code>http://servername/</code> if no Referer: |
| header was present. |
| <p> |
| <dt><code>nocontent</code> |
| <dd>Sends a status code of <code>204 No Content</code>, |
| telling the client to keep the same page displayed. Valid for |
| all but <code>base</code>. |
| <p> |
| <dt><code>error</code> |
| <dd>Fails with a <code>500 Server Error</code>. Valid for all but |
| <code>base</code>, but sort of silly for anything but |
| <code>default</code>. |
| </dl> |
| |
| <h3>Coordinates</h3> |
| <dl> |
| <dt><code>0,0 200,200</code> |
| <dd>A coordinate consists of an <tt>x</tt> and a <tt>y</tt> value |
| separated by a comma. The coordinates are separated from each other |
| by whitespace. To accomodate the way Lynx handles imagemaps, should a |
| user select the coordinate <code>0,0</code>, it is as if |
| no coordinate had been selected. |
| </dl> |
| |
| <h3>Quoted Text</h3> |
| <dl> |
| <dt><code>"Menu Text"</code> |
| <dd>After the value or after the coordinates, the line optionally may |
| contain text within double quotes. This string is used as the |
| text for the link if a menu is generated:<br> |
| <code><a href="http://foo.com/">Menu text</a></code><br> |
| If no quoted text is present, the name of the link will be used |
| as the text:<br> |
| <code><a href="http://foo.com/">http://foo.com</a></code><br> |
| It is impossible to escape double quotes within this text. |
| </dl> |
| |
| <hr> |
| |
| <h2>Example Mapfile</h2> |
| <blockquote><code> |
| #Comments are printed in a 'formatted' or 'semiformatted' menu. <br> |
| #And can contain html tags. <hr> <br> |
| base referer <br> |
| poly map "Could I have a menu, please?" 0,0 0,10 10,10 10,0 <br> |
| rect .. 0,0 77,27 "the directory of the referer"<br> |
| circle http://www.inetnebr.com/lincoln/feedback/ 195,0 305,27 <br> |
| rect another_file "in same directory as referer" 306,0 419,27 <br> |
| point http://www.zyzzyva.com/ 100,100 <br> |
| point http://www.tripod.com/ 200,200 <br> |
| rect mailto:nate@tripod.com 100,150 200,0 "Bugs?" <br> |
| </code></blockquote> |
| <P> |
| |
| <h2>Referencing your mapfile</h2> |
| <blockquote><code> |
| <A HREF="/maps/imagmap1.map"> <br> |
| <IMG ISMAP SRC="/images/imagemap1.gif"> <br> |
| </A> |
| </code></blockquote><p> |
| <!--%hypertext --> |
| <HR> |
| <A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> |
| <A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> |
| </BODY> |
| </HTML> |
| <!--/%hypertext --> |
| |