SL/Helper/Flash.pm

   1 package SL::Helper::Flash;
   2
   3 use strict;
   4
   5 require Exporter;
   6 our @ISA       = qw(Exporter);
   7 our @EXPORT    = qw(flash flash_later);
   8 our @EXPORT_OK = qw(render_flash);
   9
  10 #
  11 # public functions
  12 #
  13
  14 sub flash {
  15   $::form->{FLASH} = _store_flash($::form->{FLASH}, @_);
  16 }
  17
  18 sub flash_later {
  19   $::auth->set_session_value(FLASH => _store_flash($::auth->get_session_value('FLASH'), @_))->save_session();
  20 }
  21
  22 sub render_flash {
  23   return $::form->parse_html_template('common/flash');
  24 }
  25
  26 #
  27 # private functions
  28 #
  29
  30 sub _store_flash {
  31   my $store    = shift || { };
  32   my $category = shift;
  33   $category    = 'info' if $category eq 'information';
  34
  35   $store                ||= { };
  36   $store->{ $category } ||= [ ];
  37   push @{ $store->{ $category } }, @_;
  38
  39   return $store;
  40 }
  41
  42 1;
  43
  44 __END__
  45
  46 =head1 NAME
  47
  48 SL::Helper::Flash - helper functions for storing messages to be
  49 displayed to the user
  50
  51 =head1 SYNOPSIS
  52
  53 The flash is a store for messages that should be displayed to the
  54 user. Each message has a category which is usually C<information>,
  55 C<warning> or C<error>. The messages in each category are grouped and
  56 displayed in colors appropriate for their severity (e.g. errors in
  57 red).
  58
  59 Messages are rendered either by calling the function C<render_flash>
  60 or by including the flash sub-template from a template with the
  61 following code:
  62
  63   [%- INCLUDE 'common/flash.html' %]
  64
  65 =head1 EXPORTS
  66
  67 The functions L</flash> and L</flash_later> are always exported.
  68
  69 The function L</render_flash> is only exported upon request.
  70
  71 =head1 FUNCTIONS
  72
  73 =over 4
  74
  75 =item C<flash $category, @messages>
  76
  77 Stores messages for the given category. The category can be either
  78 C<information>, C<warning> or C<error>. C<info> can also be used as an
  79 alias for C<information>.
  80
  81 =item C<flash_later $category, @messages>
  82
  83 Stores messages for the given category for the next request. The
  84 category can be either C<information>, C<warning> or C<error>. C<info>
  85 can also be used as an alias for C<information>.
  86
  87 The messages are stored in the user's session and restored upon the
  88 next request. Can be used for transmitting information over HTTP
  89 redirects.
  90
  91 =item C<render_flash>
  92
  93 Outputs the flash message by parsing the C<common/flash.html> template
  94 file.
  95
  96 This function is not exported by default.
  97
  98 =back
  99
 100 =head1 AUTHOR
 101
 102 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>
 103
 104 =cut