NAME

CGI::Application::Plugin::MessageStack

VERSION

0.01

SYNOPSIS

use CGI::Application::Plugin::Session;
use CGI::Application::Plugin::MessageStack;

sub mainpage {
  my $self = shift;
  my $template = $self->load_tmpl( 'mainpage.TMPL' );
  # ...
  $template->output;
}

sub process {
  my $self = shift;
  $self->push_message(
      -scope          => 'mainpage',
      -message        => 'Your listing has been updated',
      -classification => 'INFO',
    );
  $self->forward( 'mainpage' );
}

sub cgiapp_init {
  # setup your session object as usual...
}

Meanwhile, in your (HTML::Template) template code:

...
<style type="text/css">
  .INFO {
    font-weight: bold;
  }
  .ERROR {
    color: red;
  }
</style>
...
<h1>Howdy!</h1>
<!-- TMPL_LOOP NAME="__CAP_Messages" -->
  <div class="<!-- TMPL_VAR NAME="classification" -->">
    <!-- TMPL_VAR NAME="message" -->
  </div>
<!-- /TMPL_LOOP -->
...

You're using Template::Toolkit? Ok:

Cees?

Using HTDot? Ok:

HTDot is 100% backwards-compatible with regular HTML::Template, so see above :)
-- RhesaRozendaal

DESCRIPTION

This plugin NEEDS a session object to tuck away the message(s). So please use this in conjunction with CGI::Application::Plugin::Session.

This plugin hooks into cgiapp's load_tmpl method and if you've pushed any messages in the stack, will automatically add the message parameters.

METHODS

push_message()

$self->push_message(
    -scope          => 'mainpage',
    -message        => 'Your listing has been updated',
    -classification => 'INFO',
  );

You provide a hash to the push_message() method with three possible keys:

message - a text message. You can put HTML in there - just make sure you don't use the ESCAPE=HTML in your HTML::Template code
scope - which runmode(s) can this message appear? If you want to specify just one, use a scalar assignment. Otherwise, use an array reference with the list of runmodes.
classification - a simple scalar name representing the classification of your message (i.e. 'ERROR', 'WARNING' ... )

The scope & classification keys are optional. If you don't provide a scope, it will assume a global presence.

messages()

my @messages = $self->messages();
my @messages = $self->messages( -scope => 'mainpage' );
my @messages = $self->messages( -scope => 'mainpage', -classification => 'ERROR' );
my @messages = $self->messages( -classification => 'ERROR' );

If you want to take a gander at the message stack data structure, you can use this method.

Optionally, you can use a hash parameters to get a slice of the messages, using the same keys as specified in the push_message() method.

pop_message()

my $message = $self->pop_message();
my $message = $self->pop_message( -scope => 'mainpage' );
my $message = $self->pop_message( -scope => 'mainpage', -classification => 'WARNING' );
my $message = $self->pop_message( -classification => 'ERROR' );

Pops off the last message from the stack and returns it.

You can pop off an exact message, given a hash parameters, using the same keys as specified in the push_message() method.

Otherwise, it will pop off the message, given the current runmode and the last message added.

clear_messages()

$self->clear_messages();
$self->clear_messages( -scope => 'mainpage' );
$self->clear_messages( -scope => 'mainpage', -classification => 'ERROR' );
$self->clear_messages( -classification => 'ERROR' );

Clears the message stack. This method will be called automatically when the Plugin puts it into your template.

Optionally, you can clear particular slices of the message stack, given a hash parameters, using the same keys as specified in the push_message() method.

AUTHOR

Jason Purdy <Jason@Purdy.INFO>

ACKNOWLEDGEMENTS

Thanks to the guys on the #cgiapp channel!

BUGS

Please report any bugs or feature requests to bug-cgi-application-plugin-messagestack@rt.cpan.org, or through the web interface at http://rt.cpan.org. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.