Mason::Manual::Plugins(3) 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;

  • A simple name, which will have ``Mason::Plugin::'' prepended to it.
  • A bundle name, prefixed with '@', which will have ``Mason::PluginBundle::'' prepended to it.
  • A full plugin or bundle class name prefixed with '+'.
  • 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 <[email protected]> for Dist::Zilla and Pod::Weaver, which got me thinking in plugins and lent the plugin and bundle name syntax.

AUTHOR

Jonathan Swartz <[email protected]>

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 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.

LAST SEARCHED