---
name: "Dancer::Plugin"
section: "3pm"
platform: "linux"
package: "libdancer-perl"
version: "1.3521+dfsg-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Dancer::Plugin"
---

# Dancer::Plugin(3pm)

helper for writing Dancer plugins

## NAME

Dancer::Plugin - helper for writing Dancer plugins

## VERSION

version 1.3521

## SYNOPSIS

```
  package Dancer::Plugin::LinkBlocker;
  use Dancer ':syntax';
  use Dancer::Plugin;
  register block_links_from => sub {
    my $conf = plugin_setting();
    my $re = join ('|', @{$conf->{hosts}});
    before sub {
        if (request->referer && request->referer =~ /$re/) {
            status 403 || $conf->{http_code};
        }
    };
  };
  register_plugin;
  1;
```

And in your application:

```
    package My::Webapp;

    use Dancer ':syntax';
    use Dancer::Plugin::LinkBlocker;
    block_links_from; # this is exported by the plugin
```

## DESCRIPTION

Create plugins for Dancer

## PLUGINS

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**

  Lets you define a keyword that will be exported by the plugin.

  ```
      register my_symbol_to_export => sub {
          # ... some code
      };
  ```

- **register\_plugin**

  A Dancer plugin must end with this statement. This lets the plugin register all the symbols define with `"register"` as exported symbols (via the Exporter module).

  A Dancer plugin inherits from Dancer::Plugin and Exporter transparently.

- **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_hooks"`.

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

- **execute\_hooks**

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

  ```
      execute_hooks 'some_hook';
  ```

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

- **plugin\_setting**

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

  ```
    plugins:
      plugin_name:
        key: value
  ```

  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.

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

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

- **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.

  ```
    register foo => sub {
       my ($self, @args) = plugin_args(@_);
       ...
    }
  ```

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

## AUTHORS

This module has been written by Alexis Sukrieh and others.

## LICENSE

This module is free software and is published under the same terms as Perl itself.

## AUTHOR

Dancer Core Developers

## COPYRIGHT AND LICENSE

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