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

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

# NAME

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

# SYNOPSIS

        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 Apache, 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 (often http://localhost/perl-status/). Default is ``HTML::Mason status''. This is useful if you create more then one ApacheHandler object and want them all visible via Apache::Status.

debug_handler_proc, debug_handler_script, debug_mode, debug_perl_binary
  The debug_* parameters control Mason's use of debug files. Component debugging procedures are fully described in the Mason Administrator's Guide.

error_mode
  Specifies one of two ways to handle Perl errors, 'fatal' or 'html'. In fatal mode the handler simply dies with the error message. This may be caught with an eval around `$ah->handle_request` or left for Apache to handle (generally with a return status of 500). In HTML mode the handler sends a readable HTML version of the error message to the client. HTML mode is most useful in combination with batch output mode for debugging.

output_mode
  Specifies one of two ways to send output to the client, 'batch' or 'stream'. Batch mode means that Mason computes the entire page in memory and then transmits it all at once. Stream mode means that Mason outputs data as soon as it is computed. (This is only Mason's point of view; it does not take buffering done by Perl or the O/S into account.) Both of these modes use `$r->print` and override the value of `$interp->out_method`. The default is 'batch'. If output_mode is specified as `undef`, then `$interp->out_method` is left untouched.

top_level_predicate
  Reference to a subroutine that decides whether a component can answer top level requests. This allows for private-use components that live within the DocumentRoot but are inaccesible from URLs. By default, always returns 1.

  The subroutine receives one parameter, the absolute path to the component. It then returns either a true (serve component) or false (reject component). In this example, the predicate rejects requests for components whose name starts with an ``_'' character:

          top_level_predicate => sub { basename($_[0]) !~ /^_/ }

  NOTE: In this example I've used `basename()` from the File::Basename package. Since the top_level_predicate is defined in handler.pl, within HTML::Mason, any such symbols need to be imported into that package. In other words, I would need a `use File::Basename` somewhere below the `package HTML::Mason` line in `handler.pl`.

# ACCESSOR METHODS

All of the above properties have standard accessor methods of the same name: no arguments retrieves the value, and one argument sets it. For example:

        my $ah = new HTML::Mason::ApacheHandler;
        my $errmode = $ah->error_mode;
        $ah->error_mode('html');

# AUTHOR

Jonathan Swartz, swartz@transbay.net

# SEE ALSO

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