NAME

       Dancer::Plugin - helper for writing Dancer plugins

DESCRIPTION

       Create plugins for Dancer

SYNOPSIS

         package Dancer::Plugin::LinkBlocker;
         use Dancer ':syntax';
         use Dancer::Plugin;

         register block_links_from => sub {
           my $conf = plugin_setting();
           my $re = join ('|', @{$conf->{hosts}});
           before sub {
               if (request->referer && request->referer =~ /$re/) {
                   status 403 || $conf->{http_code};
               }
           };
         };

         register_plugin;
         1;

       And in your application:

           package My::Webapp;

           use Dancer ':syntax';
           use Dancer::Plugin::LinkBlocker;

           block_links_from; # this is exported by the plugin

PLUGINS

       You can extend Dancer by writing your own Plugin.

       A plugin is a module that exports a bunch of symbols to the current namespace (the caller
       will see all the symbols defined via "register").

       Note that you have to "use" the plugin wherever you want to use its symbols.  For
       instance, if you have Webapp::App1 and Webapp::App2, both loaded from your main
       application, they both need to "use FooPlugin" if they want to use the symbols exported by
       "FooPlugin".

   METHODS
       register
           Lets you define a keyword that will be exported by the plugin.

               register my_symbol_to_export => sub {
                   # ... some code
               };

       register_plugin
           A Dancer plugin must end with this statement. This lets the plugin register all the
           symbols define with "register" as exported symbols (via the Exporter module).

           A Dancer plugin inherits from Dancer::Plugin and Exporter transparently.

       register_hook
           Allows a plugin to declare a list of supported hooks. Any hook declared like so can be
           executed by the plugin with "execute_hooks".

               register_hook 'foo';
               register_hook 'foo', 'bar', 'baz';

       execute_hooks
           Allows a plugin to execute the hooks attached at the given position

               execute_hooks 'some_hook';

           The hook must have been registered by the plugin first, with "register_hook".

       plugin_setting
           Configuration for plugin should be structured like this in the config.yml of the
           application:

             plugins:
               plugin_name:
                 key: value

           If "plugin_setting" is called inside a plugin, the appropriate configuration will be
           returned. The "plugin_name" should be the name of the package, or, if the plugin name
           is under the Dancer::Plugin:: namespace (which is recommended), the remaining part of
           the plugin name.

           Enclose the remaining part in quotes if it contains ::, e.g.  for
           Dancer::Plugin::Foo::Bar, use:

             plugins:
               "Foo::Bar":
                 key: value

       plugin_args
           To easy migration and interoperability between Dancer 1 and Dancer 2 you can use this
           method to obtain the arguments or parameters passed to a plugin-defined keyword.
           Although not relevant for Dancer 1 only, or Dancer 2 only, plugins, it is useful for
           universal plugins.

             register foo => sub {
                my ($self, @args) = plugin_args(@_);
                ...
             }

           Note that Dancer 1 will return undef as the object reference.

AUTHORS

       This module has been written by Alexis Sukrieh and others.

LICENSE

       This module is free software and is published under the same terms as Perl itself.