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