NAME¶
HTML::Mason::ApacheHandler - Mason/mod_perl interface
VERSION¶
version 1.54
SYNOPSIS¶
use HTML::Mason::ApacheHandler;
my $ah = HTML::Mason::ApacheHandler->new (..name/value params..);
...
sub handler {
my $r = shift;
$ah->handle_request($r);
}
DESCRIPTION¶
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
new() constructor.
PARAMETERS TO THE new() CONSTRUCTOR¶
- apache_status_title
- 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.
- args_method
- Method to use for unpacking GET and POST arguments. The valid options are
'CGI' and 'mod_perl'; these indicate that a "CGI.pm" or
"Apache::Request" object (respectively) will be created for the
purposes of argument handling.
'mod_perl' is the default under mod_perl-1 and requires that you have
installed the "Apache::Request" package. Under mod_perl-2, the
default is 'CGI' because "Apache2::Request" is still in
development.
If args_method is 'mod_perl', the $r 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
"Apache::Request" for more information.
If the args_method is 'CGI', the Mason request object ($m) will have a
method called "cgi_object" available. This method returns the
CGI object used for argument processing.
While Mason will load "Apache::Request" or "CGI" as
needed at runtime, it is recommended that you preload the relevant module
either in your httpd.conf or handler.pl file, as this will
save some memory.
- decline_dirs
- True or false, default is true. Indicates whether Mason should decline
directory requests, leaving Apache to serve up a directory index or a
"FORBIDDEN" error as appropriate. See the allowing directory
requests section of the administrator's manual for more information about
handling directories with Mason.
- interp
- The interpreter object to associate with this compiler. By default a new
object of the specified interp_class will be created.
- interp_class
- The class to use when creating a interpreter. Defaults to
HTML::Mason::Interp.
ACCESSOR METHODS¶
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:
my $ah = HTML::Mason::ApacheHandler->new;
my $decline_dirs = $ah->decline_dirs;
$ah->decline_dirs(1);
OTHER METHODS¶
The ApacheHandler object has a few other publically accessible methods that may
be of interest to end users.
- handle_request ($r)
- 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.
Passing an Apache::Request object is useful if you want to set
Apache::Request parameters, such as POST_MAX or DISABLE_UPLOADS.
- prepare_request ($r)
- 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 "exec" method to have it generate output.
If this method returns an Apache status code, that means that it could not
create a Mason request object.
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:
my $req = $ah->prepare_request($r);
# $req must be an Apache status code if it's not an object
return $req unless ref($req);
return DECLINED
unless $req->request_comp->source_file =~ /\.html$/;
$req->exec;
- request_args ($r)
- 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.
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.
The third item may be a CGI.pm object or "undef", depending on the
value of the args_method parameter.
SEE ALSO¶
Mason
AUTHORS¶
- •
- Jonathan Swartz <swartz@pobox.com>
- •
- Dave Rolsky <autarch@urth.org>
- •
- Ken Williams <ken@mathforum.org>
COPYRIGHT AND LICENSE¶
This software is copyright (c) 2012 by Jonathan Swartz.
This is free software; you can redistribute it and/or modify it under the same
terms as the Perl 5 programming language system itself.