NAME

SYNOPSIS

    package MyApp::Dispatcher;
    use Jifty::Dispatcher -base;

    under ['blog', 'wiki'] => [
        run {
            default model => "MyApp::Model::\u$1"
        },
        on PUT 'entries/*' => run {
            set entry_id => $1;
            show '/display/entry';
        },
        on '*/*' => run {
            my ($page, $op) = ($1, $2);
            my $item = get('model')->load($page) or next_rule;

            set item => $item;
            set page => $page;
            set op   => $op;

            show "/display/$op";
        },
        on '*' => run { dispatch "$1/view" },
        on ''  => show '/display/list',
    ];
    under qr{logs/(\d+)} => [
        when { $1 > 100 } => show '/error',
        set model => 'MyApp::Model::Log',
        run { dispatch "/wiki/LogPage-$1" },
    ];
    # ... more rules ...

DESCRIPTION

Generally, this is not the place to be performing model and user specific access control checks or updating your database based on what the user has sent in. You want to do that in your model classes. (Well, we want you to do that, but you're free to ignore our advice).

The Dispatcher runs rules in several stages:

before

before rules are run before Jifty evaluates actions. They're the perfect place to enable or disable Jifty::Actions using "allow" in Jifty::API and "deny" in Jifty::API or to completely disallow user access to private component templates such as the _elements directory in a default Jifty application. They're also the right way to enable Jifty::LetMe actions.

You can entirely stop processing with the "redirect", "tangent" and "abort" directives, though "after" rules will still run.

on

on rules are run after Jifty evaluates actions, so they have full access to the results actions users have performed. They're the right place to set up view-specific objects or load up values for your templates.

Dispatcher directives are evaluated in order until we get to either a "show", "redirect", "tangent" or "abort".

after

after rules let you clean up after rendering your page. Delete your cache files, write your transaction logs, whatever.

At this point, it's too late to "show", "redirect", "tangent" or "abort" page display.

"Jifty::Dispatcher" is intended to replace all the autohandler, dhandler and "index.html" boilerplate code commonly found in Mason applications, but there's nothing stopping you from using those features in your application when they're more convenient.

Each directive's code block runs in its own scope, but all share a common $Dispatcher object.

Plugins and rule ordering

    before plugin NAME =>
        RULE(S);
    
    after plugin NAME =>
        RULE(S);

    after app,
        RULE(S)

"NAME" may either be a string, which must match the plugin name exactly, or a regular expression, which is matched against the plugin name. The rule will be placed at the first boundary that it matches -- that is, given a "before plugin qr/^Jifty::Plugin::Auth::/" and both a "Jifty::Plugin::Auth::Basic" and a "Jifty::Plugin::Auth::Complex", the rules will be placed before the first.

"after app" inserts the following "RULES" after the application's dispatcher rules, and is identical to, but hopefully clearer than, "after plugin Jifty => RULES".

"RULES" may either be a single "before", "on", "under", or "after" rule to change the ordering of, or an array reference of rules to reorder.

Data your dispatch routines has access to

Things your dispatch routine might do

    use Jifty::Dispatcher -base;

    require MyApp::Dispatcher;
    MyApp::Dispatcher->handle_request;

    after '/some/path/*' => run {
        return if already_run;
        # ...
    };