NAME

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

VERSION

version 2.0000_01

DESCRIPTION

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

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 Dancer::Core::DSL object. Any Dancer keyword wrapped by the plugin should be called with the $dsl object like the following:

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

        $dsl->some_dancer_thing;
        ...
    };

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 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 frome everywhere (eg: dancer_version or setting).

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

register_plugin

A Dancer plugin must end with this statement. This lets the plugin register all the symbols defined with register as exported symbols.

Since version 2, Dancer requires any plugin to declare explicitly which version of the core it supports. This is done for safer upgrade of major versions and allow Dancer 2 to detect legacy plugins that have not been ported to the new core. To do so, the plugin must list the major versions of the core it supports in an arrayref, like the following:

    # For instance, if the plugin works with Dancer 1 and 2:
    register_plugin for_versions => [ 1, 2 ];

    # Or if it only works for 2:
    register_plugin for_versions => [ 2 ];

If the for_versions option is omitted, it dfaults to [ 1 ] meaning the plugin was written for Dancer 1 and has not been ported to Dancer 2. This is a rather violent convention but will help a lot the migration of the ecosystem.

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 ($self, @args) = plugin_args(@_);
     ...
  }

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

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 Dancer::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 Dancer::Plugin::Foo::Bar, use:

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

register_hook

Allows a plugin to delcare 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

    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.

EXAMPLE PLUGIN

The following code is a dummy plugin that provides a keyword 'block_links_from'.

  package Dancer::Plugin::LinkBlocker;
  use Dancer::Plugin;

  register block_links_from => sub {
    my $dsl = shift;

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

  register_plugin for_versions => [ 2 ] ;

  1;

And in your application:

    package My::Webapp;

    use Dancer;
    use Dancer::Plugin::LinkBlocker;

    block_links_from; # this is exported by the plugin

AUTHOR

Dancer Core Developers

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 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.

cpanm Dancer

perl -MCPAN -e shell
install Dancer