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>Execute CGI scripts based on media type or request method.</description>
  28
  29 <status>Base</status>
  30 <sourcefile>mod_actions.c</sourcefile>
  31 <identifier>actions_module</identifier>
  32
  33 <summary>
  34     <p>This module has two directives. The <directive
  35     module="mod_actions">Action</directive> directive lets you run CGI
  36     scripts whenever a file of a certain <glossary
  37     ref="mime-type">MIME content type</glossary> 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> </summary>
  42
  43 <seealso><module>mod_cgi</module></seealso>
  44 <seealso><a href="../howto/cgi.html">Dynamic Content with CGI</a></seealso>
  45 <seealso><a href="../handler.html">Apache httpd's Handler Use</a></seealso>
  46
  47 <directivesynopsis>
  48 <name>Action</name>
  49 <description>Activates a CGI script for a particular handler or
  50 content-type</description>
  51 <syntax>Action <var>action-type</var> <var>cgi-script</var> [virtual]</syntax>
  52 <contextlist>
  53 <context>server config</context><context>virtual host</context>
  54 <context>directory</context><context>.htaccess</context>
  55 </contextlist>
  56 <override>FileInfo</override>
  57
  58 <usage>
  59     <p>This directive adds an action, which will activate
  60     <var>cgi-script</var> when <var>action-type</var> is triggered by
  61     the request.  The <var>cgi-script</var> is the URL-path to a
  62     resource that has been designated as a CGI script using <directive
  63     module="mod_alias">ScriptAlias</directive> or <directive
  64     module="mod_mime">AddHandler</directive>.  The
  65     <var>action-type</var> can be either a <a
  66     href="../handler.html">handler</a> or a <glossary
  67     ref="mime-type">MIME content type</glossary>. It sends the URL and
  68     file path of the requested document using the standard CGI
  69     <code>PATH_INFO</code> and <code>PATH_TRANSLATED</code>
  70     environment variables. The handler used for the particular request
  71     is passed using the <code>REDIRECT_HANDLER</code> variable.</p>
  72
  73     <example><title>Example: MIME type</title>
  74     <highlight language="config">
  75 # Requests for files of a particular MIME content type:
  76 Action image/gif /cgi-bin/images.cgi
  77     </highlight>
  78     </example>
  79
  80     <p>In this example, requests for files with a MIME content
  81     type of <code>image/gif</code> will be handled by the
  82     specified cgi script <code>/cgi-bin/images.cgi</code>.</p>
  83
  84     <example>
  85         <title>Example: File extension</title>
  86     <highlight language="config">
  87 # Files of a particular file extension
  88 AddHandler my-file-type .xyz
  89 Action my-file-type /cgi-bin/program.cgi
  90     </highlight>
  91     </example>
  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     <highlight language="config">
 102 &lt;Location /news&gt;
 103     SetHandler news-handler
 104     Action news-handler /cgi-bin/news.cgi virtual
 105 &lt;/Location&gt;
 106     </highlight>
 107 </usage>
 108
 109 <seealso><directive module="mod_mime">AddHandler</directive></seealso>
 110 </directivesynopsis>
 111
 112 <directivesynopsis>
 113 <name>Script</name>
 114 <description>Activates a CGI script for a particular request
 115 method.</description>
 116 <syntax>Script <var>method</var> <var>cgi-script</var></syntax>
 117 <contextlist>
 118 <context>server config</context><context>virtual host</context>
 119 <context>directory</context></contextlist>
 120 <usage>
 121     <p>This directive adds an action, which will activate
 122     <var>cgi-script</var> when a file is requested using the method of
 123     <var>method</var>. The <var>cgi-script</var> is the URL-path to a
 124     resource that has been designated as a CGI script using <directive
 125     module="mod_alias">ScriptAlias</directive> or <directive
 126     module="mod_mime">AddHandler</directive>.  The URL and
 127     file path of the requested document is sent using the standard CGI
 128     <code>PATH_INFO</code> and <code>PATH_TRANSLATED</code> environment
 129     variables.</p>
 130
 131     <note>
 132       Any arbitrary method name may be used. <strong>Method names are
 133       case-sensitive</strong>, so <code>Script PUT</code> and
 134       <code>Script put</code> have two entirely different
 135       effects.
 136     </note>
 137
 138     <p>Note that the <directive>Script</directive> command defines default
 139     actions only. If a CGI script is called, or some other resource that is
 140     capable of handling the requested method internally, it will do
 141     so. Also note that <directive>Script</directive> with a method of
 142     <code>GET</code> will only be called if there are query arguments present
 143     (<em>e.g.</em>, foo.html?hi). Otherwise, the request will
 144     proceed normally.</p>
 145
 146     <highlight language="config">
 147 # All GET requests go here
 148 Script GET /cgi-bin/search
 149
 150 # A CGI PUT handler
 151 Script PUT /~bob/put.cgi
 152     </highlight>
 153 </usage>
 154 </directivesynopsis>
 155
 156 </modulesynopsis>