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     ||  do {
  50       require Carp;
  51       croak("invalid category '$c' for flash");
  52     };
  53 }
  54
  55 1;
  56
  57 __END__
  58
  59 =head1 NAME
  60
  61 SL::Helper::Flash - helper functions for storing messages to be
  62 displayed to the user
  63
  64 =head1 SYNOPSIS
  65
  66 The flash is a store for messages that should be displayed to the
  67 user. Each message has a category which is usually C<information>,
  68 C<warning> or C<error>. The messages in each category are grouped and
  69 displayed in colors appropriate for their severity (e.g. errors in
  70 red).
  71
  72 Messages are rendered either by calling the function C<render_flash>
  73 or by including the flash sub-template from a template with the
  74 following code:
  75
  76   [%- INCLUDE 'common/flash.html' %]
  77
  78 =head1 EXPORTS
  79
  80 The functions L</flash> and L</flash_later> are always exported.
  81
  82 The function L</render_flash> is only exported upon request.
  83
  84 =head1 FUNCTIONS
  85
  86 =over 4
  87
  88 =item C<flash $category, @messages>
  89
  90 Stores messages for the given category. The category can be either
  91 C<information>, C<warning> or C<error>. C<info> can also be used as an
  92 alias for C<information>.
  93
  94 =item C<flash_later $category, @messages>
  95
  96 Stores messages for the given category for the next request. The
  97 category can be either C<information>, C<warning> or C<error>. C<info>
  98 can also be used as an alias for C<information>.
  99
 100 The messages are stored in the user's session and restored upon the
 101 next request. Can be used for transmitting information over HTTP
 102 redirects.
 103
 104 =item C<render_flash>
 105
 106 Outputs the flash message by parsing the C<common/flash.html> template
 107 file.
 108
 109 This function is not exported by default.
 110
 111 =back
 112
 113 =head1 AUTHOR
 114
 115 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>
 116
 117 =cut