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