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

- NAME
- SYNOPSIS
- DESCRIPTION
- PARAMETERS TO THE `new()` CONTRUCTOR
- ACCESSOR METHODS
- OTHER METHODS
- SEE ALSO

# NAME

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

# SYNOPSIS

        use HTML::Mason::ApacheHandler;

        my $ah = new HTML::Mason::ApacheHandler (..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()` CONTRUCTOR

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.

  Apache::Request is the default and requires that you have installed this package.

  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 in the ApacheHandler code.

  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.

  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
  Indicates whether Mason should decline directory requests, leaving Apache to serve up a directory index or a FORBIDDEN error as appropriate. Default is 1. See Allowing directory requests in the Admin manual for more information about handling directories with Mason.

interp
  Specifies a Mason interpreter to use for handling requests. An `HTML::Mason::Interp` object will be created if you don't specify one yourself. The interpreter should be an instance of the `HTML::Mason::Interp` class, or a subclass thereof.

# ACCESSOR METHODS

All of the above properties, except interp, 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 = new HTML::Mason::ApacheHandler;
        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, possibly the one originally passed to the method.

  The third item may be a CGI.pm object or `undef`, depending on the value of the ``args_method'' parameter for the ApacheHandler object.

# SEE ALSO

HTML::Mason, HTML::Mason::Admin, HTML::Mason::Interp