1CGI::Application::PlugiUns:e:rMeCsosnatgreiSbtuatcekdC(G3PI)e:r:lApDpolciucmaetnitoant:i:oPnlugin::MessageStack(3)
2
3
4

NAME

6       CGI::Application::Plugin::MessageStack - A message stack for your
7       CGI::Application
8

VERSION

10       Version 0.34
11

SYNOPSIS

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
16        use CGI::Application::Plugin::Session;
17        use CGI::Application::Plugin::MessageStack;
18
19        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
26        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
36        sub cgiapp_init {
37          # setup your session object as usual...
38        }
39
40       Meanwhile, in your (HTML::Template) template code:
41
42        ...
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
60       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
64       Here's a quick TT example:
65
66        <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
81       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
86        sub start {
87            my $self = shift;
88            my $session = $self->session;
89            return $self->tt_process( 'output.tt' );
90        }
91
92       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
97       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

DESCRIPTION

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
109       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
113       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
121       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
126       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
131       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

FUNCTIONS

136   push_message
137        $self->push_message(
138            -scope          => 'mainpage',
139            -message        => 'Your listing has been updated',
140            -classification => 'INFO',
141          );
142
143       You provide a hash to the push_message() method with three possible
144       keys:
145
146       ·   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
149       ·   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
153       ·   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
157       The scope & classification keys are optional.  If you don't provide a
158       scope, it will assume a global presence.
159
160   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
166       If you want to take a gander at the message stack data structure, you
167       can use this method.
168
169       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
173       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
177   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
183       Pops off the last message from the stack and returns it.  Note that
184       this just returns the -message part.
185
186       You can pop off an exact message, given a hash parameters, using the
187       same keys as specified in the push_message() method.
188
189       Otherwise, it will pop off the message, given the current runmode and
190       the last message added.
191
192   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
198       Clears the message stack.
199
200       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
204       If you specify a scope, it will clear any messages that are either
205       global or match that scope
206
207       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
211       If you specify both, it will combine both that logic in an AND fashion.
212
213   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
222       There is a configuration option that you, as the developer can specify:
223
224       ·   -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
229       ·   -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
236       ·   -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
243            <!-- TMPL_LOOP NAME="MyOwnLoopName" -->
244            ...
245            <!-- /TMPL_LOOP -->
246
247       ·   -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
252            [ { 'MyOwnMessageName' => 'this is just a test' }, ... ]
253
254           instead of:
255
256            [ { '-message' => 'this is just a test' }, ... ]
257
258           Likewise, your templates will need to use your parameter name:
259
260            <!-- TMPL_LOOP NAME="MyOwnLoopName" -->
261              Here's the message: <!-- TMPL_VAR NAME="MyOwnMessageName" -->
262            <!-- /TMPL_LOOP -->
263
264       ·   -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
270            [ { 'MyOwnClassificationName' => 'ERROR', 'MyOwnMessageName' => 'this is just a test' }, ... ]
271
272           instead of:
273
274            [ { '-classification' => 'ERROR', '-message' => 'this is just a test' }, ... ]
275
276           Likewise, your templates will need to use your parameter name:
277
278            <!-- 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

AUTHOR

285       Jason Purdy, "<Jason@Purdy.INFO>"
286

SEE ALSO

288       CGI::Application and CGI::Application::Plugin::Session
289

BUGS

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
298       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

ACKNOWLEDGEMENTS

304       Thanks to the guys on the #cgiapp channel
305
307       Copyright 2005 Jason Purdy, all rights reserved.
308
309       This program is free software; you can redistribute it and/or modify it
310       under the same terms as Perl itself.
311
312
313
314perl v5.30.1                      2020C-G0I1:-:2A9pplication::Plugin::MessageStack(3)
Impressum