view release on metacpan or  search on metacpan

README.mkdn  view on Meta::CPAN

# 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](http://search.cpan.org/perldoc?Catalyst::Plugin::Session)
or something with a compatible API, and preferably a model based on
[Data::Manager](http://search.cpan.org/perldoc?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](http://search.cpan.org/perldoc?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](http://search.cpan.org/perldoc?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](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
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({