1CGI::Application::PlugiUns:e:rMeCsosnatgreiSbtuatcekdC(G3PI)e:r:lApDpolciucmaetnitoant:i:oPnlugin::MessageStack(3)
2
6 CGI::Application::Plugin::MessageStack - A message stack for your
7 CGI::Application
8
10 Version 0.34
11
13 This plugin gives you a few support methods that you can call within
14 your cgiapp to pass along messages between requests for a given user.
15 use CGI::Application::Plugin::Session;
17 use CGI::Application::Plugin::MessageStack;
18 sub mainpage {
20 my $self = shift;
21 my $template = $self->load_tmpl( 'mainpage.TMPL', 'die_on_bad_params' => 0 );
22 # ...
23 $template->output;
24 }
25 sub process {
27 my $self = shift;
28 $self->push_message(
29 -scope => 'mainpage',
30 -message => 'Your listing has been updated',
31 -classification => 'INFO',
32 );
33 $self->forward( 'mainpage' );
34 }
35 sub cgiapp_init {
37 # setup your session object as usual...
38 }
39 Meanwhile, in your (HTML::Template) template code:
41 ...
43 <style type="text/css">
44 .INFO {
45 font-weight: bold;
46 }
47 .ERROR {
48 color: red;
49 }
50 </style>
51 ...
52 <h1>Howdy!</h1>
53 <!-- TMPL_LOOP NAME="CAP_Messages" -->
54 <div class="<!-- TMPL_VAR NAME="classification" -->">
55 <!-- TMPL_VAR NAME="message" -->
56 </div>
57 <!-- /TMPL_LOOP -->
58 ...
59 It's a good idea to turn off 'die_on_bad_params' in HTML::Template - in
61 case this plugin tries to put in the parameters and they're not
62 available in your template.
63 Here's a quick TT example:
65 <style type="text/css">
67 .INFO {
68 font-weight: bold;
69 }
70 .ERROR {
71 color: red;
72 }
73 </style>
74 ...
75 <h1>Howdy!</h1>
76 [% FOREACH CAP_Messages %]
77 <div class="[% classification %]">[% message %]</div>
78 [% END %]
79 ...
80 If you use TT, I recommend using CAP-TT and a more recent version
82 (0.09), which supports cgiapp's load_tmpl hook and then this plugin
83 will automatically supply TT with the relevant messages. Your runmode
84 could be this simple:
85 sub start {
87 my $self = shift;
88 my $session = $self->session;
89 return $self->tt_process( 'output.tt' );
90 }
91 I don't have the experience to weigh in on how you'd do this with other
93 templates (HTDot, Petal), but basically, this plugin will put in a loop
94 parameter called 'CAP_Messages'. Within each element of that loop,
95 you'll have two tags, 'classification' and 'message'.
96 NOTE: I have broken backwards compatibility with this release (0.30)
98 and the loop parameter's default name is now 'CAP_Messages'. If you
99 used the old __CAP_Messages or want to use another name, feel free to
100 use the capms_config to override the "-loop_param_name".
101
103 This plugin by default needs a session object to tuck away the
104 message(s). It's recommended that you use this in conjunction with
105 CGI::Application::Plugin::Session. You can opt to not have the
106 messages persist and thereby, not use CAP-Session by using the
107 "-dont_use_session" option in the "capms_config" method.
108 This plugin hooks into cgiapp's load_tmpl method and if you've pushed
110 any messages in the stack, will automatically add the message
111 parameters.
112 In the functions, there are scope & classification keys and when
114 they're used for either display or your API purposes (clearing,
115 pop'ing, etc), the classification is an exclusive specification.
116 Meaning, if you ask for messages with the 'ERROR' classification, it
117 will only deal with messages that you've pushed in with the 'ERROR'
118 classification. Any messages that have no classification aren't
119 included.
120 The scope key is not exclusive, meaning that if you ask for messages
122 with a 'mainpage' scope, it will deal with messages that you've pushed
123 with that scope as well as any messages that you've pushed in without a
124 scope.
125 If you use both scope & classification, it blends both of those rules,
127 first getting all matching messages with the same classification and
128 then filtering out messages that are scoped and don't match the scope
129 you're looking for.
130 This logic may change as I get feedback from more saavy developers.
132 What we may end up doing is have a plugin configuration where you can
133 dictate the logic that's used.
134
136 push_message
137 $self->push_message(
138 -scope => 'mainpage',
139 -message => 'Your listing has been updated',
140 -classification => 'INFO',
141 );
142 You provide a hash to the push_message() method with three possible
144 keys:
145 · message - a text message. You can put HTML in there - just make
147 sure you don't use the ESCAPE=HTML in your HTML::Template code
148 · scope - which runmode(s) can this message appear? If you want to
150 specify just one, use a scalar assignment. Otherwise, use an array
151 reference with the list of runmodes.
152 · classification - a simple scalar name representing the
154 classification of your message (i.e. 'ERROR', 'WARNING' ... ).
155 This is very useful for CSS styles (see template example above).
156 The scope & classification keys are optional. If you don't provide a
158 scope, it will assume a global presence.
159 messages
161 my @messages = $self->messages();
162 my @messages = $self->messages( -scope => 'mainpage' );
163 my @messages = $self->messages( -scope => 'mainpage', -classification => 'ERROR' );
164 my @messages = $self->messages( -classification => 'ERROR' );
165 If you want to take a gander at the message stack data structure, you
167 can use this method.
168 Optionally, you can use a hash parameters to get a slice of the
170 messages, using the same keys as specified in the push_message()
171 method.
172 It will return an array reference of the matching messages or 'undef',
174 if there's either no messages in the stack or no messages that match
175 your specification(s).
176 pop_message
178 my $message = $self->pop_message();
179 my $message = $self->pop_message( -scope => 'mainpage' );
180 my $message = $self->pop_message( -scope => 'mainpage', -classification => 'WARNING' );
181 my $message = $self->pop_message( -classification => 'ERROR' );
182 Pops off the last message from the stack and returns it. Note that
184 this just returns the -message part.
185 You can pop off an exact message, given a hash parameters, using the
187 same keys as specified in the push_message() method.
188 Otherwise, it will pop off the message, given the current runmode and
190 the last message added.
191 clear_messages
193 $self->clear_messages();
194 $self->clear_messages( -scope => 'mainpage' );
195 $self->clear_messages( -scope => 'mainpage', -classification => 'ERROR' );
196 $self->clear_messages( -classification => 'ERROR' );
197 Clears the message stack.
199 Optionally, you can clear particular slices of the message stack, given
201 a hash parameters, using the same keys as specified in the
202 push_message() method.
203 If you specify a scope, it will clear any messages that are either
205 global or match that scope
206 If you specify a classification, it will clear any messages that have
208 that classification (but not any messages that don't have any
209 classification).
210 If you specify both, it will combine both that logic in an AND fashion.
212 capms_config
214 $self->capms_config(
215 -automatic_clearing => 1,
216 -dont_use_session => 1,
217 -loop_param_name => 'MyOwnLoopName',
218 -message_param_name => 'MyOwnMessageName',
219 -classification_param_name => 'MyOwnClassificationName',
220 );
221 There is a configuration option that you, as the developer can specify:
223 · -automatic_clearing: By default, this is turned off. If you
225 override it with a true value, it will call clear_messages()
226 automatically after the messages are automatically put into
227 template.
228 · -dont_use_session: This will override this Plugin's dependence on
230 CGI::Application::Plugin::Session and instead, temporarily store
231 the message data such that it will be available to templates within
232 the same web request, but no further. If you're running your
233 cgiapp under a persistent state (mod_perl), we'll also make sure
234 your messages are gone by the end of the request.
235 · -loop_param_name: This will override the default __CAP_Messages (or
237 CAP_Messages for TT users) name for the loop of messages, which is
238 only used for the "load_tmpl" callback. Meaning, this
239 configuration will only impact your template code. So if you use
240 the 'MyOwnLoopName' above, then your template code (for
241 HTML::Template users) should look like:
242 <!-- TMPL_LOOP NAME="MyOwnLoopName" -->
244 ...
245 <!-- /TMPL_LOOP -->
246 · -message_param_name: This will override the default '-message' in
248 both the template code as well as the keys in each hashref of the
249 arrayref that's returned by the messages() function. So a call to
250 messages() may return:
251 [ { 'MyOwnMessageName' => 'this is just a test' }, ... ]
253 instead of:
255 [ { '-message' => 'this is just a test' }, ... ]
257 Likewise, your templates will need to use your parameter name:
259 <!-- TMPL_LOOP NAME="MyOwnLoopName" -->
261 Here's the message: <!-- TMPL_VAR NAME="MyOwnMessageName" -->
262 <!-- /TMPL_LOOP -->
263 · -classification_param_name: Just like the "-message_param_name"
265 parameter - this will override the default '-classification' key in
266 both the template code as well as the keys in each hashref of the
267 arrayref that's returned by the messages() function. So a call to
268 messages() may return:
269 [ { 'MyOwnClassificationName' => 'ERROR', 'MyOwnMessageName' => 'this is just a test' }, ... ]
271 instead of:
273 [ { '-classification' => 'ERROR', '-message' => 'this is just a test' }, ... ]
275 Likewise, your templates will need to use your parameter name:
277 <!-- TMPL_LOOP NAME="MyOwnLoopName" -->
279 <div class="<!-- TMPL_VAR NAME="MyOwnClassificationName" -->">
280 Here's the message: <!-- TMPL_VAR NAME="MyOwnMessageName" -->
281 </div>
282 <!-- /TMPL_LOOP -->
283
285 Jason Purdy, "<Jason@Purdy.INFO>"
286
288 CGI::Application and CGI::Application::Plugin::Session
289
291 Please report any bugs or feature requests to
292 "bug-cgi-application-plugin-messagestack@rt.cpan.org", or through the
293 web interface at
294 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CGI-Application-Plugin-MessageStack>.
295 I will be notified, and then you'll automatically be notified of
296 progress on your bug as I make changes.
297 I suspect that this code could use some expert guidance. I hacked it
299 together and I'd hate to think that it would be responsible for slowing
300 templates down. Please feel free to submit patches, guiding comments,
301 etc.
302
304 Thanks to the guys on the #cgiapp channel
305
307 Copyright 2005 Jason Purdy, all rights reserved.
308 This program is free software; you can redistribute it and/or modify it
310 under the same terms as Perl itself.
311perl v5.28.1 2019C-G0I2:-:0A2pplication::Plugin::MessageStack(3)