2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
6 Copyright 2002-2004 The Apache Software Foundation
8 Licensed under the Apache License, Version 2.0 (the "License");
9 you may not use this file except in compliance with the License.
10 You may obtain a copy of the License at
12 http://www.apache.org/licenses/LICENSE-2.0
14 Unless required by applicable law or agreed to in writing, software
15 distributed under the License is distributed on an "AS IS" BASIS,
16 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17 See the License for the specific language governing permissions and
18 limitations under the License.
21 <modulesynopsis metafile="mod_imap.xml.meta">
24 <description>Server-side imagemap processing</description>
26 <sourcefile>mod_imap.c</sourcefile>
27 <identifier>imap_module</identifier>
30 <p>This module processes <code>.map</code> files, thereby
31 replacing the functionality of the <code>imagemap</code> CGI
32 program. Any directory or document type configured to use the
33 handler <code>imap-file</code> (using either
34 <directive module="mod_mime">AddHandler</directive> or
35 <directive module="core">SetHandler</directive>)
36 will be processed by this module.</p>
38 <p>The following directive will activate files ending with
39 <code>.map</code> as imagemap files:</p>
41 <example>AddHandler imap-file map</example>
43 <p>Note that the following is still supported:</p>
45 <example>AddType application/x-httpd-imap map</example>
47 <p>However, we are trying to phase out "magic MIME types" so we
48 are deprecating this method.</p>
51 <section id="features"><title>New Features</title>
53 <p>The imagemap module adds some new features that were not
54 possible with previously distributed imagemap programs.</p>
57 <li>URL references relative to the Referer: information.</li>
59 <li>Default <code><base></code> assignment through a new map
60 directive <code>base</code>.</li>
62 <li>No need for <code>imagemap.conf</code> file.</li>
64 <li>Point references.</li>
66 <li>Configurable generation of imagemap menus.</li>
70 <section id="imapfile"><title>Imagemap File</title>
72 <p>The lines in the imagemap files can have one of several
76 directive value [<var>x</var>,<var>y</var> ...]<br />
77 directive value "<var>Menu text</var>" [<var>x</var>,<var>y</var>
79 directive value <var>x</var>,<var>y</var> ... "<var>Menu text</var>"
82 <p>The directive is one of <code>base</code>,
83 <code>default</code>, <code>poly</code>, <code>circle</code>,
84 <code>rect</code>, or <code>point</code>. The value is an
85 absolute or relative URL, or one of the special values listed
86 below. The coordinates are <code><var>x</var>,<var>y</var></code>
87 pairs separated by whitespace. The quoted text is used as the text of
88 the link if a imagemap menu is generated. Lines beginning with '#' are
91 <section id="imapfile.directives"><title>Imagemap File Directives</title>
92 <p>There are six directives allowed in the imagemap file. The
93 directives can come in any order, but are processed in the
94 order they are found in the imagemap file.</p>
97 <dt><code>base</code> Directive</dt>
99 <dd><p>Has the effect of <code><base href="<var>value</var>">
100 </code>. The non-absolute URLs of the map-file are taken relative
101 to this value. The <code>base</code> directive overrides
102 <directive module="mod_imap">ImapBase</directive> as set in a
103 <code>.htaccess</code> file or in the server configuration files.
104 In the absence of an <directive>ImapBase</directive> configuration
105 directive, <code>base</code> defaults to
106 <code>http://server_name/</code>.</p>
107 <p><code>base_uri</code> is synonymous with <code>base</code>.
108 Note that a trailing slash on the URL is significant.</p></dd>
110 <dt><code>default</code> Directive</dt>
112 <dd>The action taken if the coordinates given do not fit any
113 of the <code>poly</code>, <code>circle</code> or
114 <code>rect</code> directives, and there are no
115 <code>point</code> directives. Defaults to <code>nocontent</code>
116 in the absence of an <directive module="mod_imap"
117 >ImapDefault</directive> configuration setting, causing a status
118 code of <code>204 No Content</code> to be returned. The client
119 should keep the same page displayed.</dd>
121 <dt><code>poly</code> Directive</dt>
123 <dd>Takes three to one-hundred points, and is obeyed if the
124 user selected coordinates fall within the polygon defined by
127 <dt><code>circle</code></dt>
129 <dd>Takes the center coordinates of a circle and a point on
130 the circle. Is obeyed if the user selected point is with the
133 <dt><code>rect</code> Directive</dt>
135 <dd>Takes the coordinates of two opposing corners of a
136 rectangle. Obeyed if the point selected is within this
139 <dt><code>point</code> Directive</dt>
141 <dd>Takes a single point. The point directive closest to the
142 user selected point is obeyed if no other directives are
143 satisfied. Note that <code>default</code> will not be
144 followed if a <code>point</code> directive is present and
145 valid coordinates are given.</dd>
149 <section id="imapfile.values"><title>Values</title>
151 <p>The values for each of the directives can any of the following:</p>
156 <dd><p>The URL can be relative or absolute URL. Relative URLs
157 can contain '..' syntax and will be resolved relative to the
158 <code>base</code> value.</p>
159 <p><code>base</code> itself will not resolved according to the
160 current value. A statement <code>base mailto:</code> will
161 work properly, though.</p></dd>
163 <dt><code>map</code></dt>
165 <dd>Equivalent to the URL of the imagemap file itself. No
166 coordinates are sent with this, so a menu will be generated
167 unless <directive module="mod_imap">ImapMenu</directive> is set to
168 <code>none</code>.</dd>
170 <dt><code>menu</code></dt>
171 <dd>Synonymous with <code>map</code>.</dd>
173 <dt><code>referer</code></dt>
175 <dd>Equivalent to the URL of the referring document. Defaults
176 to <code>http://servername/</code> if no <code>Referer:</code>
177 header was present.</dd>
179 <dt><code>nocontent</code></dt>
181 <dd>Sends a status code of <code>204 No Content</code>,
182 telling the client to keep the same page displayed. Valid for
183 all but <code>base</code>.</dd>
185 <dt><code>error</code></dt>
187 <dd>Fails with a <code>500 Server Error</code>. Valid for all
188 but <code>base</code>, but sort of silly for anything but
189 <code>default</code>.</dd>
193 <section id="imapfile.coords"><title>Coordinates</title>
196 <dt><code>0,0 200,200</code></dt>
198 <dd>A coordinate consists of an <var>x</var> and a <var>y</var>
199 value separated by a comma. The coordinates are separated
200 from each other by whitespace. To accommodate the way Lynx
201 handles imagemaps, should a user select the coordinate
202 <code>0,0</code>, it is as if no coordinate had been
208 <section id="imapfile.quotedtext"><title>Quoted Text</title>
211 <dt><code>"<var>Menu Text</var>"</code></dt>
213 <dd><p>After the value or after the coordinates, the line
214 optionally may contain text within double quotes. This string
215 is used as the text for the link if a menu is
219 <a href="http://foo.com/"><var>Menu text</var></a>
222 <p>If no quoted text is present, the name of the link will be
223 used as the text:</p>
226 <a href="http://foo.com/">http://foo.com</a>
229 <p>If you want to use double quotes within this text, you have to
230 write them as <code>&quot;</code>.</p></dd>
236 <section id="example"><title>Example Mapfile</title>
239 #Comments are printed in a 'formatted' or 'semiformatted' menu.<br />
240 #And can contain html tags. <hr><br />
242 poly map "Could I have a menu, please?" 0,0 0,10 10,10 10,0<br />
243 rect .. 0,0 77,27 "the directory of the referer"<br />
244 circle http://www.inetnebr.com/lincoln/feedback/ 195,0 305,27<br />
245 rect another_file "in same directory as referer" 306,0 419,27<br />
246 point http://www.zyzzyva.com/ 100,100<br />
247 point http://www.tripod.com/ 200,200<br />
248 rect mailto:nate@tripod.com 100,150 200,0 "Bugs?"<br />
253 <section id="referencing"><title>Referencing your mapfile</title>
255 <example><title>HTML example</title>
256 <a href="/maps/imagemap1.map"><br />
258 <img ismap src="/images/imagemap1.gif"><br />
263 <example><title>XHTML example</title>
264 <a href="/maps/imagemap1.map"><br />
266 <img ismap="ismap" src="/images/imagemap1.gif" /><br />
274 <name>ImapMenu</name>
275 <description>Action if no coordinates are given when calling
276 an imagemap</description>
277 <syntax>ImapMenu none|formatted|semiformatted|unformatted</syntax>
278 <contextlist><context>server config</context><context>virtual host</context>
279 <context>directory</context><context>.htaccess</context></contextlist>
280 <override>Indexes</override>
283 <p>The <directive>ImapMenu</directive> directive determines the
284 action taken if an imagemap file is called without valid
288 <dt><code>none</code></dt>
289 <dd>If ImapMenu is <code>none</code>, no menu is generated,
290 and the <code>default</code> action is performed.</dd>
292 <dt><code>formatted</code></dt>
293 <dd>A <code>formatted</code> menu is the simplest menu.
294 Comments in the imagemap file are ignored. A level one header
295 is printed, then an hrule, then the links each on a separate
296 line. The menu has a consistent, plain look close to that of
297 a directory listing.</dd>
299 <dt><code>semiformatted</code></dt>
300 <dd>In the <code>semiformatted</code> menu, comments are
301 printed where they occur in the imagemap file. Blank lines
302 are turned into HTML breaks. No header or hrule is printed,
303 but otherwise the menu is the same as a
304 <code>formatted</code> menu.</dd>
306 <dt><code>unformatted</code></dt>
307 <dd>Comments are printed, blank lines are ignored. Nothing is
308 printed that does not appear in the imagemap file. All breaks
309 and headers must be included as comments in the imagemap
310 file. This gives you the most flexibility over the appearance
311 of your menus, but requires you to treat your map files as
312 HTML instead of plaintext.</dd>
318 <name>ImapDefault</name>
319 <description>Default action when an imagemap is called with coordinates
320 that are not explicitly mapped</description>
321 <syntax>ImapDefault error|nocontent|map|referer|<var>URL</var></syntax>
322 <default>ImapDefault nocontent</default>
323 <contextlist><context>server config</context><context>virtual host</context>
324 <context>directory</context><context>.htaccess</context></contextlist>
325 <override>Indexes</override>
328 <p>The <directive>ImapDefault</directive> directive sets the default
329 <code>default</code> used in the imagemap files. Its value is
330 overridden by a <code>default</code> directive within the
331 imagemap file. If not present, the <code>default</code> action
332 is <code>nocontent</code>, which means that a <code>204 No
333 Content</code> is sent to the client. In this case, the client
334 should continue to display the original page.</p>
339 <name>ImapBase</name>
340 <description>Default <code>base</code> for imagemap files</description>
341 <syntax>ImapBase map|referer|<var>URL</var></syntax>
342 <default>ImapBase http://servername/</default>
343 <contextlist><context>server config</context><context>virtual host</context>
344 <context>directory</context><context>.htaccess</context></contextlist>
345 <override>Indexes</override>
348 <p>The <directive>ImapBase</directive> directive sets the default
349 <code>base</code> used in the imagemap files. Its value is
350 overridden by a <code>base</code> directive within the imagemap
351 file. If not present, the <code>base</code> defaults to
352 <code>http://<var>servername</var>/</code>.</p>
354 <seealso><directive module="core">UseCanonicalName</directive></seealso>