special_chars: ø, Ø und λ ergänzt
[kivitendo-erp.git] / 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