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