2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Licensed to the Apache Software Foundation (ASF) under one or more
8 contributor license agreements. See the NOTICE file distributed with
9 this work for additional information regarding copyright ownership.
10 The ASF licenses this file to You under the Apache License, Version 2.0
11 (the "License"); you may not use this file except in compliance with
12 the License. You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
16 Unless required by applicable law or agreed to in writing, software
17 distributed under the License is distributed on an "AS IS" BASIS,
18 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 See the License for the specific language governing permissions and
20 limitations under the License.
23 <modulesynopsis metafile="mod_imagemap.xml.meta">
25 <name>mod_imagemap</name>
26 <description>Server-side imagemap processing</description>
28 <sourcefile>mod_imagemap.c</sourcefile>
29 <identifier>imagemap_module</identifier>
32 <p>This module processes <code>.map</code> files, thereby
33 replacing the functionality of the <code>imagemap</code> CGI
34 program. Any directory or document type configured to use the
35 handler <code>imap-file</code> (using either
36 <directive module="mod_mime">AddHandler</directive> or
37 <directive module="core">SetHandler</directive>)
38 will be processed by this module.</p>
40 <p>The following directive will activate files ending with
41 <code>.map</code> as imagemap files:</p>
43 <highlight language="config">AddHandler imap-file map</highlight>
45 <p>Note that the following is still supported:</p>
47 <highlight language="config">AddType application/x-httpd-imap map</highlight>
49 <p>However, we are trying to phase out "magic MIME types" so we
50 are deprecating this method.</p>
53 <section id="features"><title>New Features</title>
55 <p>The imagemap module adds some new features that were not
56 possible with previously distributed imagemap programs.</p>
59 <li>URL references relative to the Referer: information.</li>
61 <li>Default <code><base></code> assignment through a new map
62 directive <code>base</code>.</li>
64 <li>No need for <code>imagemap.conf</code> file.</li>
66 <li>Point references.</li>
68 <li>Configurable generation of imagemap menus.</li>
72 <section id="imapfile"><title>Imagemap File</title>
74 <p>The lines in the imagemap files can have one of several
78 directive value [<var>x</var>,<var>y</var> ...]<br />
79 directive value "<var>Menu text</var>" [<var>x</var>,<var>y</var>
81 directive value <var>x</var>,<var>y</var> ... "<var>Menu text</var>"
84 <p>The directive is one of <code>base</code>,
85 <code>default</code>, <code>poly</code>, <code>circle</code>,
86 <code>rect</code>, or <code>point</code>. The value is an
87 absolute or relative URL, or one of the special values listed
88 below. The coordinates are <code><var>x</var>,<var>y</var></code>
89 pairs separated by whitespace. The quoted text is used as the text of
90 the link if a imagemap menu is generated. Lines beginning with '#' are
93 <section id="imapfile.directives"><title>Imagemap File Directives</title>
94 <p>There are six directives allowed in the imagemap file. The
95 directives can come in any order, but are processed in the
96 order they are found in the imagemap file.</p>
99 <dt><code>base</code> Directive</dt>
101 <dd><p>Has the effect of <code><base href="<var>value</var>">
102 </code>. The non-absolute URLs of the map-file are taken relative
103 to this value. The <code>base</code> directive overrides
104 <directive module="mod_imagemap">ImapBase</directive> as set in a
105 <code>.htaccess</code> file or in the server configuration files.
106 In the absence of an <directive>ImapBase</directive> configuration
107 directive, <code>base</code> defaults to
108 <code>http://server_name/</code>.</p>
109 <p><code>base_uri</code> is synonymous with <code>base</code>.
110 Note that a trailing slash on the URL is significant.</p></dd>
112 <dt><code>default</code> Directive</dt>
114 <dd>The action taken if the coordinates given do not fit any
115 of the <code>poly</code>, <code>circle</code> or
116 <code>rect</code> directives, and there are no
117 <code>point</code> directives. Defaults to <code>nocontent</code>
118 in the absence of an <directive module="mod_imagemap"
119 >ImapDefault</directive> configuration setting, causing a status
120 code of <code>204 No Content</code> to be returned. The client
121 should keep the same page displayed.</dd>
123 <dt><code>poly</code> Directive</dt>
125 <dd>Takes three to one-hundred points, and is obeyed if the
126 user selected coordinates fall within the polygon defined by
129 <dt><code>circle</code></dt>
131 <dd>Takes the center coordinates of a circle and a point on
132 the circle. Is obeyed if the user selected point is with the
135 <dt><code>rect</code> Directive</dt>
137 <dd>Takes the coordinates of two opposing corners of a
138 rectangle. Obeyed if the point selected is within this
141 <dt><code>point</code> Directive</dt>
143 <dd>Takes a single point. The point directive closest to the
144 user selected point is obeyed if no other directives are
145 satisfied. Note that <code>default</code> will not be
146 followed if a <code>point</code> directive is present and
147 valid coordinates are given.</dd>
151 <section id="imapfile.values"><title>Values</title>
153 <p>The values for each of the directives can be any of the
159 <dd><p>The URL can be relative or absolute URL. Relative URLs
160 can contain '..' syntax and will be resolved relative to the
161 <code>base</code> value.</p>
162 <p><code>base</code> itself will not be resolved according to the
163 current value. A statement <code>base mailto:</code> will
164 work properly, though.</p></dd>
166 <dt><code>map</code></dt>
168 <dd>Equivalent to the URL of the imagemap file itself. No
169 coordinates are sent with this, so a menu will be generated
170 unless <directive module="mod_imagemap">ImapMenu</directive> is set to
171 <code>none</code>.</dd>
173 <dt><code>menu</code></dt>
174 <dd>Synonymous with <code>map</code>.</dd>
176 <dt><code>referer</code></dt>
178 <dd>Equivalent to the URL of the referring document. Defaults
179 to <code>http://servername/</code> if no <code>Referer:</code>
180 header was present.</dd>
182 <dt><code>nocontent</code></dt>
184 <dd>Sends a status code of <code>204 No Content</code>,
185 telling the client to keep the same page displayed. Valid for
186 all but <code>base</code>.</dd>
188 <dt><code>error</code></dt>
190 <dd>Fails with a <code>500 Server Error</code>. Valid for all
191 but <code>base</code>, but sort of silly for anything but
192 <code>default</code>.</dd>
196 <section id="imapfile.coords"><title>Coordinates</title>
199 <dt><code>0,0 200,200</code></dt>
201 <dd>A coordinate consists of an <var>x</var> and a <var>y</var>
202 value separated by a comma. The coordinates are separated
203 from each other by whitespace. To accommodate the way Lynx
204 handles imagemaps, should a user select the coordinate
205 <code>0,0</code>, it is as if no coordinate had been
211 <section id="imapfile.quotedtext"><title>Quoted Text</title>
214 <dt><code>"<var>Menu Text</var>"</code></dt>
216 <dd><p>After the value or after the coordinates, the line
217 optionally may contain text within double quotes. This string
218 is used as the text for the link if a menu is
222 <a href="http://example.com/"><var>Menu text</var></a>
225 <p>If no quoted text is present, the name of the link will be
226 used as the text:</p>
229 <a href="http://example.com/">http://example.com</a>
232 <p>If you want to use double quotes within this text, you have to
233 write them as <code>&quot;</code>.</p></dd>
239 <section id="example"><title>Example Mapfile</title>
242 #Comments are printed in a 'formatted' or 'semiformatted' menu.<br />
243 #And can contain html tags. <hr><br />
245 poly map "Could I have a menu, please?" 0,0 0,10 10,10 10,0<br />
246 rect .. 0,0 77,27 "the directory of the referer"<br />
247 circle http://www.inetnebr.example.com/lincoln/feedback/ 195,0 305,27<br />
248 rect another_file "in same directory as referer" 306,0 419,27<br />
249 point http://www.zyzzyva.example.com/ 100,100<br />
250 point http://www.tripod.example.com/ 200,200<br />
251 rect mailto:nate@tripod.example.com 100,150 200,0 "Bugs?"<br />
256 <section id="referencing"><title>Referencing your mapfile</title>
258 <example><title>HTML example</title>
259 <a href="/maps/imagemap1.map"><br />
261 <img ismap src="/images/imagemap1.gif"><br />
266 <example><title>XHTML example</title>
267 <a href="/maps/imagemap1.map"><br />
269 <img ismap="ismap" src="/images/imagemap1.gif" /><br />
277 <name>ImapMenu</name>
278 <description>Action if no coordinates are given when calling
279 an imagemap</description>
280 <syntax>ImapMenu none|formatted|semiformatted|unformatted</syntax>
281 <contextlist><context>server config</context><context>virtual host</context>
282 <context>directory</context><context>.htaccess</context></contextlist>
283 <override>Indexes</override>
286 <p>The <directive>ImapMenu</directive> directive determines the
287 action taken if an imagemap file is called without valid
291 <dt><code>none</code></dt>
292 <dd>If ImapMenu is <code>none</code>, no menu is generated,
293 and the <code>default</code> action is performed.</dd>
295 <dt><code>formatted</code></dt>
296 <dd>A <code>formatted</code> menu is the simplest menu.
297 Comments in the imagemap file are ignored. A level one header
298 is printed, then an hrule, then the links each on a separate
299 line. The menu has a consistent, plain look close to that of
300 a directory listing.</dd>
302 <dt><code>semiformatted</code></dt>
303 <dd>In the <code>semiformatted</code> menu, comments are
304 printed where they occur in the imagemap file. Blank lines
305 are turned into HTML breaks. No header or hrule is printed,
306 but otherwise the menu is the same as a
307 <code>formatted</code> menu.</dd>
309 <dt><code>unformatted</code></dt>
310 <dd>Comments are printed, blank lines are ignored. Nothing is
311 printed that does not appear in the imagemap file. All breaks
312 and headers must be included as comments in the imagemap
313 file. This gives you the most flexibility over the appearance
314 of your menus, but requires you to treat your map files as
315 HTML instead of plaintext.</dd>
321 <name>ImapDefault</name>
322 <description>Default action when an imagemap is called with coordinates
323 that are not explicitly mapped</description>
324 <syntax>ImapDefault error|nocontent|map|referer|<var>URL</var></syntax>
325 <default>ImapDefault nocontent</default>
326 <contextlist><context>server config</context><context>virtual host</context>
327 <context>directory</context><context>.htaccess</context></contextlist>
328 <override>Indexes</override>
331 <p>The <directive>ImapDefault</directive> directive sets the default
332 <code>default</code> used in the imagemap files. Its value is
333 overridden by a <code>default</code> directive within the
334 imagemap file. If not present, the <code>default</code> action
335 is <code>nocontent</code>, which means that a <code>204 No
336 Content</code> is sent to the client. In this case, the client
337 should continue to display the original page.</p>
342 <name>ImapBase</name>
343 <description>Default <code>base</code> for imagemap files</description>
344 <syntax>ImapBase map|referer|<var>URL</var></syntax>
345 <default>ImapBase http://servername/</default>
346 <contextlist><context>server config</context><context>virtual host</context>
347 <context>directory</context><context>.htaccess</context></contextlist>
348 <override>Indexes</override>
351 <p>The <directive>ImapBase</directive> directive sets the default
352 <code>base</code> used in the imagemap files. Its value is
353 overridden by a <code>base</code> directive within the imagemap
354 file. If not present, the <code>base</code> defaults to
355 <code>http://<var>servername</var>/</code>.</p>
357 <seealso><directive module="core">UseCanonicalName</directive></seealso>