.\" 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 "Dancer::Plugin 3pm"
.TH Dancer::Plugin 3pm "2015-11-07" "perl v5.20.2" "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"
Dancer::Plugin \- helper for writing Dancer plugins
.SH "VERSION"
.IX Header "VERSION"
version 1.3202
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  package Dancer::Plugin::LinkBlocker;
\&  use Dancer \*(Aq:syntax\*(Aq;
\&  use Dancer::Plugin;
\&
\&  register block_links_from => sub {
\&    my $conf = plugin_setting();
\&    my $re = join (\*(Aq|\*(Aq, @{$conf\->{hosts}});
\&    before sub {
\&        if (request\->referer && request\->referer =~ /$re/) {
\&            status 403 || $conf\->{http_code};
\&        }
\&    };
\&  };
\&
\&  register_plugin;
\&  1;
.Ve
.PP
And in your application:
.PP
.Vb 1
\&    package My::Webapp;
\&    
\&    use Dancer \*(Aq:syntax\*(Aq;
\&    use Dancer::Plugin::LinkBlocker;
\&
\&    block_links_from; # this is exported by the plugin
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Create plugins for Dancer
.SH "PLUGINS"
.IX Header "PLUGINS"
You can extend Dancer by writing your own Plugin.
.PP
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.
.SS "\s-1METHODS\s0"
.IX Subsection "METHODS"
.IP "\fBregister\fR" 4
.IX Item "register"
Lets you define a keyword that will be exported by the plugin.
.Sp
.Vb 3
\&    register my_symbol_to_export => sub {
\&        # ... some code 
\&    };
.Ve
.IP "\fBregister_plugin\fR" 4
.IX Item "register_plugin"
A Dancer plugin must end with this statement. This lets the plugin register all
the symbols define with \f(CW\*(C`register\*(C'\fR as exported symbols (via the Exporter
module).
.Sp
A Dancer plugin inherits from Dancer::Plugin and Exporter transparently.
.IP "\fBregister_hook\fR" 4
.IX Item "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_hooks\*(C'\fR.
.Sp
.Vb 2
\&    register_hook \*(Aqfoo\*(Aq; 
\&    register_hook \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq;
.Ve
.IP "\fBexecute_hooks\fR" 4
.IX Item "execute_hooks"
Allows a plugin to execute the hooks attached at the given position
.Sp
.Vb 1
\&    execute_hooks \*(Aqsome_hook\*(Aq;
.Ve
.Sp
The hook must have been registered by the plugin first, with \f(CW\*(C`register_hook\*(C'\fR.
.IP "\fBplugin_setting\fR" 4
.IX Item "plugin_setting"
Configuration for plugin should be structured like this in the config.yml of
the application:
.Sp
.Vb 3
\&  plugins:
\&    plugin_name:
\&      key: value
.Ve
.Sp
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 \fBDancer::Plugin::\fR namespace (which is
recommended), the remaining part of the plugin name.
.Sp
Enclose the remaining part in quotes if it contains ::, e.g.
for \fBDancer::Plugin::Foo::Bar\fR, use:
.Sp
.Vb 3
\&  plugins:
\&    "Foo::Bar":
\&      key: value
.Ve
.IP "\fBplugin_args\fR" 4
.IX Item "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.
.Sp
.Vb 4
\&  register foo => sub {
\&     my ($self, @args) = plugin_args(@_);
\&     ...
\&  }
.Ve
.Sp
Note that Dancer 1 will return undef as the object reference.
.SH "AUTHORS"
.IX Header "AUTHORS"
This module has been written by Alexis Sukrieh and others.
.SH "LICENSE"
.IX Header "LICENSE"
This module is free software and is published under the same
terms as Perl itself.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dancer Core Developers
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2010 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.