/ 
Catalyst-Plugin-SimpleMessage-0.0.1
River stage zero No dependents
/ Catalyst::Plugin::SimpleMessage

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.