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;

       •   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  <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) 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.

perl v5.34.0                                       2022-05-27                        Mason::Manual::Plugins(3pm)