Dancer2::Plugin - Extending Dancer2's DSL with plugins
version 0.159003
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).
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.
use
use FooPlugin
FooPlugin
For a more gentle introduction to Dancer2 plugins, see Dancer2::Plugins.
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).
is_global
session
param
dancer_version
setting
register my_symbol_to_export => sub { # ... some code }, { is_global => 1} ;
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 { ... }, ) ); };
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.
Earlier version of Dancer2 needed the keyword <for_version> to indicate for which version of Dancer the plugin was written, e.g.
register_plugin for_versions => [ 2 ];
Today, plugins for Dancer2 are only expected to work for Dancer2 and the for_versions 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.
for_versions
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.
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.
plugin_setting
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
Allows a plugin to declare a list of supported hooks. Any hook declared like so can be executed by the plugin with execute_hook.
execute_hook
register_hook 'foo'; register_hook 'foo', 'bar', 'baz';
Allows a plugin to execute the hooks attached at the given position
execute_hook 'some_hook';
Arguments can be passed which will be received by handlers attached to that hook:
execute_hook 'some_hook', $some_args, ... ;
The hook must have been registered by the plugin first, with register_hook.
register_hook
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.
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 for_versions => [ 2 ] ; 1;
And in your application:
package My::Webapp; use Dancer2; use Dancer2::Plugin::Logout; get '/logout' => sub { logout };
Dancer Core Developers
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.
To install Dancer2, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Dancer2
CPAN shell
perl -MCPAN -e shell install Dancer2
For more information on module installation, please visit the detailed CPAN module installation guide.