GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  MASON::MANUAL::PLUGINS (3)

.ds Aq ’

NAME

Mason::Manual::Plugins - Mason plugins

CONTENTS

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

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 MASON::MANUAL::PLUGINS (3) 2015-05-16

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.