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