[cgi-wiki-dev] RFC: CGI::Wiki::AutoPlugin

IvorW ivorw-openguides at xemaps.com
Sat Dec 10 18:52:15 GMT 2005

Not written the code yet, just after some feedback.

=head1 NAME

CGI::Wiki::AutoPlugin - Automatic marshalling of CGI::Wiki plugins


  use CGI::Wiki::AutoPlugin;

  my $ap = CGI::Wiki::AutoPlugin->new( key1 => value1, key2 => value2...);

  $ap->register( $wiki );

  $ap->despatch( 'pre_write');


L<CGI::Wiki::Plugin> provides a basic framework for writing additional
that work with L<CGI::Wiki> objects. But, the process of using the plugins
from a wiki application to date has been a manual one.

The purpose of CGI::Wiki::AutoPlugin is to detect, require and
instantiate all
the plugin modules that have been installed. An instance of every plugin is
available for common method despatching. The wiki application uses despatch
to provide a set of standard hooks which may or may not be present in a

=head1 USAGE

=head2 new

This will look for all the plugins, and instantiate one of each class by
calling new. Passed in is an arbitrary list of named parameters (key and
value pairs), which are passed to new for each plugin.

Returns a CGI::Wiki::AutoPlugin object.

=head2 register

Takes a CGI::Wiki object as a parameter, and registers all the plugins to
the wiki.

=head2 despatch

Takes a method name and further parameters to be passed in to the plugins.
All the plugins which C<can> call the method are called.

Any modifiable parameters are passed by reference (e.g. may be objects),
hence may be changed by one plugin before another plugin sees them.

The following standard hooks are used:

=over 4

=item C<pre_retrieve>

  $ap->despatch( 'pre_retrieve', $node);

Called before retrieving a node from the database, A suitable place to check
whether the user is permitted to read the node. Also, a place to munge UTF8,
word separation (space or underscore) and capitalization.

=item C<post_retrieve>

  $ap->despatch( 'post_retrieve', $node, $content, \%metadata);

We've just got a node back from the database. Here we can do any munging
needed before we look at the data.

=item C<pre_write>

  $ap->despatch( 'pre_write', $node, $content, \%metadata);

Again, a suitable place for an authentication check and/or some munging.


=head1 SUPPORT

    Please discuss on the cgi-wiki-dev mailing list:

=head1 AUTHOR

	Ivor Williams
	ivorw-openguides at xemaps.com


This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the
LICENSE file included with this module.

=head1 SEE ALSO

L<CGI::Wiki::Plugin>, L<CGI::Wiki>.

More information about the CGI-Wiki-dev mailing list