Mason::Manual::Plugins(3pm) User Contributed Perl Documentation Mason::Manual::Plugins(3pm)
NAME
Mason::Manual::Plugins - Mason plugins
DESCRIPTION
A Mason plugin modifies behavior in one or more of Mason's main classes simultaneously, using Moose roles. Many Mason features, even some
that might be considered "core", are implemented with plugins.
FINDING PLUGINS
By convention plugins live in the "Mason::Plugin::*" namespace, and plugin bundles live in the "Mason::PluginBundle::*" namespace. You can
find both with this search:
http://search.cpan.org/search?query=Mason%3A%3APlugin&mode=all
USING PLUGINS
Pass a list of plugin specs to the Mason constructor:
Mason->new(plugins =>
[
'OnePlugin',
'AnotherPlugin',
'+My::Mason::Plugin::AThirdPlugin',
'@APluginBundle',
'+My::Mason::PluginBundle::AnotherBundle',
'-PluginIDontLike',
]);
Each plugin spec can be one of the following;
o A simple name, which will have "Mason::Plugin::" prepended to it.
o A bundle name, prefixed with '@', which will have "Mason::PluginBundle::" prepended to it.
o A full plugin or bundle class name prefixed with '+'.
o Any spec prefixed with '-', which means do not include these plugin(s) in the final list.
See Mason::t::Plugins::test_plugin_specs in the Mason distribution for some examples.
DEFAULT PLUGINS
Mason will always add the @Default bundle regardless of whether you pass your own list. You can remove individual default plugins that you
don't like:
plugins => ['-DollarDot', ...]
or the whole list:
plugins => ['-@Default', ...]
CREATING PLUGINS
Note: If you want to modify behavior for a particular application only, it might be more convenient to create subclasses.
A plugin consists of the main plugin class and one or more roles. The main class currently looks like this:
package Mason::Plugin::MyPlugin;
use Moose;
with 'Mason::Plugin';
# Optional: declare other plugin dependencies
method requires_plugins { qw(A @D) }
1;
__END__
=pod
=head1 NAME
Mason::Plugin::MyPlugin - My plugin
....
Its main responsibilities are to include the role 'Mason::Plugin' and document itself. It may also specify a "requires_plugins" that
returns a list of dependencies with the same syntax as the "plugins" parameter to "Mason-"new>.
The real action is in the role classes, which live underneath, and each modify a single Mason class:
package Mason::Plugin::MyPlugin::Interp;
use Mason::PluginRole;
# Modify Mason::Interp
...
package Mason::Plugin::MyPlugin::Compilation;
use Mason::PluginRole;
# Modify Mason::Compilation
...
When a plugin is applied, each of its roles will be automatically applied to the appropriate Mason class. For example, in the example above
"Mason::Plugin::MyPlugin::Interp" and "Mason::Plugin::MyPlugin::Compilation" will be applied to Mason::Interp and Mason::Compilation
respectively.
Pluggable Mason classes
As of this writing the following Mason classes can be modified with plugins:
Mason::CodeCache
Mason::Compilation
Mason::Component
Mason::Component::ClassMeta
Mason::Component::Import
Mason::Component::Moose
Mason::Interp
Mason::Request
Mason::Result
Extra classes in plugin
If you have extra classes in your plugin that aren't automatically providing a role to a Mason class, put them in "Extra.pm" or the "Extra"
subdirectory, e.g.
package Mason::Plugin::MyPlugin::Extra::Utils;
...
That will ensure that your classname will not conflict with a future Mason class name.
CREATING PLUGIN BUNDLES
A plugin bundle just collects one or more plugins and/or other bundles. It looks like this:
package Mason::PluginBundle::MyBundle
use Moose;
with 'Mason::PluginBundle';
sub requires_plugins {
return (
'A',
'B',
'+My::Plugin::C',
'@D',
'+My::PluginBundle::E',
);
}
1;
__END__
=pod
=head1 NAME
Mason::PluginBundle::MyBundle - My plugin bundle
=head1 INCLUDED PLUGINS
=over
=item A
=item B
=item +My::Plugin::C
=item @D
=item +My::PluginBundle::E
=back
....
The "requires_plugins" method returns a list of entries, with the same syntax as the "plugins" parameter to "Mason-"new>.
ACKNOWLEDGEMENTS
Thanks to Ricardo Signes <rjbs@cpan.org> for Dist::Zilla and Pod::Weaver, which got me thinking in plugins and lent the plugin and bundle
name syntax.
SEE ALSO
Mason
AUTHOR
Jonathan Swartz <swartz@pobox.com>
COPYRIGHT AND LICENSE
This software is copyright (c) 2011 by Jonathan Swartz.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
perl v5.14.2 2012-05-02 Mason::Manual::Plugins(3pm)