NAME

Catalyst::Plugin::SimpleMessage - Handle passing multiple types of messages between screens of a web application using session or stash.

SYNOPSIS

In MyApp.pm:

    use Catalyst qr/
        SimpleMessage
    /;
 

In controller where you want to save a message for display on the next page (here, once the "delete" action taken is complete, we are redirecting to a "list" page to show the status [we don't want to leave the delete action in the browser URL]):

   $c->response->redirect($c->uri_for($self->action_for('list'),
        { $c->sm_get_token_param() => $c->sm_session({ message => 'Deleted widget', type => 'success' }) }));
 

Or, to display an error message:

   $c->response->redirect($c->uri_for($self->action_for('list'),
        { $c->sm_get_token_param() => $c->sm_session({ message => 'Error deleting widget', type => 'danger' }) }));

If you do not need a redirect, you can pass the message using stash:

    $c->sm_stash({ message => 'Your email was not confirmed yet', type => 'warning' });
 

And, to display the output (here using Template Toolkit and Twitter Bootstrap):

    ...
    [% FOREACH item IN c.sm_get() %]
        <span class="alert alert-[% item.type %]">[% item.message %]</span>
    [% END %]
    ...
 
 

DESCRIPTION

There are a number of ways people commonly use to pass messages between screens in a web application.

• Using $c->flash: The "flash" feature does provide a mechanism where the application can redirect to an appropriate URL, but it can also lead to a race condition where the wrong status message is displayed in the wrong browser window or tab (and can therefore be confusing to the users of your application).

• Query parameters in the URL: This suffers from issues related to long/ugly URLs and leaves the message displayed even after a browser refresh.

This plugin attempts to address these issues through the following mechanisms:

• Stores messages in the $c->session so that the application is free to redirect to the appropriate URL after an action is taken.

• Associates a random 8-digit "token" with each message, so it's completely unambiguous what message should be shown in each window/tab.

• Only requires that the token (not the full message) be included in the redirect URL.

• Automatically removes the message after the first time it is displayed. That way, if users hit refresh in their browsers they only see the messages the first time.

METHODS

sm_get_messages

Returns an array ref with messages sent through $c->sm_session and $c->sm_stash. You can send messages through $c->sm_session and $c->sm_stash and both will be available, messages sent throught stash are available only for the current request.

sm_get

Alias for sm_get_messages

sm_get_token_param

Return the token_param name. Default is "__sm"

sm_set_messages_session

Send messages through the session and return a token. You can send multiple messages:

    my $token = $c->sm_session({ message => 'Product added with success', type => 'success' }, { message => 'You must define a price before selling', type => 'warning' });
    $c->response->redirect($c->uri_for($self->action_for('list'), { $c->sm_get_token_param() => $token }));

sm_session

Alias for sm_set_messages_session

sm_set_messages_stash

Send messages through the stash. You can send multiple messages:

    my $token = $c->sm_stash({ message => 'You account is active', type => 'info' }, { message => 'You do not have credit', type => 'danger' });

Messages sent through stash will be available only for the current request.

sm_stash

Alias for sm_set_messages_stash

CONFIGURABLE OPTIONS

session_prefix

The location inside $c->session where messages will be stored. Defaults to "__sm".

stash_prefix

The location inside $c->stash where messages will be stored. Defaults to "__sm".

token_param

The name of the URL param that holds the token on the page where you want to retrieve/display the status message. Defaults to "__sm".

Configuration Example

Here is a quick example showing how Catalyst::Plugin::SimpleMessage can be configured

    # Configure Catalyst::Plugin::SimpleMessage
    __PACKAGE__->config(
        'Plugin::SimpleMessage' => {
            session_prefix       => '__sm',
            stash_prefix         => '__sm',
            token_param          => '__sm'
        }
    );
 
 

INTERNALS

Note: You normally shouldn't need any of the information in this section to use Catalyst::Plugin::SimpleMessage.

__sm_config

Handles default values for config and lets them be overriden from the MyApp configuration.

CODE

Github

    https://github.com/geovannyjs/Catalyst-Plugin-SimpleMessage
 

AUTHOR

Geovanny Junio, geovannyjs@gmail.com

This module was based on Catalyst::Plugin::StatusMessage. Many thanks to Kennedy Clark (HKCLARK).

COPYRIGHT

This library is free software. You can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Catalyst::Plugin::SimpleMessage

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