The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>HTML::Mason::ApacheHandler - Mason/mod_perl interface</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:autarch@houseabsolute.urth.org" />
</head>

<body style="background-color: white">


<!-- INDEX BEGIN -->
<div name="index">
<p><A NAME="__index__"></a></p>

<ul>

	<li><A HREF="#name">NAME</a></li>
	<li><A HREF="#synopsis">SYNOPSIS</a></li>
	<li><A HREF="#description">DESCRIPTION</a></li>
	<li><A HREF="#parameters_to_the_new___construc">PARAMETERS TO THE <code>new()</code> CONSTRUCTOR</a></li>
	<li><A HREF="#accessor_methods">ACCESSOR METHODS</a></li>
	<li><A HREF="#other_methods">OTHER METHODS</a></li>
	<li><A HREF="#see_also">SEE ALSO</a></li>
</ul>

<hr name="index" />
</div>
<!-- INDEX END -->

<p>
</p>
<h1><A NAME="name">NAME</a></h1>
<p>HTML::Mason::ApacheHandler - Mason/mod_perl interface</p>
<p>
</p>
<hr />
<h1><A NAME="synopsis">SYNOPSIS</a></h1>
<pre>
    use HTML::Mason::ApacheHandler;</pre>
<pre>
    my $ah = HTML::Mason::ApacheHandler-&gt;new (..name/value params..);
    ...
    sub handler {
        my $r = shift;
        $ah-&gt;handle_request($r);
    }</pre>
<p>
</p>
<hr />
<h1><A NAME="description">DESCRIPTION</a></h1>
<p>The ApacheHandler object links Mason to mod_perl (version 1 or 2),
running components in response to HTTP requests. It is controlled
primarily through parameters to the <code>new()</code> constructor.</p>
<p>
</p>
<hr />
<h1><A NAME="parameters_to_the_new___construc">PARAMETERS TO THE <code>new()</code> CONSTRUCTOR</a></h1>
<dl>
<dt><strong><A NAME="apache_status_title" class="item">apache_status_title</a></strong></dt>

<dd>
<p>Title that you want this ApacheHandler to appear as under
Apache::Status.  Default is &quot;HTML::Mason status&quot;.  This is useful if
you create more than one ApacheHandler object and want them all
visible via Apache::Status.</p>
</dd>
<dt><strong><A NAME="args_method" class="item">args_method</a></strong></dt>

<dd>
<p>Method to use for unpacking GET and POST arguments. The valid options
are 'CGI' and 'mod_perl'; these indicate that a <code>CGI.pm</code> or
<code>Apache::Request</code> object (respectively) will be created for the
purposes of argument handling.</p>
<p>'mod_perl' is the default under mod_perl-1 and requires that you have 
installed the <code>Apache::Request</code> package.  Under mod_perl-2, the default
is 'CGI' because <code>Apache2::Request</code> is still in development.</p>
<p>If args_method is 'mod_perl', the <code>$r</code> global is upgraded to an
Apache::Request object. This object inherits all Apache methods and
adds a few of its own, dealing with parameters and file uploads.  See
<code>Apache::Request</code> for more information.</p>
<p>If the args_method is 'CGI', the Mason request object (<code>$m</code>) will have a
method called <code>cgi_object</code> available.  This method returns the CGI
object used for argument processing.</p>
<p>While Mason will load <code>Apache::Request</code> or <code>CGI</code> as needed at runtime, it
is recommended that you preload the relevant module either in your
<em class="file">httpd.conf</em> or <em class="file">handler.pl</em> file, as this will save some memory.</p>
</dd>
<dt><strong><A NAME="decline_dirs" class="item">decline_dirs</a></strong></dt>

<dd>
<p>True or false, default is true. Indicates whether Mason should decline
directory requests, leaving Apache to serve up a directory index or a
<code>FORBIDDEN</code> error as appropriate. See the <A HREF="Admin.html#allowing_directory_requests">allowing directory requests</a> section of the administrator's manual
for more information about handling directories with Mason.</p>
</dd>
<dt><strong><A NAME="interp" class="item">interp</a></strong></dt>

<dd>
<p>The interpreter object to associate with this compiler. By default a
new object of the specified <A HREF="Params.html#interp_class">interp_class</a> will be created.</p>
</dd>
<dt><strong><A NAME="interp_class" class="item">interp_class</a></strong></dt>

<dd>
<p>The class to use when creating a interpreter. Defaults to
<a HREF="Interp.html">HTML::Mason::Interp</a>.</p>
</dd>
</dl>
<p>
</p>
<hr />
<h1><A NAME="accessor_methods">ACCESSOR METHODS</a></h1>
<p>All of the above properties, except interp_class, have standard accessor
methods of the same name: no arguments retrieves the value, and one
argument sets it, except for args_method, which is not settable.  For
example:</p>
<pre>
    my $ah = HTML::Mason::ApacheHandler-&gt;new;
    my $decline_dirs = $ah-&gt;decline_dirs;
    $ah-&gt;decline_dirs(1);</pre>
<p>
</p>
<hr />
<h1><A NAME="other_methods">OTHER METHODS</a></h1>
<p>The ApacheHandler object has a few other publically accessible methods
that may be of interest to end users.</p>
<dl>
<dt><strong><A NAME="handle_request" class="item">handle_request ($r)</a></strong></dt>

<dd>
<p>This method takes an Apache or Apache::Request object representing a
request and translates that request into a form Mason can understand.
Its return value is an Apache status code.</p>
<p>Passing an Apache::Request object is useful if you want to set
Apache::Request parameters, such as POST_MAX or DISABLE_UPLOADS.</p>
</dd>
<dt><strong><A NAME="prepare_request" class="item">prepare_request ($r)</a></strong></dt>

<dd>
<p>This method takes an Apache object representing a request and returns
a new Mason request object or an Apache status code.  If it is a
request object you can manipulate that object as you like, and then
call the request object's <code>exec</code> method to have it generate output.</p>
<p>If this method returns an Apache status code, that means that it could
not create a Mason request object.</p>
<p>This method is useful if you would like to have a chance to decline a
request based on properties of the Mason request object or a component
object.  For example:</p>
<pre>
    my $req = $ah-&gt;prepare_request($r);
    # $req must be an Apache status code if it's not an object
    return $req unless ref($req);</pre>
<pre>
    return DECLINED
        unless $req-&gt;request_comp-&gt;source_file =~ /\.html$/;</pre>
<pre>
    $req-&gt;exec;</pre>
</dd>
<dt><strong><A NAME="request_args" class="item">request_args ($r)</a></strong></dt>

<dd>
<p>Given an Apache request object, this method returns a three item list.
The first item is a hash reference containing the arguments passed by
the client's request.</p>
<p>The second is an Apache request object.  This is returned for
backwards compatibility from when this method was responsible for
turning a plain Apache object into an Apache::Request object.</p>
<p>The third item may be a CGI.pm object or <code>undef</code>, depending on the
value of the <A HREF="Params.html#args_method">args_method</a> parameter.</p>
</dd>
</dl>
<p>
</p>
<hr />
<h1><A NAME="see_also">SEE ALSO</a></h1>
<p><a HREF="Mason.html">HTML::Mason</a>,
<a HREF="Admin.html">HTML::Mason::Admin</a>,
<a HREF="Interp.html">HTML::Mason::Interp</a></p>

</body>

</html>