ApacheHandler (version 1.28)

HTML::Mason::ApacheHandler - Mason/mod_perl interface

NAME
SYNOPSIS
DESCRIPTION
PARAMETERS TO THE new() CONSTRUCTOR
ACCESSOR METHODS
OTHER METHODS
SEE ALSO

NAME

HTML::Mason::ApacheHandler - Mason/mod_perl interface

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, running components in response to HTTP requests. It is controlled primarily through parameters to the new() constructor.

handle_request() is not a user method, but rather is called from the HTML::Mason::handler() routine in handler.pl.

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 and requires that you have installed the Apache::Request package.; 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 object representing a request and translates that request into a form Mason can understand. It's return value is an Apache status code.

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.