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


version 0.03


This plugin offers persistent messaging (requiring [Catalyst::Plugin::Session](http://search.cpan.org/perldoc?Catalyst::Plugin::Session)
or something with a compatible API, and preferably a model based on

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](http://search.cpan.org/perldoc?Message::Stack) is always accessible via the stash while the view is
rendered, regardless of redirects.


## 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:

        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](http://search.cpan.org/perldoc?Message::Stack::Message)

            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.


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/;

        'Plugin::MessageStack' => {
            stash_key    => 'messages',
            flash_key    => '_message',
            default_type => 'warning',
            model        => 'DataManager', # optional, but will merge messages


[Data::Manager](http://search.cpan.org/perldoc?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

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 ) {
                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](http://search.cpan.org/perldoc?Data::Verifier).  The two methods are listed below:



J. Shirley <jshirley@cpan.org>


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.