view release on metacpan or  search on metacpan

lib/Catalyst/Plugin/MessageStack.pm  view on Meta::CPAN

    return $ret unless defined $messages;

    if ( $messages->has_messages and $c->response->location) {
        $c->flash->{$flash_key}    = $messages;
        $c->keep_flash($flash_key);
        if ( $config->{model} ) {
            $c->flash->{$rflash_key} ||= $c->model($config->{model})->results;
            $c->keep_flash($rflash_key);
        }
    }
    return $ret;
}

1;

__END__
=pod

=head1 NAME

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

=head1 VERSION

version 0.03

=head1 DESCRIPTION

This plugin offers persistent messaging (requiring L<Catalyst::Plugin::Session>
or something with a compatible API, and preferably a model based on
L<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 L<Message::Stack> is always accessible via the stash while the view is
rendered, regardless of redirects.

=head1 METHODS

=head2 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<< $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 L<Message::Stack::Message>

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

=head2 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.

=head1 CONFIGURATION

For message storage, there are two configuration options: C<stash_key> and 
C<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
        }
    });

=head1 INTEGRATION WITH DATA::MANAGER

L<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({