<?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:root@localhost" /> </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->new (..name/value params..); ... sub handler { my $r = shift; $ah->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 "HTML::Mason status". 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->new; my $decline_dirs = $ah->decline_dirs; $ah->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->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->request_comp->source_file =~ /\.html$/;</pre> <pre> $req->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>