NAME

       Dancer2::Plugin - Extending Dancer2's DSL with plugins

VERSION

       version 0.166001

DESCRIPTION

       You can extend Dancer2 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".

       For a more gentle introduction to Dancer2 plugins, see Dancer2::Plugins.

METHODS

   register
           register 'my_keyword' => sub { ... } => \%options;

       Allows the plugin to define a keyword that will be exported to the caller's namespace.

       The first argument is the symbol name, the second one the coderef to execute when the
       symbol is called.

       The coderef receives as its first argument the Dancer2::Core::DSL object.

       Plugins must use the DSL object to access application components and work with them
       directly.

           sub {
               my $dsl = shift;
               my @args = @_;

               my $app     = $dsl->app;
               my $request = $app->request;

               if ( $app->session->read('logged_in') ) {
                   ...
               }
           };

       As an optional third argument, it's possible to give a hash ref to "register" in order to
       set some options.

       The option "is_global" (boolean) is used to declare a global/non-global keyword (by
       default all keywords are global). A non-global keyword must be called from within a route
       handler (eg: "session" or "param") whereas a global one can be called from everywhere (eg:
       "dancer_version" or "setting").

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

   on_plugin_import
       Allows the plugin to take action each time it is imported.  It is prototyped to take a
       single code block argument, which will be called with the DSL object of the package
       importing it.

       For example, here is a way to install a hook in the importing app:

           on_plugin_import {
               my $dsl = shift;
               $dsl->app->add_hook(
                   Dancer2::Core::Hook->new(
                       name => 'before',
                       code => sub { ... },
                   )
               );
           };

   register_plugin
       A Dancer2 plugin must end with this statement. This lets the plugin register all the
       symbols defined with "register" as exported symbols:

           register_plugin;

       Register_plugin returns 1 on success and undef if it fails.

   plugin_args
       Simple method to retrieve the parameters or arguments 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 ($dsl, @args) = plugin_args(@_);
            ...
         }

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

   plugin_setting
       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 Dancer2::Plugin:: namespace (which is recommended), the remaining part of the
       plugin name.

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

         plugins:
           plugin_name:
             key: value

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

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

   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_hook".

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

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

           $dsl->execute_hook( 'some_hook' );

       Arguments can be passed which will be received by handlers attached to that hook:

           $dsl->execute_hook( 'some_hook', @some_args );

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

EXAMPLE PLUGIN

       The following code is a dummy plugin that provides a keyword 'logout' that destroys the
       current session and redirects to a new URL specified in the config file as "after_logout".

         package Dancer2::Plugin::Logout;
         use Dancer2::Plugin;

         register logout => sub {
           my $dsl  = shift;
           my $app  = $dsl->app;
           my $conf = plugin_setting();

           $app->destroy_session;

           return $app->redirect( $conf->{after_logout} );
         };

         register_plugin;
         1;

       And in your application:

           package My::Webapp;

           use Dancer2;
           use Dancer2::Plugin::Logout;

           get '/logout' => sub { logout };

AUTHOR

       Dancer Core Developers

COPYRIGHT AND LICENSE

       This software is copyright (c) 2015 by Alexis Sukrieh.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.