/ 
CGI-Application-Plugin-Flash-0.01
River stage zero No dependents
/ CGI::Application::Plugin::Flash

NAME

CGI::Application::Plugin::Flash - Flash ...

SYNOPSIS

use CGI::Application::Plugin::Flash;

sub cgiapp_init
{
    my $self = shift;

    $self->flash_config(
        session_key  => 'FLASH',
        auto_cleanup => 1,
    );

    # ...
}

sub some_runmode
{
    my $self = shift;

    # Set a message in the flash
    $self->flash(info => 'Welcome back!');

    # Alternatively
    my $flash = $self->flash;
    $flash->set(info => "Welcome back!");

    # Set a message in the flash that only lasts for the duration of
    # the current request.
    $self->flash->now(test => 'Only available for this request');

    # ...
}

DESCRIPTION

This CGI::Application plugin implements a Flash object. A flash is session data with a specified life cycle. When you put something into the flash it stays then until the end of the next request. This allows you to use it for storing messages that can be accessed after a redirect, but then are automatically cleaned up.

Since the flash data is accessible from the next request a method of persistance is required. We use a session for this so the CGI::Application::Plugin::Session is required. The flash is stored in the session using two keys, one for the data and one for the list of keys that are to be kept.

EXPORTED METHODS

The following methods are exported into your CGI::Application base class and can be used from within your runmodes.

flash

The flash is implemented as a singleton so the same object will be returned on subsequent calls. The first time this is called a new flash object is created using data from the session.

This method can be called in the following manners:

$self->flash()

When no arguments are specified the flash object is returned. Use this form when you want to use a more advanced feature of the flash. See the documentation below for the flash object.

$self->flash('KEY')

Retrieve the data from the flash. See get for more details.

$self->flash('KEY' => @data)

Set the data in the flash. See set for more details.

flash_config

Call this method to set or get the configuration for the flash. Setting the configuration must be done before the first time you call flash, otherwise the configuration will not take effect. A good place to put this call is in your cgiapp_init method.

When setting the configuration values specify a list of key and value pairs. The possible values are documented in the "new" in CGI::Session::Flash documentation.

When called with no parameters, the current configuration will be returned as either a hashref or a list depending on the context.

USING FROM A TEMPLATE

This is an example of how you could use the flash in a template to display some various informational notices.

[% FOR type IN [ 'error', 'warning', 'info' ] -%]
  [% IF c.flash.has_key(type) -%]
  <div class="flash [% type %]">,
    <strong>[% type %] messages</strong>
    <ul>
    [% FOREACH message in c.flash(type) -%]
      <li>[% message | h %]</li>
    [% END -%]
    </ul>
  </div>
  [% END -%]
[% END -%]

A simpler example is:

[% c.flash('key') %]

FLASH OBJECT

While the basic use of the flash is getting and setting data, which we provide simple wrapper for, there may be times when you need to access the full power of the flash object.

Consult the CGI::Session::Flash documentation for details on its usage.

BUGS

Please report any bugs or feature requests to bug-cgi-application-plugin-flash at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CGI-Application-Plugin-Flash. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

ACKNOWLEDGEMENTS

The concept and name of this plugin was inspired by the Ruby on Rails framework.

SEE ALSO

CGI::Application, CGI::Application::Plugin::Session, CGI::Session::Flash

AUTHOR

Bradley C Bailey, <cap-flash at brad.memoryleak.org>

COPYRIGHT & LICENSE

Copyright 2008 Bradley C Bailey, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.