Debian Codegraph @

README

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