.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "mod_perl_method_handlers 3"
.TH mod_perl_method_handlers 3 "2007-03-30" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
mod_perl_method_handlers \- How to use mod_perl's MethodHandlers 
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Described here are a few examples and hints how to use MethodHandlers
with modperl.
.PP
This document assumes familiarity with at least perltoot and
\&\*(L"normal\*(R" usage of the Perl*Handlers.
.PP
It isn't strictly modperl related, more like \*(L"what I use objects for
in my modperl environment\*(R".
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
If a Perl*Handler is prototyped with '$$', this handler will be
invoked as method, being passed a class name or blessed object as its
first argument and the blessed \fIrequest_rec\fR as the second argument,
e.g.
.PP
.Vb 2
\& package My;
\& @ISA = qw(BaseClass);
.Ve
.PP
.Vb 4
\& sub handler ($$) {
\&     my($class, $r) = @_;
\&     ...;
\& }
.Ve
.PP
.Vb 1
\& package BaseClass;
.Ve
.PP
.Vb 4
\& sub method ($$) {
\&     my($class, $r) = @_;
\&     ...;
\& }
.Ve
.PP
.Vb 1
\& __END__
.Ve
.PP
Configuration:
.PP
.Vb 1
\& PerlHandler My
.Ve
.PP
or
.PP
.Vb 1
\& PerlHandler My->handler
.Ve
.PP
Since the handler is invoked as a method, it may inherit from other
classes:
.PP
.Vb 1
\& PerlHandler My->method
.Ve
.PP
In this case, the 'My' class inherits this method from 'BaseClass'.
.PP
In Perl 5.6.0 or later, you can use subroutine attributes in place
of subroutine prototypes:
.PP
.Vb 2
\& package My;
\& @ISA = qw(BaseClass);
.Ve
.PP
.Vb 4
\& sub handler : method {
\&     my($class, $r) = @_;
\&     ...;
\& }
.Ve
.PP
see the attributes manpage for additional information on 
subroutine attributes.
.PP
To build in the ability to specify Perl*Handlers as method handlers,
configure mod_perl with:
.PP
.Vb 1
\& % perl Makefile.PL PERL_METHOD_HANDLERS=1 [PERL_FOO_HOOK=1,etc]
.Ve
.SH "WHY?"
.IX Header "WHY?"
The short version: For pretty much the same reasons we're using \s-1OO\s0
perl everywhere else. :\-) See perltoot.
.PP
The slightly longer version would include some about code reusage and
more clean interface between modules.
.SH "SIMPLE EXAMPLE"
.IX Header "SIMPLE EXAMPLE"
Let's start with a simple example.
.PP
In httpd.conf:
.PP
.Vb 4
\& <Location /obj-handler>
\& SetHandler perl-script
\& PerlHandler $My::Obj->method
\& </Location>
.Ve
.PP
In startup.pl or another PerlRequire'd file:
.PP
.Vb 1
\& package This::Class;
.Ve
.PP
.Vb 1
\& $My::Obj = bless {};
.Ve
.PP
.Vb 6
\& sub method ($$) {
\&     my($obj, $r) = @_;
\&     $r->send_http_header("text/plain");
\&     print "$obj isa ", ref($obj);
\&     0;
\& }
.Ve
.PP
which displays:
.PP
.Vb 1
\& This::Class=HASH(0x8411edc) isa This::Class
.Ve
.SH "A LITTLE MORE ADVANCED"
.IX Header "A LITTLE MORE ADVANCED"
That wasn't really useful, so let's try something little more advanced.
.PP
I've a little module which creates a graphical 'datebar' for a client.
(See \f(CW\*(C`http://www.hip.dk/date_bar\*(C'\fR). It's reading a lot of small gifs 
with numbers and weekdays, and keeping them in memory in \s-1GD\s0.pm's native 
format, ready to be copied together and served as gifs.
.PP
Now I wanted to use it at another site too, but with a different
look. Obviously something to do with a object. Hence I changed the
module to a object, and can now do a 
.PP
.Vb 5
\& $Client1::Datebar = new Datebar(
\&         -imagepath => '/home/client1/datebar/',
\&         -size      => [131,18],
\&         -elements  => 'wday mday mon year hour min',
\& );
.Ve
.PP
.Vb 5
\& $Client2::Datebar = new Datebar
\&         -imagepath => '/home/client2/datebar/',
\&         -size      => [90,14],
\&         -elements  => 'wday hour min',
\& );
.Ve
.PP
And then use \f(CW$Client1::Datebar\fR and \f(CW$Client2::Datebar\fR as PerlHandlers in my
Apache configuration. Remember to pass them in literal quotes ('') and not
"" which will be interpolated!
.PP
I've a webinterface system to our content\-database. I've created
objects to handle the administration of articles, banners, images and
other content.  It's then very easy (a few lines of code) to enable
certain modules for each client, depending on their needs.
.PP
Another area where I use objects with great success in my modperl
configurations is database abstraction.  All our clients using the
webinterface to handle f.x. articles will use a simple module to
handle everything related to the database.  Each client have
.PP
.Vb 1
\& $Client::Article = new WebAjour::Article(-host => 'www.client.com');
.Ve
.PP
in a module what will be run at server startup.
.PP
I can then use some simple methods from the \f(CW$Client::Article\fR object in
my embperl documents, like:
.PP
.Vb 5
\& [- $c = $Client::Article->GetCursor(-layout=>'Frontpage') -]
\& [$ while($c->Fetch) $]
\&   <h2>[+ $c->f('header') +]</h2>
\&   [+ $c->f('textfield') +]
\& [$ endwhile $]
.Ve
.PP
Very very useful!
.SH "TRAPS"
.IX Header "TRAPS"
mod_perl expects object handlers to be in the form of a string, which it
will thaw for you. That means that something like 
.PP
.Vb 1
\& $r->push_handlers(PerlHandler => '$self->perl_handler_method');
.Ve
.PP
This doesn't work as you might expect, since Perl isn't able to see
\&\f(CW$self\fR once it goes to PerlHandler. 
.PP
The best solution to this is to use an anonymous subroutine and pass it \f(CW$r\fR
yourself, like this:
.PP
.Vb 6
\& $r->push_handlers(PerlHandler => 
\&     sub {
\&         my $r = shift;
\&         $self->perl_handler_method($r);
\&     }
\& );
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
This document is written by Ask Bjoern Hansen <ask@netcetera.dk> or
<ask@apache.org>.  Corrections and suggestions are most
welcome. In particular would more examples be appreciated, most of my
own code is way too integrated with our system, which isn't suitable
for public release.
.PP
Some codesnippets is from Doug MacEachern.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
mod_perl, Apache, perltoot (also available at
\&\f(CW\*(C`http://www.perl.com/CPAN/doc/FMTEYEWTK/perltoot.html\*(C'\fR)