The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Dancer2::Manual::Hooks; - Reference manual for all hooks supported by Dancer2's core.

VERSION

version 0.02

This manual documents all the hooks that are supported by the core framework.

Request workflow

before hooks are evaluated before each request within the context of the request and can modify the request and response. It's possible to define variables which will be accessible in the action blocks with the keyword 'var'.

    hook before => sub {
        var note => 'Hi there';
        request->path_info('/foo/oversee')
    };

    get '/foo/*' => sub {
        my ($match) = splat; # 'oversee';
        vars->{note}; # 'Hi there'
    };

For another example, this can be used along with session support to easily give non-logged-in users a login page:

    hook before => sub {
        if (!session('user') && request->path_info !~ m{^/login}) {
            # Pass the original path requested along to the handler:
            var requested_path => request->path_info;
            request->path_info('/login');
        }
    };

The request keyword returns the current Dancer2::Request object representing the incoming request. See the documentation of the Dancer2::Core::Request module for details.

after hooks are evaluated after the response has been built by a route handler, and can alter the response itself, just before it's sent to the client.

The filter is given the response object as its first argument:

    hook after => sub {
        my $response = shift;
        $response->{content} = 'after filter got here!';
    };

Templates

before_template_render hooks are called whenever a template is going to be processed, they are passed the tokens hash which they can alter.

    hook before_template_render => sub {
        my $tokens = shift;
        $tokens->{foo} = 'bar';
    }

The tokens hash will then be passed to the template with all the modifications performed by the filter. This is a good way to setup some global vars you like to have in all your templates, like the name of the user logged in or a section name.

after_template_render hooks are called after the view has been rendered. They receive as their first argument the reference to the content that has been produced. This can be used to post-process the content rendered by the template engine.

    hook after_template_render => sub {
        my $ref_content = shift;
        my $content = $$ref_content;
        # do something with $content
        $ref_content = \$content;
    };

before_layout_render hooks are called whenever the layout is going to be applied to the current content. The arguments received by the hook are the current tokens hashref and a reference to the current content.

    hook before_layout_render => sub {
        my ($tokens, $ref_content) = @_;
        $tokens->{new_stuff} = 42;
        $ref_conent = \"new content";
    };

after_layout_render hooks are called once the complete content of the view has been produced, after the layout has been applied to the content. The argument received by the hook is a reference to the complete content string.

    hook after_layout_render => sub {
        my $ref_content = shift;
        ...
    };

Error handling

When an error is caught by Dancer2's core, an exception object is built (of the class Dancer2::Core::Error. This class provides hook to let the user alter the error work-flow if needed.

init_error hooks are called whenever an error object is built, the object is passed to the hook.

    hook init_error => sub {
        my $error = shift;
        # do something with $error 
    };

before_error hooks are called whenever an error is going to be thrown, it receives the error object as its first and unique argument.

    hook before_error => sub {
        my $error = shift;
        # do something with $error 
    };

after_error hooks are called whenever an error object has been thrown, it receives the generated content as the first argument.

    hook after_error => sub {
        my $content = shift;
    };

File rendering

Whenever a content is produced out of the parsing of a static file, the Dancer::Handler::File component is used. This component provides two hooks, before_file_render and after_file_render.

before_file_render hooks are called just before starting to parse the file, the hook receives as its first argument the file path that is going to be processed.

    hook before_file_render => sub {
        my $path = shift;
    };

after_file_render are called after the file has been parsed and the response content produced. It receives the response object (Dancer2::Core::Response) produced.

    hook after_file_render => sub {
       my $response = shift; 
    };

AUTHOR

Dancer Core Developers

COPYRIGHT AND LICENSE

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