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  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
  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 <glossary
  38     ref="mime-type">MIME content type</glossary> is requested. The
  39     <directive module="mod_actions">Script</directive> directive lets
  40     you run CGI scripts whenever a particular method is used in a
  41     request. This makes it much easier to execute scripts that process
  42     files.</p> </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 httpd'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
  64     the request.  The <var>cgi-script</var> is the URL-path to a
  65     resource 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 <glossary
  70     ref="mime-type">MIME content type</glossary>. It sends the URL and
  71     file path of the requested document using the standard CGI
  72     <code>PATH_INFO</code> and <code>PATH_TRANSLATED</code>
  73     environment variables. The handler used for the particular request
  74     is passed using the <code>REDIRECT_HANDLER</code> variable.</p>
  75
  76     <example><title>Example: MIME type</title>
  77       # Requests for files of a particular MIME content type:<br />
  78       Action image/gif /cgi-bin/images.cgi<br />
  79       <br />
  80     </example>
  81
  82     <p>In this 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     <example><title>Example: File extension</title>
  87       # Files of a particular file extension<br />
  88       AddHandler my-file-type .xyz<br />
  89       Action my-file-type /cgi-bin/program.cgi<br />
  90     </example>
  91
  92     <p>In this example, requests for files with a file extension of
  93     <code>.xyz</code> are handled by the specified cgi script
  94     <code>/cgi-bin/program.cgi</code>.</p>
  95
  96     <p>The optional <code>virtual</code> modifier turns off the check
  97     whether the requested file really exists. This is useful, for example,
  98     if you want to use the <directive>Action</directive> directive in
  99     virtual locations.</p>
 100
 101     <example><title>Example</title>
 102       &lt;Location /news&gt;<br />
 103       <indent>
 104         SetHandler news-handler<br />
 105         Action news-handler /cgi-bin/news.cgi virtual<br />
 106       </indent>
 107       &lt;/Location&gt;
 108     </example>
 109 </usage>
 110
 111 <seealso><directive module="mod_mime">AddHandler</directive></seealso>
 112 </directivesynopsis>
 113
 114 <directivesynopsis>
 115 <name>Script</name>
 116 <description>Activates a CGI script for a particular request
 117 method.</description>
 118 <syntax>Script <var>method</var> <var>cgi-script</var></syntax>
 119 <contextlist>
 120 <context>server config</context><context>virtual host</context>
 121 <context>directory</context></contextlist>
 122 <usage>
 123     <p>This directive adds an action, which will activate
 124     <var>cgi-script</var> when a file is requested using the method of
 125     <var>method</var>. The <var>cgi-script</var> is the URL-path to a
 126     resource that has been designated as a CGI script using <directive
 127     module="mod_alias">ScriptAlias</directive> or <directive
 128     module="mod_mime">AddHandler</directive>.  The URL and
 129     file path of the requested document is sent using the standard CGI
 130     <code>PATH_INFO</code> and <code>PATH_TRANSLATED</code> environment
 131     variables.</p>
 132
 133     <note>
 134       Any arbitrary method name may be used. <strong>Method names are
 135       case-sensitive</strong>, so <code>Script PUT</code> and
 136       <code>Script put</code> have two entirely different
 137       effects.
 138     </note>
 139
 140     <p>Note that the <directive>Script</directive> command defines default
 141     actions only. If a CGI script is called, or some other resource that is
 142     capable of handling the requested method internally, it will do
 143     so. Also note that <directive>Script</directive> with a method of
 144     <code>GET</code> will only be called if there are query arguments present
 145     (<em>e.g.</em>, foo.html?hi). Otherwise, the request will
 146     proceed normally.</p>
 147
 148     <example><title>Examples</title>
 149       # All GET requests go here<br />
 150       Script GET /cgi-bin/search<br />
 151       <br />
 152       # A CGI PUT handler<br />
 153       Script PUT /~bob/put.cgi<br />
 154     </example>
 155 </usage>
 156 </directivesynopsis>
 157
 158 </modulesynopsis>