Maypole::Manual::PlugiUser)Contributed Perl DocumenMaypole::Manual::Plugins(3)NAMEMaypole::Manual::Plugins - the Maypole Plugin API
VERSION
This version written for Maypole 2.10
LOADING PLUGINS
Plugins occupy the "Maypole::Plugin::*" namespace on CPAN. At time of
writing, there are 16 plugin modules available - see
http://search.cpan.org/search?query=Maypole%3A%3APlugin&mode=module
Plugins are loaded into a Maypole application by Maypole::Application.
For instance, to add HTML::QuickTable support to the BeerDB example
application:
package BeerDB;
use strict;
use warnings;
use Maypole::Application( 'QuickTable' );
Note that the leading "Maypole::Plugin::*" is omitted.
For some plugins, that's it. You probably have a bunch of new methods
available on your Maypole request objects - see the documentation for
the plugin.
For others, you will need to set configuration variables or customise
other parts of the application. For instance, to add sessions to your
application, you can use Maypole::Plugin::Session:
package BeerDB;
use strict;
use warnings;
use Maypole::Application( 'Session' );
That's all, if you're willing to stick with the defaults
(Apache::Session::File backend, session and lock files in
"/tmp/sessions" and "/tmp/sessionlock"). Otherwise, you need to supply
some configuration:
__PACKAGE__->config->session( { class => "Apache::Session::Flex",
args => {
Store => 'DB_File',
Lock => 'Null',
Generate => 'MD5',
Serialize => 'Storable'
}
} );
The plugin module is responsible for adding slots to Maypole::Config,
in this case, the "session" accessor.
WRITING PLUGINS
Modifying the Maypole request object
Plugins are inserted into the @ISA of the Maypole request object. So
method calls on the request object will first search the plugin
classes, before looking in Maypole. Methods defined in the plugin are
therefore directly available on the request. That also goes for methods
inherited by the plugin. I'm not aware of any plugins that currently
inherit from another package, but there's no reason not to.
Note that if you need simple accessor methods on the request, you can
add them by saying
Maypole->mk_accessors( qw/ fee fi fo / );
at the start of your plugin. Under mod_perl, you've just added these
accessors to all Maypole applications on the server, even ones that do
not use this plugin. You could instead make the call inside the "setup"
method:
$r->mk_accessors( qw/ fee fi fo / );
Now the accessors are only added to applications that use this plugin.
Initialisation with "setup"
After loading plugins via Maypole::Application, setting configuration
variables in calls to "__PACKAGE__->config->foo( 'bar' )", and
optionally defining custom request methods, your application should
call its "setup" method, generally including arguments for the database
connection:
__PACKAGE__->setup( $dsn, $user, $pass, @more_args );
All of these arguments will be passed to the "setup_database" method of
the model class.
"Maypole::setup()" is responsible for loading the model class, calling
the "setup_database" method on the model class, and making each table
class in the application inherit from the model. It is therefore
recommended that you call "setup" after setting up all your
configuration options.
Plugins can intercept the call to "setup" to carry out their own
initialisation, as long as they propagate the call up through the
hierarchy. A common idiom for this is:
Maypole::Plugin::Foo;
use strict;
use warnings;
use NEXT;
sub setup
{
my $r = shift;
$r->NEXT::DISTINCT::setup(@_);
# Foo initialisation goes here
my $option = $r->config->foo_option;
# do something with $option
}
NEXT is a replacement for the built-in "SUPER" syntax. "SUPER"
dispatches a call to the superclass of the current package - but it
determines the superclass at compile time. At that time, the superclass
is something like "main::". NEXT does the superclass lookup at runtime,
after Maypole::Application has inserted the plugin into the request
class's inheritance chain.
The "DISTINCT" modifier ensures each plugin's "setup" method is only
called once, and protects against diamond inheritance. This may or may
not be an issue in your app - and if you always use the "DISTINCT"
syntax, it won't be.
Notice that the "setup" call is re-dispatched before running the
plugin's own initialisation code. This allows "Maypole::setup()" to set
up the database, model, and table classes, before your plugin starts
tweaking things.
You can use the "setup" method to load modules into the request class
namespace. Maypole::Plugin::I18N has:
sub setup {
my $r = shift;
$r->NEXT::DISTINCT::setup(@_);
require Locale::Maketext::Simple;
import Locale::Maketext::Simple
Class => $r,
Export => '_loc',
Path => $r->config->lexicon;
}
Now the application namespace has a "_loc" function (exported by
Locale::Maketext::Simple), (plus "lang" and "maketext" methods
inherited from Maypole::Plugin::I18N).
More initialisation with "init"
Maypole also defines an "init" method. It pulls the name of the view
class from the config, loads it, instantiates an object in the view
class, and sets this in the "view_object" config slot.
In CGI applications, "init" is called at the start of every request.
Under mod_perl, this method will only ever be called once per server
child, at the start of the first request after server startup. If
instead, you call this method in your application module (after the
call to "setup"), then the code loaded by this call will be shared by
all child servers.
See Hacking the view for a plugin that uses "init".
Adding configuration
The configuration object can be retrieved from the Maypole request
object ("$r->config") or as a class method on the application (e.g.
"BeerDB->config").
If your plugin needs some custom configuration settings, you can add
methods to the config object by saying
Maypole::Config->mk_accessors( qw/ foo bar baz / );
at the start of your plugin. In the application, after the
"Maypole::Application" call, these methods will be available on the
config object.
Modifying the Maypole model
Replacing the model
To load a different model, set "__PACKAGE__->config->model(
'Custom::Model' )" in the application before calling "setup". You
could instead set "$r->config->model" before re-dispatching the
"setup" call, but this is going to confuse and annoy your users.
Hacking the model
CAVEAT: the way I do this just seems dirty, so there must be a
Better Way.
Maypole::Plugin::FormBuilder (part of the Maypole::FormBuilder
distribution), in its "setup" method, loads a custom pager class
into the model by saying
eval "package $model; use $pager";
Yuk. Note that under mod_perl, you have just forced every
application using $model to also use $pager.
"Maypole::Plugin::AutoUntaint::setup()" loads an extra method into
the model by saying
no strict 'refs';
*{"$model\::auto_untaint"} = \&Class::DBI::Plugin::AutoUntaint::auto_untaint;
Yuk again. And again, under mod_perl, now every application using
$model has an "auto_untaint" method added to its model.
Same plugin, next line has
eval "package $model; use Class::DBI::Plugin::Type";
Same yuk, same mod_perl caveat.
Modifying the Maypole view
Replacing the view
Again, just specify a different view in the application
configuration.
Hacking the view
Maypole::Plugin::FormBuilder intercepts the "init" call to override
the "vars" method in the view class. First it re-dispatches the
"init" call, which will set up either a default view class and
object, or those configured in the application. Then it builds a
new view class on-the-fly, and makes this new class inherit from
Maypole::FormBuilder::View and from the original view class.
Finally it replaces the "view" and "view_object" in the
application's config object.
sub init
{
my ( $class ) = @_;
my $config = $class->config;
$class->NEXT::DISTINCT::init;
my $old_view = $class->config->view ||
die "Please configure a view in $class before calling init()";
my $virtual_view = "$class\::__::View";
eval <<VIEW;
package $virtual_view;
use base qw( Maypole::FormBuilder::View $old_view );
VIEW
die $@ if $@;
$config->view( $virtual_view );
$class->view_object( $virtual_view->new );
}
There really must be a Better Way.
AUTHOR
David Baird, "<cpan@riverside-cms.co.uk>"
COPYRIGHT & LICENSE
Copyright 2005 David Baird, All Rights Reserved.
This text is free documentation; you can redistribute it and/or modify
it under the same terms as the Perl documentation itself.
perl v5.14.1 2005-11-23 Maypole::Manual::Plugins(3)
