NAME

Apache::Wyrd::Handler

SYNOPSIS

PerlWarn off
<Directory /var/www/sites/BASENAME>
	SetHandler perl-script
	PerlHandler BASENAME::Handler
</Directory>

DESCRIPTION

Handler for Apache::Wyrd documents. For more information on mod_perl and handlers, see http://perl.apache.org/docs/index.html

This module has been developed for and only been tested in Apache < 2.0 / mod_perl < 1.99. In this environment, the SYNOPSIS shows a typical set of appropriate Apache directives. Global Perl warnings are turned off, as they are more granularly handled within the package. Note that the Handler that is usedour $VERSION = '0.8'; is an instance of this handler. It is named, in this example, BASNAME::Handler and is found in a BASNAME directory which in @INC of a local mod_perl installation. Traditionally, this is in <apache configuration directory>/lib/perl/. If the perl module BASENAME::Handler has a use base qw(Apache::Wyrd::Handler) pragma, the handler method should properly determine the base class for the BASENAME set of Wyrds and the handler should interpret only those tags beginning <BASENAME::... A rudimentary sample of this usage is available in the t/lib directory of this package and is used forour $VERSION = '0.8'; testing.

This way, several sites using Wyrds can be built, each subclassing Apache::Wyrd objects in their own idiom without interfering in the interpretation of the same objects in another BASENAME class. (However, nothing prevents a second BASENAME from including the first BASENAME in its use base pragma array). This is a feature(tm) of Apache::Wyrd and is intended to promote code re-use.

The Handler also dumps out the error log, if needed from the DBL, where it accumulates from it's own internal calls and calls by Wyrds to the error-level functions (_warn, _error, etc.). If the "init" hashref has a non-null key called "error_page", this log will be reverse-dumped in a standard-looking error page with a backtrace of events.

METHODS

new

Accept and bless a new object. Provided for tradition's sake, since the handler method does the real work.

handler

Handle the request. This handler uses the 2 argument function prototype so that it can be instantiated in another name-space.

In the example Apache directive above, the arguments supplied by the Apache directive give it the class name "BASENAME". It uses this BASENAME to determine what is the base class of all Wyrds it handles. Consequently, it will only parse Wyrds which begin with <BASENAME::...

The handler assembles the Apache request object itself, the initialization hash for the generation of Apache::Wyrd objects, and the globals used by Apache::DBL. It then calls process and respond in sequence. If all goes well, the 'output' attribute has been set by the response method, and this is returned with the appropriate headers set.

add_headers

Called by handler on a successful responses from process and respond. Adds some standard headers to the response or can be overridden. By default, it adds headers to help with compatibility with AOL's famously broken proxies and other similar problems.

get_file

Based on the request, locates the file to be used and sets the file attribute to that path. It declines non-html (*.html) files and passes the mtime and size of the file to the init hashref for use by the Apache::Wyrd object.

globals

defines the hashref which will be kept by the DBL object. Empty by default.

init

defines the hashref which will be used to initialize the Apache::Wyrd objects. It must return the request object under the key 'req', which is stored under the Apache::Wyrd::Handler attribute 'req' by the handler method. Any other keys are optional.

By default, if the hash key 'error_page' is set (non-null), the installation will use an error page with a debugging log. See the errorpage method.

process

"Hook" method for introducing other handling checks to the request. It should return an Apache::Constants value if it wants to override the response of the respond method. If it does this override, then it is responsible for setting it's own headers.

respond

Does the work of setting up the found page as an Apache::Wyrd object and calling it's output method. Should probably not be overridden, unless there are tweaks that cannot be accomplished in add_headers and process.

req

return the Apache request object. This object has been initialized in handler

errorpage

Simply a formatting method. Given the error and the log in scalar form, outputs an Error Page with "Internal Server Error" at the top. Called by respond when the debugging flags are on.

BUGS/CAVEATS

FREE SOFTWARE

Standard warning about GNU GPL software. See LICENSE under the documentation for Apache::Wyrd

UNSTABLE

The basic Wyrd API should remain stable barring unforseen events, but until some time after initial release, this software should be considered unstable.

This software has only tested under Linux and Darwin, but should work for any *nix-style system. This software is not intended for use on windows or other easily-damaged glass objects.

AUTHOR

Barry King <wyrd@nospam.wyrdwright.com>

SEE ALSO

Apache::Wyrd

General-purpose HTML-embeddable perl object

Apache::Wyrd::DBL

"Das Blinkenlights", a more-or-less mandatory module for centralization of calls to the Apache process or an associated DBI-type database.

The Eagle Book

"Writing Apache Modules iwth Perl and C" by Stein & MacEachern, Copyright 1999 O'Reilly & Associates, Inc., ISBN: 1-56592-567-X.

LICENSE

Copyright 2002-2004 Wyrdwright, Inc. and licensed under the GNU GPL.

See LICENSE under the documentation for Apache::Wyrd.