NAME

Dancer::Plugin::Dispatcher - Controller Class Dispatching System for Dancer

VERSION

version 0.13

SYNOPSIS

    use Dancer;
    use Dancer::Plugin::Dispatcher;

    get '/login'     => dispatch '#login';
    get '/dashboard' => dispatch '#check_session', '#dashboard';

    sub login {
        halt 'Unauthorized' unless login_okay scalar params;
        redirect '/dashboard';
    }

    sub check_session {
        var sessions => generate_session;
    }

    sub dashboard {
        template 'dashboard';
    }

    dance;

DESCRIPTION

Dancer::Plugin::Dispatcher provides a mechanism for dispatching HTTP requests to controller classes allowing you to better separate and compartmentalize your Dancer application. This simple approach is a building block towards giving your Dancer application a more scalable MVC architecture. Note: This is an early release available for testing and feedback and as such is subject to change. The latest release of this distribution breaks backwards compatibility with version 0.12 or anything prior. This plugin leverages dependency injection to load the objects that the HTTP requests will be dispatched to. The invesion of control container is provided by Beam::Wire which supports various patterns for dynamically loading controllers.

METHODS

dispatch

This method takes a string, referred to as a dispatch string, and returns a coderef. The dispatch string represents a controller service and action. The controller service is a Beam::Wire service container configuration. All controller services should be specified under the services property in the plugin configuration. The controller service action is a method on the object which the service loads. The following are the dispatch string semantics:

    plugins:
        Dispatcher:
            services:
                artists:
                    class: MyApp::Artist

    The '#' character is used to separate the controller service name and
    action (method): e.g. (service#action).

    dispatch '#index'; -> dispatches main->index or caller->index
    where caller is the namespace of whichever package loads the plugin

    dispatch 'artists#find'; # dispatches MyApp::Artist->new->find
    dispatch 'artists#single'; # dispatches MyApp::Artist->new->single

Another benefit in using this plugin is a better method of chaining actions. The current method of chaining suggests that you create a catch-all* route which you then use to perform some actions then pass the request to the next matching route forcing you to use mega-splat and re-parse routes to find the next match.

Chaining actions with this plugin only requires you to supply multiple dispatch strings to the dispatch keyword:

    get '/secured' => dispatch '#check_session', '#secured';

    sub chksession {
        return redirect '/' unless session 'user';
    }

    sub secured {
        template 'secured';
    }

If it isn't obvious, when chaining, the dispatch keyword takes multiple dispatch strings and returns a coderef that will execute them sequentially. The first action to explicitly halt execution, by calling Dancer's halt keyword, or issue a 3xx series redirect will break the dispatch chain.

CONFIGURATION

Configuration details will be optionally grabbed from your Dancer config file although no configuration is neccessary. For example:

    plugins:
      Dispatcher:
        services:
            artists:
                class: MyApp::Artist
            albums:
                class: MyApp::Album
            songs:
                class: MyApp::Song

If no configuration information is given, this plugin will attempt to use the calling (or main) namespace as the controller where requests will be dispatched. Controller methods can have a prefix and/or a suffix automatically applied before dispatch. For example:

    plugins:
        Dispatcher:
            prefix: do_
            suffix: _action
            services:
                artists:
                    class: MyApp::Artist
                albums:
                    class: MyApp::Album
                songs:
                    class: MyApp::Song

The prefix and suffix values are optional and will be applied be resolving the controller dispatch chain.

    get '/' => dispatch '#index'; # will execute do_index_action

AUTHORS

• Al Newkirk <anewkirk@ana.io>

• Naveed Massjouni <naveed@vt.edu>

CONTRIBUTORS

• Al Newkirk <we@ana.im>

• David Zurborg <zurborg@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Al Newkirk.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.