cvs commit: modperl mod_perl_method_handlers.pod

[as...@hyperreal.org]

ask         98/06/15 23:27:33

  Added:       .        mod_perl_method_handlers.pod
  Log:
  My little text about methodhandlers/objects in modperl.
  There is one 'pod bug'.  I've posted to clpm for help. :)
  
  Revision  Changes    Path
  1.1                  modperl/mod_perl_method_handlers.pod
  
  Index: mod_perl_method_handlers.pod
  ===================================================================
  
  =head1 NAME 
  
  Methodhandlers - a little article about methodhandlers and
  objecthandlers
  
  =head1 DESCRIPTION
  
  Described here are a few examples and hints how to use methodhandlers
  (and objects) with modperl.
  
  This document assumes familiarity with at least L<perltoot> and
  "normal" usage of the Perl*Handlers.
  
  It isn't strictly modperl related, more like "what I use objects for
  in my modperl environment".
  
  Methodhandlers was introduced between as an experimental feature
  between modperl 1.10 and 1.11. They can be enabled in 1.12 with 
  
  =head1 WHY?
  
  The short version: For pretty much the same reasons we're using OO
  perl everywhere else. :-) See L<perltoot>.
  
  The slightly longer version would include some about code reusage and
  more clean interface between modules.
  
  =head1 SIMPLE EXAMPLE
  
  Make sure you're running at least modperl 1.12 and you have compiled
  modperl with PERL_METHOD_HANDLERS=1 or EVERYTHING=1.
  
  Let's start with a simple example.
  
  In httpd.conf:
  
  <Location /obj-handler>
  SetHandler perl-script
  PerlHandler $My::Obj->method
  </Location>
  
  In startup.pl or another PerlRequire'd file:
  
  package This::Class;
  
  $My::Obj = bless {};
  
  sub method ($$) {
      my($obj, $r) = @_;
      $r->send_http_header("text/plain");
      print "$obj isa ", ref($obj);
      0;
  }
  
  which displays:
  
  This::Class=HASH(0x8411edc) isa This::Class
  
  =head1 A LITTLE MORE ADVANCED
  
  That wasn't really useful, so let's try something little more advanced.
  
  I've a little module which creates a graphical 'datebar' for a client.
  (See C<http://www.hip.dk/webajour/datebar>). It's reading a lot of
  small gifs with numbers and weekdays, and keeping them in memory in
  GD.pm's native format, ready to be copied together and served as gifs.
  
  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 
  
  $Client1::Datebar = new Datebar(
  	-imagepath => '/home/client1/datebar/',
  	-size      => [131,18],
  	-elements  => 'wday mday mon year hour min',
  );
  
  $Client2::Datebar = new Datebar
  	-imagepath => '/home/client2/datebar/',
  	-size      => [90,14],
  	-elements  => 'wday hour min',
  );
  
  And then use $Client1::Datebar and $Client2::Datebar as PerlHandlers
  in my Apache configuration.
  
  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.
  
  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
  
  $Client::Article = new WebAjour::Article(-host => 'www.client.com');
  
  in a module what will be run at server startup.
  
  I can then use some simple methods from the $Client::Article object in
  my embperl documents, like:
  
  [- $c = $Client::Article->GetCursor(-layout=>'Frontpage') -]
  [$ while($c->Fetch) $]
    <h2>[+ $c->f('header') +]</h2>
    [+ $c->f('textfield') +]
  [$ endwhile $]
  
  Very very useful!
  
  =head1 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 
  
  $r->push_handlers(PerlHandler => $self->perl_handler_method);
  
  DON'T work, since Perl isn't able to see $self once it goes to PerlHandler.
  
  The best solution to this is to use an anonymous subroutine and pass it $r
  yourself, like this:
  
  $r->push_handlers(PerlHandler => 
  		sub {
  			my $r = shift;
  			$self->perl_handler_method($r);
  		}
  );
  
  =head1 AUTHOR
  
  This document is written by Ask Bjoern Hansen <as...@netcetera.dk> or
  <as...@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.
  
  Some codesnippets is from Doug MacEachern.
  
  =head1 SEE ALSO
  
  L<mod_perl>, L<Apache>, L<perltoot> (also available at
  C<http://www.perl.com/CPAN/doc/FMTEYEWTK/perltoot.html>)