Modifying the Maypole request object

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"

   __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

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.