granicus.if.org Git - apache/blob - docs/manual/mod/mod_negotiation.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <modulesynopsis>
   5
   6 <name>mod_negotiation</name>
   7 <description>Provides for <a
   8     href="../content-negotiation.html">content negotiation</a></description>
   9 <status>Base</status>
  10 <sourcefile>mod_negotiation.c</sourcefile>
  11 <identifier>negotiation_module</identifier>
  12
  13 <summary>
  14     <p>Content negotiation, or more accurately content selection, is
  15     the selection of the document that best matches the clients
  16     capabilities, from one of several available documents. There
  17     are two implementations of this.</p>
  18
  19     <ul>
  20       <li>A type map (a file with the handler
  21       <code>type-map</code>) which explicitly lists the files
  22       containing the variants.</li>
  23
  24       <li>A MultiViews search (enabled by the MultiViews <directive
  25       module="core">Options</directive>, where the server does an
  26       implicit filename pattern match, and choose from amongst the
  27       results.</li>
  28     </ul>
  29 </summary>
  30
  31 <seealso><directive module="mod_mime">DefaultLanguage</directive></seealso>
  32 <seealso><directive module="mod_mime">AddEncoding</directive></seealso>
  33 <seealso><directive module="mod_mime">AddLanguage</directive></seealso>
  34 <seealso><directive module="mod_mime">AddType</directive></seealso>
  35 <seealso><directive module="mod_mime">MultiViewsMatch</directive></seealso>
  36
  37 <section id="typemaps"><title>Type maps</title>
  38     <p>A type map has the same format as RFC822 mail headers. It
  39     contains document descriptions separated by blank lines, with
  40     lines beginning with a hash character ('#') treated as
  41     comments. A document description consists of several header
  42     records; records may be continued on multiple lines if the
  43     continuation lines start with spaces. The leading space will be
  44     deleted and the lines concatenated. A header record consists of
  45     a keyword name, which always ends in a colon, followed by a
  46     value. Whitespace is allowed between the header name and value,
  47     and between the tokens of value. The headers allowed are: </p>
  48
  49     <dl>
  50       <dt>Content-Encoding:</dt>
  51
  52       <dd>The encoding of the file. Apache only recognizes
  53       encodings that are defined by an <directive
  54       module="mod_mime">AddEncoding</directive> directive.
  55       This normally includes the encodings <code>x-compress</code>
  56       for compress'd files, and <code>x-gzip</code> for gzip'd
  57       files. The <code>x-</code> prefix is ignored for encoding
  58       comparisons.</dd>
  59
  60       <dt>Content-Language:</dt>
  61
  62       <dd>The language of the variant, as an Internet standard
  63       language tag (RFC 1766). An example is <code>en</code>,
  64       meaning English.</dd>
  65
  66       <dt>Content-Length:</dt>
  67
  68       <dd>The length of the file, in bytes. If this header is not
  69       present, then the actual length of the file is used.</dd>
  70
  71       <dt>Content-Type:</dt>
  72
  73       <dd>
  74         The MIME media type of the document, with optional
  75         parameters. Parameters are separated from the media type
  76         and from one another by a semi-colon, with a syntax of
  77         <code>name=value</code>. Common parameters include:
  78
  79         <dl>
  80           <dt>level</dt>
  81
  82           <dd>an integer specifying the version of the media type.
  83           For <code>text/html</code> this defaults to 2, otherwise
  84           0.</dd>
  85
  86           <dt>qs</dt>
  87
  88           <dd>a floating-point number with a value in the range 0.0
  89           to 1.0, indicating the relative 'quality' of this variant
  90           compared to the other available variants, independent of
  91           the client's capabilities. For example, a jpeg file is
  92           usually of higher source quality than an ascii file if it
  93           is attempting to represent a photograph. However, if the
  94           resource being represented is ascii art, then an ascii
  95           file would have a higher source quality than a jpeg file.
  96           All qs values are therefore specific to a given
  97           resource.</dd>
  98         </dl>
  99         Example:
 100
 101 <example>Content-Type: image/jpeg; qs=0.8</example>
 102       </dd>
 103
 104       <dt>URI:</dt>
 105
 106       <dd>uri of the file containing the variant (of the given
 107       media type, encoded with the given content encoding). These
 108       are interpreted as URLs relative to the map file; they must
 109       be on the same server (!), and they must refer to files to
 110       which the client would be granted access if they were to be
 111       requested directly.</dd>
 112
 113       <dt>Body:</dt>
 114
 115       <dd><p>New in Apache 2.0, the actual content of the resource may
 116       be included in the type-map file using the Body header.  This
 117       header must contain a string that designates a delimiter for
 118       the body content.  Then all following lines in the type map
 119       file will be considered part of the resource body until the
 120       delimiter string is found.</p>
 121
 122       <p>Example:</p>
 123 <example>
 124 Body:----xyz----<br />
 125 &lt;html&gt;<br />
 126 &lt;body&gt;<br />
 127 &lt;p&gt;Content of the page.&lt;/p&gt;<br />
 128 &lt;/body&gt;<br />
 129 &lt;/html&gt;<br />
 130 ----xyz----
 131 </example>
 132       </dd>
 133     </dl>
 134 </section>
 135
 136 <section><title>MultiViews</title>
 137
 138     <p>A MultiViews search is enabled by the MultiViews <directive
 139     module="core">Options</directive>. If the server receives a
 140     request for <code>/some/dir/foo</code> and
 141     <code>/some/dir/foo</code> does <em>not</em> exist, then the
 142     server reads the directory looking for all files named
 143     <code>foo.*</code>, and effectively fakes up a type map which
 144     names all those files, assigning them the same media types and
 145     content-encodings it would have if the client had asked for one
 146     of them by name. It then chooses the best match to the client's
 147     requirements, and returns that document.</p>
 148 </section>
 149
 150 <directivesynopsis>
 151 <name>CacheNegotiatedDocs</name>
 152 <description>Allows content-negotiated documents to be
 153 cached by proxy servers</description>
 154 <syntax>CacheNegotiatedDocs on|off</syntax>
 155 <default>CacheNegotiatedDocs off</default>
 156 <contextlist><context>server config</context></contextlist>
 157 <compatibility>The syntax changed in version 2.0.</compatibility>
 158
 159 <usage>
 160     <p>If set, this directive allows content-negotiated documents
 161     to be cached by proxy servers. This could mean that clients
 162     behind those proxys could retrieve versions of the documents
 163     that are not the best match for their abilities, but it will
 164     make caching more efficient.</p>
 165
 166     <p>This directive only applies to requests which come from
 167     HTTP/1.0 browsers. HTTP/1.1 provides much better control over
 168     the caching of negotiated documents, and this directive has no
 169     effect in responses to HTTP/1.1 requests.</p>
 170
 171     <p>Prior to version 2.0,
 172     <directive>CacheNegotiatedDocs</directive> did not take an
 173     argument; it was turned on by the presence of the directive by
 174     itself.</p>
 175 </usage>
 176 </directivesynopsis>
 177
 178 <directivesynopsis>
 179 <name>ForceLanguagePriority</name>
 180 <description>Action to take if a single acceptable document is not
 181 found</description>
 182 <syntax>ForceLanguagePriority None|Prefer|Fallback [Prefer|Fallback]</syntax>
 183 <default>ForceLanguagePriority None</default>
 184 <contextlist><context>server config</context>
 185 <context>virtual host</context>
 186 <context>directory</context>
 187 <context>.htaccess</context>
 188 </contextlist>
 189 <override>FileInfo</override>
 190 <compatibility>Available in version 2.0.30 and later</compatibility>
 191
 192 <usage>
 193     <p>The <directive>ForceLanguagePriority</directive> directive uses
 194     the given <directive
 195     module="mod_negotiation">LanguagePriority</directive> to satisfy
 196     negotation where the server could otherwise not return a single
 197     matching document.</p>
 198
 199     <p><code>ForceLanguagePriority Prefer</code> uses
 200     <code>LanguagePriority</code> to serve a one valid result, rather
 201     than returning an HTTP result 300 (MULTIPLE CHOICES) when there
 202     are several equally valid choices.  If the directives below were
 203     given, and the user's Accept-Language header assigned en and de
 204     each as quality .500 (equally acceptable) then then first matching
 205     variant, en, will be served.</p>
 206
 207 <example>
 208       LanguagePriority en fr de<br />
 209       ForceLanguagePriority Prefer
 210 </example>
 211
 212     <p><code>ForceLanguagePriority Fallback</code> uses
 213     <code>LanguagePriority</code> to serve a valid result, rather than
 214     returning an HTTP result 406 (NOT ACCEPTABLE).  If the directives
 215     below were given, and the user's Accept-Language only permitted an
 216     es language response, but such a variant isn't found, then the
 217     first variant from the LanguagePriority list below will be
 218     served.</p>
 219
 220 <example>
 221       LanguagePriority en fr de<br />
 222       ForceLanguagePriority Fallback
 223 </example>
 224
 225     <p>Both options, Prefer and Fallback, may be specified, so either the
 226     first matching variant from LanguagePriority will be served if more
 227     that one variant is acceptable, or first available document will be
 228     served if none of the variants matched the client's acceptable list of
 229     languages.</p>
 230 </usage>
 231 </directivesynopsis>
 232
 233 <directivesynopsis>
 234 <name>LanguagePriority</name>
 235 <description>The precendence of language variants for cases where
 236 the client does not express a preference</description>
 237 <syntax>LanguagePriority <em>MIME-lang</em> [<em>MIME-lang</em>] ...</syntax>
 238 <contextlist><context>server config</context>
 239 <context>virtual host</context>
 240 <context>directory</context>
 241 <context>.htaccess</context>
 242 </contextlist>
 243 <override>FileInfo</override>
 244
 245 <usage>
 246     <p>The <directive>LanguagePriority</directive> sets the precedence
 247     of language variants for the case where the client does not
 248     express a preference, when handling a MultiViews request. The list
 249     of <em>MIME-lang</em> are in order of decreasing preference.
 250     Example:</p>
 251
 252 <example>LanguagePriority en fr de</example>
 253
 254     <p>For a request for <code>foo.html</code>, where
 255     <code>foo.html.fr</code> and <code>foo.html.de</code> both
 256     existed, but the browser did not express a language preference,
 257     then <code>foo.html.fr</code> would be returned.</p>
 258
 259     <p>Note that this directive only has an effect if a 'best'
 260     language cannot be determined by any other means or the <directive
 261     module="mod_negotiation">ForceLanguagePriority</directive> directive
 262     is not <code>None</code>. Correctly implemented HTTP/1.1 requests
 263     will mean this directive has no effect.</p>
 264 </usage>
 265 </directivesynopsis>
 266
 267 </modulesynopsis>