granicus.if.org Git - apache/blob - docs/manual/mod/mod_actions.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 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Copyright 2002-2005 The Apache Software Foundation or its licensors, as
   8  applicable.
   9
  10  Licensed under the Apache License, Version 2.0 (the "License");
  11  you may not use this file except in compliance with the License.
  12  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  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.
  21 -->
  22
  23 <modulesynopsis metafile="mod_actions.xml.meta">
  24
  25 <name>mod_actions</name>
  26
  27 <description>This module provides for executing CGI scripts based on
  28 media type or request method.</description>
  29
  30 <status>Base</status>
  31 <sourcefile>mod_actions.c</sourcefile>
  32 <identifier>actions_module</identifier>
  33
  34 <summary>
  35     <p>This module has two directives. The <directive
  36     module="mod_actions">Action</directive> directive lets you run CGI
  37     scripts whenever a file of a certain MIME content type is requested. The
  38     <directive module="mod_actions">Script</directive> directive lets
  39     you run CGI scripts whenever a particular method is used in a
  40     request. This makes it much easier to execute scripts that process
  41     files.</p>
  42 </summary>
  43
  44 <seealso><module>mod_cgi</module></seealso>
  45 <seealso><a href="../howto/cgi.html">Dynamic Content with CGI</a></seealso>
  46 <seealso><a href="../handler.html">Apache's Handler Use</a></seealso>
  47
  48 <directivesynopsis>
  49 <name>Action</name>
  50 <description>Activates a CGI script for a particular handler or
  51 content-type</description>
  52 <syntax>Action <var>action-type</var> <var>cgi-script</var> [virtual]</syntax>
  53 <contextlist>
  54 <context>server config</context><context>virtual host</context>
  55 <context>directory</context><context>.htaccess</context>
  56 </contextlist>
  57 <override>FileInfo</override>
  58 <compatibility>The <code>virtual</code> modifier and handler passing were
  59 introduced in Apache 2.1</compatibility>
  60
  61 <usage>
  62     <p>This directive adds an action, which will activate
  63     <var>cgi-script</var> when <var>action-type</var> is triggered by the
  64     request.  The <var>cgi-script</var> is the URL-path to a resource
  65     that has been designated as a CGI script using <directive
  66     module="mod_alias">ScriptAlias</directive> or <directive
  67     module="mod_mime">AddHandler</directive>.  The
  68     <var>action-type</var> can be either a <a
  69     href="../handler.html">handler</a> or a MIME content type. It
  70     sends the URL and file path of the requested document using the
  71     standard CGI <code>PATH_INFO</code> and <code>PATH_TRANSLATED</code>
  72     environment variables. The handler used for the particular request is
  73     passed using the <code>REDIRECT_HANDLER</code> variable.</p>
  74
  75     <example><title>Examples</title>
  76       # Requests for files of a particular MIME content type:<br />
  77       Action image/gif /cgi-bin/images.cgi<br />
  78       <br />
  79       # Files of a particular file extension<br />
  80       AddHandler my-file-type .xyz<br />
  81       Action my-file-type /cgi-bin/program.cgi<br />
  82     </example>
  83
  84     <p>In the first example, requests for files with a MIME content
  85     type of <code>image/gif</code> will be handled by the
  86     specified cgi script <code>/cgi-bin/images.cgi</code>.</p>
  87
  88     <p>In the second example, requests for files with a file extension of
  89     <code>.xyz</code> are handled by the specified cgi script
  90     <code>/cgi-bin/program.cgi</code>.</p>
  91
  92     <p>The optional <code>virtual</code> modifier turns off the check
  93     whether the requested file really exists. This is useful, for example,
  94     if you want to use the <directive>Action</directive> directive in
  95     virtual locations.</p>
  96
  97     <example><title>Example</title>
  98       &lt;Location /news&gt;<br />
  99       <indent>
 100         SetHandler news-handler<br />
 101         Action news-handler /cgi-bin/news.cgi virtual<br />
 102       </indent>
 103       &lt;/Location&gt;
 104     </example>
 105 </usage>
 106
 107 <seealso><directive module="mod_mime">AddHandler</directive></seealso>
 108 </directivesynopsis>
 109
 110 <directivesynopsis>
 111 <name>Script</name>
 112 <description>Activates a CGI script for a particular request
 113 method.</description>
 114 <syntax>Script <var>method</var> <var>cgi-script</var></syntax>
 115 <contextlist>
 116 <context>server config</context><context>virtual host</context>
 117 <context>directory</context></contextlist>
 118 <usage>
 119     <p>This directive adds an action, which will activate
 120     <var>cgi-script</var> when a file is requested using the method of
 121     <var>method</var>. The <var>cgi-script</var> is the URL-path to a
 122     resource that has been designated as a CGI script using <directive
 123     module="mod_alias">ScriptAlias</directive> or <directive
 124     module="mod_mime">AddHandler</directive>.  The URL and
 125     file path of the requested document is sent using the standard CGI
 126     <code>PATH_INFO</code> and <code>PATH_TRANSLATED</code> environment
 127     variables.</p>
 128
 129     <note>
 130       Any arbitrary method name may be used. <strong>Method names are
 131       case-sensitive</strong>, so <code>Script PUT</code> and
 132       <code>Script put</code> have two entirely different
 133       effects.
 134     </note>
 135
 136     <p>Note that the <directive>Script</directive> command defines default
 137     actions only. If a CGI script is called, or some other resource that is
 138     capable of handling the requested method internally, it will do
 139     so. Also note that <directive>Script</directive> with a method of
 140     <code>GET</code> will only be called if there are query arguments present
 141     (<em>e.g.</em>, foo.html?hi). Otherwise, the request will
 142     proceed normally.</p>
 143
 144     <example><title>Examples</title>
 145       # For &lt;ISINDEX&gt;-style searching<br />
 146       Script GET /cgi-bin/search<br />
 147       <br />
 148       # A CGI PUT handler<br />
 149       Script PUT /~bob/put.cgi<br />
 150     </example>
 151 </usage>
 152 </directivesynopsis>
 153
 154 </modulesynopsis>