.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Dancer2::Plugin 3pm"
.TH Dancer2::Plugin 3pm "2014-10-15" "perl v5.20.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Dancer2::Plugin \- Extending Dancer2's DSL with plugins
.SH "VERSION"
.IX Header "VERSION"
version 0.152000
.SH "DESCRIPTION"
.IX Header "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 \f(CW\*(C`register\*(C'\fR).
.PP
Note that you have to \f(CW\*(C`use\*(C'\fR 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 \f(CW\*(C`use FooPlugin\*(C'\fR if they want to use the
symbols exported by \f(CW\*(C`FooPlugin\*(C'\fR.
.PP
For a more gentle introduction to Dancer2 plugins, see Dancer2::Plugins.
.SH "METHODS"
.IX Header "METHODS"
.SS "register"
.IX Subsection "register"
.Vb 1
\&    register \*(Aqmy_keyword\*(Aq => sub { ... } => \e%options;
.Ve
.PP
Allows the plugin to define a keyword that will be exported to the caller's
namespace.
.PP
The first argument is the symbol name, the second one the coderef to execute
when the symbol is called.
.PP
The coderef receives as its first argument the Dancer2::Core::DSL object.
.PP
Plugins \fBmust\fR use the \s-1DSL\s0 object to access application components and work
with them directly.
.PP
.Vb 3
\&    sub {
\&        my $dsl = shift;
\&        my @args = @_;
\&
\&        my $app     = $dsl\->app;
\&        my $request = $app\->request;
\&
\&        if ( $app\->session\->read(\*(Aqlogged_in\*(Aq) ) {
\&            ...
\&        }
\&    };
.Ve
.PP
As an optional third argument, it's possible to give a hash ref to \f(CW\*(C`register\*(C'\fR
in order to set some options.
.PP
The option \f(CW\*(C`is_global\*(C'\fR (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: \f(CW\*(C`session\*(C'\fR or \f(CW\*(C`param\*(C'\fR) whereas a global one can be
called from everywhere (eg: \f(CW\*(C`dancer_version\*(C'\fR or \f(CW\*(C`setting\*(C'\fR).
.PP
.Vb 3
\&    register my_symbol_to_export => sub {
\&        # ... some code
\&    }, { is_global => 1} ;
.Ve
.SS "on_plugin_import"
.IX Subsection "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 \s-1DSL\s0 object of the package importing it.
.PP
For example, here is a way to install a hook in the importing app:
.PP
.Vb 9
\&    on_plugin_import {
\&        my $dsl = shift;
\&        $dsl\->app\->add_hook(
\&            Dancer2::Core::Hook\->new(
\&                name => \*(Aqbefore\*(Aq,
\&                code => sub { ... },
\&            )
\&        );
\&    };
.Ve
.SS "register_plugin"
.IX Subsection "register_plugin"
A Dancer2 plugin must end with this statement. This lets the plugin register all
the symbols defined with \f(CW\*(C`register\*(C'\fR as exported symbols:
.PP
.Vb 1
\&    register_plugin;
.Ve
.PP
Register_plugin returns 1 on success and undef if it fails.
.PP
\fIDeprecation note\fR
.IX Subsection "Deprecation note"
.PP
Earlier version of Dancer2 needed the keyword <for_version> to indicate for
which version of Dancer the plugin was written, e.g.
.PP
.Vb 1
\&    register_plugin for_versions => [ 2 ];
.Ve
.PP
Today, plugins for Dancer2 are only expected to work for Dancer2 and the
\&\f(CW\*(C`for_versions\*(C'\fR keyword is ignored. If you try to load a plugin for Dancer2
that does not meet the requirements of a Dancer2 plugin, you will get an error
message.
.SS "plugin_args"
.IX Subsection "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.
.PP
.Vb 4
\&  register foo => sub {
\&     my ($dsl, @args) = plugin_args(@_);
\&     ...
\&  }
.Ve
.PP
Note that Dancer 1 will return undef as the \s-1DSL\s0 object.
.SS "plugin_setting"
.IX Subsection "plugin_setting"
If \f(CW\*(C`plugin_setting\*(C'\fR is called inside a plugin, the appropriate configuration
will be returned. The \f(CW\*(C`plugin_name\*(C'\fR should be the name of the package, or,
if the plugin name is under the \fBDancer2::Plugin::\fR namespace (which is
recommended), the remaining part of the plugin name.
.PP
Configuration for plugin should be structured like this in the config.yml of
the application:
.PP
.Vb 3
\&  plugins:
\&    plugin_name:
\&      key: value
.Ve
.PP
Enclose the remaining part in quotes if it contains ::, e.g.
for \fBDancer2::Plugin::Foo::Bar\fR, use:
.PP
.Vb 3
\&  plugins:
\&    "Foo::Bar":
\&      key: value
.Ve
.SS "register_hook"
.IX Subsection "register_hook"
Allows a plugin to declare a list of supported hooks. Any hook declared like so
can be executed by the plugin with \f(CW\*(C`execute_hook\*(C'\fR.
.PP
.Vb 2
\&    register_hook \*(Aqfoo\*(Aq;
\&    register_hook \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq;
.Ve
.SS "execute_hook"
.IX Subsection "execute_hook"
Allows a plugin to execute the hooks attached at the given position
.PP
.Vb 1
\&    execute_hook \*(Aqsome_hook\*(Aq;
.Ve
.PP
Arguments can be passed which will be received by handlers attached to that
hook:
.PP
.Vb 1
\&    execute_hook \*(Aqsome_hook\*(Aq, $some_args, ... ;
.Ve
.PP
The hook must have been registered by the plugin first, with \f(CW\*(C`register_hook\*(C'\fR.
.SH "EXAMPLE PLUGIN"
.IX Header "EXAMPLE PLUGIN"
The following code is a dummy plugin that provides a keyword 'logout' that
destroys the current session and redirects to a new \s-1URL\s0 specified in
the config file as \f(CW\*(C`after_logout\*(C'\fR.
.PP
.Vb 2
\&  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 for_versions => [ 2 ] ;
\&
\&  1;
.Ve
.PP
And in your application:
.PP
.Vb 1
\&    package My::Webapp;
\&
\&    use Dancer2;
\&    use Dancer2::Plugin::Logout;
\&
\&    get \*(Aq/logout\*(Aq => sub { logout };
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Dancer Core Developers
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2014 by Alexis Sukrieh.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.