1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3 4<html xmlns="http://www.w3.org/1999/xhtml"> 5 <head> 6 <meta name="generator" content="HTML Tidy, see www.w3.org" /> 7 8 <title>Apache module mod_imap</title> 9 </head> 10 <!-- Background white, links blue (unvisited), navy (visited), red (active) --> 11 12 <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" 13 vlink="#000080" alink="#FF0000"> 14 <div align="CENTER"> 15 <img src="../images/sub.gif" alt="[APACHE DOCUMENTATION]" /> 16 17 <h3>Apache HTTP Server Version 1.3</h3> 18 </div> 19 20 21 <h1 align="CENTER">Module mod_imap</h1> 22 23 <p>This module provides for server-side imagemap 24 processing.</p> 25 26 <p><a href="module-dict.html#Status" 27 rel="Help"><strong>Status:</strong></a> Base<br /> 28 <a href="module-dict.html#SourceFile" 29 rel="Help"><strong>Source File:</strong></a> mod_imap.c<br /> 30 <a href="module-dict.html#ModuleIdentifier" 31 rel="Help"><strong>Module Identifier:</strong></a> 32 imap_module<br /> 33 <a href="module-dict.html#Compatibility" 34 rel="Help"><strong>Compatibility:</strong></a> Available in 35 Apache 1.1 and later.</p> 36 37 <h2>Summary</h2> 38 39 <p>This module processes <code>.map</code> files, thereby 40 replacing the functionality of the <code>imagemap</code> CGI 41 program. Any directory or document type configured to use the 42 handler <code>imap-file</code> (using either <code><a 43 href="mod_mime.html#addhandler">AddHandler</a></code> or 44 <code><a href="mod_mime.html#sethandler">SetHandler</a></code>) 45 will be processed by this module.</p> 46 47 <p>The following directive will activate files ending with 48 <code>.map</code> as imagemap files:</p> 49 50 <blockquote> 51 <code>AddHandler imap-file map</code> 52 </blockquote> 53 Note that the following is still supported: 54 55 <blockquote> 56 <code>AddType application/x-httpd-imap map</code> 57 </blockquote> 58 However, we are trying to phase out "magic MIME types" so we 59 are deprecating this method. 60 61 <h2>Directives</h2> 62 63 <ul> 64 <li><a href="#imapmenu">ImapMenu</a></li> 65 66 <li><a href="#imapdefault">ImapDefault</a></li> 67 68 <li><a href="#imapbase">ImapBase</a></li> 69 </ul> 70 71 <h2>New Features</h2> 72 The imagemap module adds some new features that were not 73 possible with previously distributed imagemap programs. 74 75 <ul> 76 <li>URL references relative to the Referer: information.</li> 77 78 <li>Default <BASE> assignment through a new map 79 directive <code>base</code>.</li> 80 81 <li>No need for <code>imagemap.conf</code> file.</li> 82 83 <li>Point references.</li> 84 85 <li>Configurable generation of imagemap menus.</li> 86 </ul> 87 88 <h2>Imagemap File</h2> 89 The lines in the imagemap files can have one of several 90 formats: 91 92 <blockquote> 93 <code>directive value [x,y ...]</code><br /> 94 <code>directive value "Menu text" [x,y ...]</code><br /> 95 <code>directive value x,y ... "Menu text"</code><br /> 96 </blockquote> 97 The directive is one of <code>base</code>, 98 <code>default</code>, <code>poly</code>, <code>circle</code>, 99 <code>rect</code>, or <code>point</code>. The value is an 100 absolute or relative URL, or one of the special values listed 101 below. The coordinates are <code>x,y</code> pairs separated by 102 whitespace. The quoted text is used as the text of the link if 103 a imagemap menu is generated. Lines beginning with '#' are 104 comments. 105 106 <h3>Imagemap File Directives</h3> 107 There are six directives allowed in the imagemap file. The 108 directives can come in any order, but are processed in the 109 order they are found in the imagemap file. 110 111 <dl> 112 <dt><code>base</code> Directive</dt> 113 114 <dd>Has the effect of <code><BASE HREF="value"></code>. 115 The non-absolute URLs of the map-file are taken relative to 116 this value. The <code>base</code> directive overrides 117 ImapBase as set in a .htaccess file or in the server 118 configuration files. In the absence of an ImapBase 119 configuration directive, <code>base</code> defaults to 120 <code>http://server_name/</code>.<br /> 121 <code>base_uri</code> is synonymous with <code>base</code>. 122 Note that a trailing slash on the URL is significant.</dd> 123 124 <dt><code>default</code> Directive</dt> 125 126 <dd>The action taken if the coordinates given do not fit any 127 of the <code>poly</code>, <code>circle</code> or 128 <code>rect</code> directives, and there are no 129 <code>point</code> directives. Defaults to 130 <code>nocontent</code> in the absence of an ImapDefault 131 configuration setting, causing a status code of <code>204 No 132 Content</code> to be returned. The client should keep the 133 same page displayed.</dd> 134 135 <dt><code>poly</code> Directive</dt> 136 137 <dd>Takes three to one-hundred points, and is obeyed if the 138 user selected coordinates fall within the polygon defined by 139 these points.</dd> 140 141 <dt><code>circle</code></dt> 142 143 <dd>Takes the center coordinates of a circle and a point on 144 the circle. Is obeyed if the user selected point is with the 145 circle.</dd> 146 147 <dt><code>rect</code> Directive</dt> 148 149 <dd>Takes the coordinates of two opposing corners of a 150 rectangle. Obeyed if the point selected is within this 151 rectangle.</dd> 152 153 <dt><code>point</code> Directive</dt> 154 155 <dd>Takes a single point. The point directive closest to the 156 user selected point is obeyed if no other directives are 157 satisfied. Note that <code>default</code> will not be 158 followed if a <code>point</code> directive is present and 159 valid coordinates are given.</dd> 160 </dl> 161 162 <h3>Values</h3> 163 The values for each of the directives can any of the following: 164 165 166 <dl> 167 <dt>a URL</dt> 168 169 <dd>The URL can be relative or absolute URL. Relative URLs 170 can contain '..' syntax and will be resolved relative to the 171 <code>base</code> value.<br /> 172 <code>base</code> itself will not resolved according to the 173 current value. A statement <code>base mailto:</code> will 174 work properly, though.</dd> 175 176 <dt><code>map</code></dt> 177 178 <dd>Equivalent to the URL of the imagemap file itself. No 179 coordinates are sent with this, so a menu will be generated 180 unless ImapMenu is set to 'none'.</dd> 181 182 <dt><code>menu</code></dt> 183 184 <dd>Synonymous with <code>map</code>.</dd> 185 186 <dt><code>referer</code></dt> 187 188 <dd>Equivalent to the URL of the referring document. Defaults 189 to <code>http://servername/</code> if no Referer: header was 190 present.</dd> 191 192 <dt><code>nocontent</code></dt> 193 194 <dd>Sends a status code of <code>204 No Content</code>, 195 telling the client to keep the same page displayed. Valid for 196 all but <code>base</code>.</dd> 197 198 <dt><code>error</code></dt> 199 200 <dd>Fails with a <code>500 Server Error</code>. Valid for all 201 but <code>base</code>, but sort of silly for anything but 202 <code>default</code>.</dd> 203 </dl> 204 205 <h3>Coordinates</h3> 206 207 <dl> 208 <dt><code>0,0 200,200</code></dt> 209 210 <dd>A coordinate consists of an <tt>x</tt> and a <tt>y</tt> 211 value separated by a comma. The coordinates are separated 212 from each other by whitespace. To accommodate the way Lynx 213 handles imagemaps, should a user select the coordinate 214 <code>0,0</code>, it is as if no coordinate had been 215 selected.</dd> 216 </dl> 217 218 <h3>Quoted Text</h3> 219 220 <dl> 221 <dt><code>"Menu Text"</code></dt> 222 223 <dd>After the value or after the coordinates, the line 224 optionally may contain text within double quotes. This string 225 is used as the text for the link if a menu is 226 generated:<br /> 227 <code><a HREF="http://foo.com/">Menu 228 text</a></code><br /> 229 If no quoted text is present, the name of the link will be 230 used as the text:<br /> 231 <code><a 232 HREF="http://foo.com/">http://foo.com</a></code><br /> 233 If you want to use double quotes within this text, you have to 234 write them as <code>&quot;</code>.</dd> 235 </dl> 236 237 <h2>Example Mapfile</h2> 238 239 <blockquote> 240 <code>#Comments are printed in a 'formatted' or 241 'semiformatted' menu.<br /> 242 #And can contain html tags. <hr><br /> 243 base referer<br /> 244 poly map "Could I have a menu, please?" 0,0 0,10 10,10 245 10,0<br /> 246 rect .. 0,0 77,27 "the directory of the referer"<br /> 247 circle http://www.inetnebr.com/lincoln/feedback/ 195,0 248 305,27<br /> 249 rect another_file "in same directory as referer" 306,0 250 419,27<br /> 251 point http://www.zyzzyva.com/ 100,100<br /> 252 point http://www.tripod.com/ 200,200<br /> 253 rect mailto:nate@tripod.com 100,150 200,0 "Bugs?"<br /> 254 </code> 255 </blockquote> 256 257 <h2>Referencing your mapfile</h2> 258 259 <blockquote> 260 <code><A HREF="/maps/imagemap1.map"><br /> 261 <IMG ISMAP SRC="/images/imagemap1.gif"><br /> 262 </A></code> 263 </blockquote> 264 <hr /> 265 266 <h2><a id="imapmenu" name="imapmenu">ImapMenu</a> 267 directive</h2> 268 <a href="directive-dict.html#Syntax" 269 rel="Help"><strong>Syntax:</strong></a> ImapMenu 270 none|formatted|semiformatted|unformatted<br /> 271 <a href="directive-dict.html#Context" 272 rel="Help"><strong>Context:</strong></a> server config, virtual 273 host, directory, .htaccess<br /> 274 <a href="directive-dict.html#Override" 275 rel="Help"><strong>Override:</strong></a> Indexes<br /> 276 <a href="directive-dict.html#Module" 277 rel="Help"><strong>Module:</strong></a> mod_imap<br /> 278 <a href="directive-dict.html#Compatibility" 279 rel="Help"><strong>Compatibility:</strong></a> ImapMenu is only 280 available in Apache 1.1 and later. 281 282 <p>The ImapMenu directive determines the action taken if an 283 imagemap file is called without valid coordinates.</p> 284 285 <dl> 286 <dt><code>none</code></dt> 287 288 <dd>If ImapMenu is <code>none</code>, no menu is generated, 289 and the <code>default</code> action is performed.</dd> 290 291 <dt><code>formatted</code></dt> 292 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> 298 299 <dt><code>semiformatted</code></dt> 300 301 <dd>In the <code>semiformatted</code> menu, comments are 302 printed where they occur in the imagemap file. Blank lines 303 are turned into HTML breaks. No header or hrule is printed, 304 but otherwise the menu is the same as a 305 <code>formatted</code> menu.</dd> 306 307 <dt><code>unformatted</code></dt> 308 309 <dd>Comments are printed, blank lines are ignored. Nothing is 310 printed that does not appear in the imagemap file. All breaks 311 and headers must be included as comments in the imagemap 312 file. This gives you the most flexibility over the appearance 313 of your menus, but requires you to treat your map files as 314 HTML instead of plaintext.</dd> 315 </dl> 316 <hr /> 317 318 <h2><a id="imapdefault" name="imapdefault">ImapDefault</a> 319 directive</h2> 320 <a href="directive-dict.html#Syntax" 321 rel="Help"><strong>Syntax:</strong></a> ImapDefault 322 error|nocontent|map|referer|<em>URL</em><br /> 323 <a href="directive-dict.html#Context" 324 rel="Help"><strong>Context:</strong></a> server config, virtual 325 host, directory, .htaccess<br /> 326 <a href="directive-dict.html#Override" 327 rel="Help"><strong>Override:</strong></a> Indexes<br /> 328 <a href="directive-dict.html#Module" 329 rel="Help"><strong>Module:</strong></a> mod_imap<br /> 330 <a href="directive-dict.html#Compatibility" 331 rel="Help"><strong>Compatibility:</strong></a> ImapDefault is 332 only available in Apache 1.1 and later. 333 334 <p>The ImapDefault directive sets the default 335 <code>default</code> used in the imagemap files. Its value is 336 overridden by a <code>default</code> directive within the 337 imagemap file. If not present, the <code>default</code> action 338 is <code>nocontent</code>, which means that a <code>204 No 339 Content</code> is sent to the client. In this case, the client 340 should continue to display the original page.</p> 341 <hr /> 342 343 <h2><a id="imapbase" name="imapbase">ImapBase</a> 344 directive</h2> 345 <a href="directive-dict.html#Syntax" 346 rel="Help"><strong>Syntax:</strong></a> ImapBase 347 map|referer|<em>URL</em><br /> 348 <a href="directive-dict.html#Context" 349 rel="Help"><strong>Context:</strong></a> server config, virtual 350 host, directory, .htaccess<br /> 351 <a href="directive-dict.html#Override" 352 rel="Help"><strong>Override:</strong></a> Indexes<br /> 353 <a href="directive-dict.html#Module" 354 rel="Help"><strong>Module:</strong></a> mod_imap<br /> 355 <a href="directive-dict.html#Compatibility" 356 rel="Help"><strong>Compatibility:</strong></a> ImapBase is only 357 available in Apache 1.1 and later. 358 359 <p>The ImapBase directive sets the default <code>base</code> 360 used in the imagemap files. Its value is overridden by a 361 <code>base</code> directive within the imagemap file. If not 362 present, the <code>base</code> defaults to 363 <code>http://servername/</code>. 364 <hr /> 365 366 <h3 align="CENTER">Apache HTTP Server Version 1.3</h3> 367 <a href="./"><img src="../images/index.gif" alt="Index" /></a> 368 <a href="../"><img src="../images/home.gif" alt="Home" /></a> 369 370 </p> 371 </body> 372</html> 373 374
