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