<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>

<!--
 Copyright 2002-2004 The Apache Software Foundation

 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->

<modulesynopsis metafile="mod_actions.xml.meta">

<name>mod_actions</name> 

<description>This module provides for executing CGI scripts based on
media type or request method.</description>

<status>Base</status>
<sourcefile>mod_actions.c</sourcefile>
<identifier>actions_module</identifier>

<summary>
    <p>This module has two directives. The <directive
    module="mod_actions">Action</directive> directive lets you run CGI
    scripts whenever a file of a certain type is requested. The
    <directive module="mod_actions">Script</directive> directive lets
    you run CGI scripts whenever a particular method is used in a
    request. This makes it much easier to execute scripts that process
    files.</p>
</summary>

<seealso><module>mod_cgi</module></seealso>
<seealso><a href="../howto/cgi.html">Dynamic Content with CGI</a></seealso>
<seealso><a href="../handler.html">Apache's Handler Use</a></seealso>

<directivesynopsis>
<name>Action</name>
<description>Activates a CGI script for a particular handler or
content-type</description>
<syntax>Action <var>action-type</var> <var>cgi-script</var></syntax>
<contextlist>
<context>server config</context><context>virtual host</context>
<context>directory</context><context>.htaccess</context>
</contextlist>
<override>FileInfo</override>

<usage>
    <p>This directive adds an action, which will activate
    <var>cgi-script</var> when <var>action-type</var> is triggered by the
    request.  The <var>cgi-script</var> is the URL-path to a resource
    that has been designated as a CGI script using <directive
    module="mod_alias">ScriptAlias</directive> or <directive
    module="mod_mime">AddHandler</directive>.  The
    <var>action-type</var> can be either a <a
    href="../handler.html">handler</a> or a MIME content type. It
    sends the URL and file path of the requested document using the
    standard CGI PATH_INFO and PATH_TRANSLATED environment
    variables.</p>

    <example><title>Examples</title>
      # Requests for files of a particular type:<br />
      Action image/gif /cgi-bin/images.cgi<br />
      <br />
      # Files of a particular file extension<br />
      AddHandler my-file-type .xyz<br />
      Action my-file-type /cgi-bin/program.cgi<br />
    </example>

    <p>In the first example, requests for files with a MIME content
    type of <code>image/gif</code> will instead be handled by the
    specified cgi script <code>/cgi-bin/images.cgi</code>.</p>

    <p>In the second example, requests for files with a file extension of
    <code>.xyz</code> are handled instead by the specified cgi script 
    <code>/cgi-bin/program.cgi</code>.</p>
</usage>

<seealso><directive module="mod_mime">AddHandler</directive></seealso>
</directivesynopsis>

<directivesynopsis>
<name>Script</name>
<description>Activates a CGI script for a particular request
method.</description>
<syntax>Script <var>method</var> <var>cgi-script</var></syntax>
<contextlist>
<context>server config</context><context>virtual host</context>
<context>directory</context></contextlist>
<usage>
    <p>This directive adds an action, which will activate
    <var>cgi-script</var> when a file is requested using the method of
    <var>method</var>. The <var>cgi-script</var> is the URL-path to a
    resource that has been designated as a CGI script using <directive
    module="mod_alias">ScriptAlias</directive> or <directive
    module="mod_mime">AddHandler</directive>.  The URL and
    file path of the requested document is sent using the standard CGI
    PATH_INFO and PATH_TRANSLATED environment variables.</p>

    <note>
      Any arbitrary method name may be used. <strong>Method names are
      case-sensitive</strong>, so <code>Script PUT</code> and
      <code>Script put</code> have two entirely different
      effects.
    </note>

    <p>Note that the Script command defines default actions only.
    If a CGI script is called, or some other resource that is
    capable of handling the requested method internally, it will do
    so. Also note that Script with a method of <code>GET</code>
    will only be called if there are query arguments present
    (<em>e.g.</em>, foo.html?hi). Otherwise, the request will
    proceed normally.</p>

    <example><title>Examples</title>
      # For &lt;ISINDEX&gt;-style searching<br />
      Script GET /cgi-bin/search<br />
      <br />
      # A CGI PUT handler<br />
      Script PUT /~bob/put.cgi<br />
    </example>
</usage>
</directivesynopsis>

</modulesynopsis>
