NAME

Catalyst::Plugin::MessageStack - A Catalyst plugin for gracefully handling messaging (and more) that follows the Post/Redirect/Get pattern.

VERSION

version 0.03

DESCRIPTION

This plugin offers persistent messaging (requiring Catalyst::Plugin::Session or something with a compatible API, and preferably a model based on Data::Manager.

The messaging gracefully handles any redirects (so you can happily use the recommended Post/Redirect/Get pattern. See http://en.wikipedia.org/wiki/Post/Redirect/Get for more information.

The Message::Stack is always accessible via the stash while the view is rendered, regardless of redirects.

METHODS

message($message)

Add a new message to the stack. The message can be a simple scalar value, which is created as an informational type. Alternatively, if you want a different type attriute, simply call $c->message in this form:

    $c->message({
        type    => 'error', # Corresponds to a message stack 'level'
        message => 'Your message string here'
    });

Called without any arguments, it simply returns the current message stack.

You can also pass in a Message::Stack::Message

    $c->message(
        Message::Stack::Message->new(
            scope => 'some_scope', level => 'info',
            msgid => 'some msg id'
        )
    );

has_messages

Returns a true value if there are messages present in the stack. If you want to limit by scope, pass in the scope and it checks that.

CONFIGURATION

For message storage, there are two configuration options: stash_key and flash_key. This define the locations in the stash to place the messages.

To define the default type of message set the 'default_type' configuration key.

Use is very simple:

    $c->message('This is a message of the default type');
    $c->message({ type => 'error', message => 'This is an error message' });

Configuring is relatively straight forward, here are the defaults:

    package MyApp;

    use Catalyst qw/MessageStack/;

    __PACKAGE__->config({
        'Plugin::MessageStack' => {
            stash_key    => 'messages',
            flash_key    => '_message',
            default_type => 'warning',
            model        => 'DataManager', # optional, but will merge messages
        }
    });

INTEGRATION WITH DATA::MANAGER

Data::Manager is an optional tool that this plugin plays well with. If you have a Data::Manager model in your application, set the model configuration key.

Then, the messages that happen between Data::Manager and your application are unified and merged into the same stack.

Additionally, the results from Data::Manager are preserved so you can continue the Post/Redirect/Get pattern.

What this allows is very simple controller actions that look like:

    sub handle_post : Local {
        my ( $self, $c ) = @_;

        # Always redirect, set it here.
        $c->res->redirect( $c->uri_for_action('/my/object') );

        my $results = $c->model('DataManager')
            ->verify('my_scope', $c->req->params);

        unless ( $results->success ) {
            $c->message({
                type => 'error',
                message => 'You made a mistake on the form, fix it!'
            });
            $c->detach; # Halt! Go no further.
        }

        # Pass the valid and vetted values to your model:
        $c->model('MyModel')->do_stuff({ $results->valid_values });
        $c->message('Everything went swimmingly. Rejoice!');
    }

If results fail and you integrate Data::Manager, the results are present as well as messaging (defined by the scope, in the case above that is my_scope).

Results are stored in the stash, keyed by scope. It looks something like this:

    $c->stash->{results} = {
        my_scope => Data::Verifier::Results->new(
                ... # results, the fields and what not ...
            )
    };

You have two distinct options in accessing the values. Either the originally supplied values or the values after filtering, munging, coercion from Data::Verifier. The two methods are listed below:

    $c->stash->{results}->{$scope}->get_original_value($field);
    $c->stash->{results}->{$scope}->get_value($field);

AUTHOR

J. Shirley <jshirley@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Cold Hard Code, LLC.

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 Catalyst::Plugin::MessageStack

perl -MCPAN -e shell
install Catalyst::Plugin::MessageStack