1MasonX::Interp::WithCalUlsbearckCso(n3t)ributed Perl DocMuamseonntXa:t:iIonnterp::WithCallbacks(3)
2
3
4

NAME

6       MasonX::Interp::WithCallbacks - Mason callback support via
7       Params::CallbackRequest.
8

SYNOPSIS

10       In your Mason component:
11
12         % if (exists $ARGS{answer}) {
13         <p><b>Answer: <% $ARGS{answer} %></b></p>
14         % } else {
15         <form>
16           <p>Enter an epoch time: <input type="text" name="epoch_time" /><br />
17             <input type="submit" name="myCallbacker|calc_time_cb" value="Calculate" />
18           </p>
19         </form>
20         % }
21
22       In handler.pl:
23
24         use strict;
25         use MasonX::Interp::WithCallbacks;
26
27         sub calc_time {
28             my $cb = shift;
29             my $params = $cb->params;
30             my $val = $cb->value;
31             $params->{answer} = localtime($val || time);
32         }
33
34         my $ah = HTML::Mason::ApacheHandler->new
35           ( interp_class => 'MasonX::Interp::WithCallbacks',
36             callbacks => [ { cb_key  => 'calc_time',
37                              pkg_key => 'myCallbacker',
38                              cb      => \&calc_time } ]
39           );
40
41         sub handler {
42             my $r = shift;
43             $ah->handle_request($r);
44         }
45
46       Or, in a subclass of Params::Callback:
47
48         package MyApp::CallbackHandler;
49         use base qw(Params::Callback);
50         __PACKAGE__->register_subclass( class_key => 'myCallbacker' );
51
52         sub calc_time : Callback {
53             my $self = shift;
54             my $params = $self->params;
55             my $val = $cb->value;
56             $params->{answer} = localtime($val || time);
57         }
58
59       And then, in handler.pl:
60
61         # Load order is important here!
62         use MyApp::CallbackHandler;
63         use MasonX::Interp::WithCallbacks;
64
65         my $ah = HTML::Mason::ApacheHandler->new
66           ( interp_class => 'MasonX::Interp::WithCallbacks',
67             cb_classes => [qw(myCallbacker)] );
68
69         sub handler {
70             my $r = shift;
71             $ah->handle_request($r);
72         }
73
74       Or, just use MasonX::Interp::WithCallbacks directly:
75
76         use MyApp::CallbackHandler;
77         use MasonX::Interp::WithCallbacks;
78         my $interp = MasonX::Interp::WithCallbacks->new
79           ( cb_classes => [qw(myCallbacker)] );
80         $interp->exec($comp, %args);
81

DESCRIPTION

83       MasonX::Interp::WithCallbacks subclasses HTML::Mason::Interp in order
84       to provide a Mason callback system built on Params::CallbackRequest.
85       Callbacks may be either code references provided to the "new()"
86       constructor, or methods defined in subclasses of Params::Callback.
87       Callbacks are triggered either for every request or by specially named
88       keys in the Mason request arguments, and all callbacks are executed at
89       the beginning of a request, just before Mason creates and executes the
90       request component stack.
91
92       This module brings support for a sort of plugin architecture based on
93       Params::CallbackRequest to Mason. Mason then executes code before
94       executing any components. This approach allows you to carry out logical
95       processing of data submitted from a form, to affect the contents of the
96       Mason request arguments (and thus the %ARGS hash in components), and
97       even to redirect or abort the request before Mason handles it.
98
99       Much of the documentation here is based on that in
100       Params::CallbackRequest, although it prefers using HTML form fields for
101       its examples rather than Perl hashes. But see the
102       Params::CallbackRequest documentation for the latest on its interface.
103

JUSTIFICATION

105       Why would you want to do this? Well, there are a number of reasons.
106       Some I can think of offhand include:
107
108       Stricter separation of logic from presentation
109           Most application logic handled in Mason components takes place in
110           "<%init>" blocks, often in the same component as presentation
111           logic. By moving the application logic into Perl modules and then
112           directing Mason to execute that code as callbacks, you obviously
113           benefit from a cleaner separation of application logic and
114           presentation.
115
116       Widgitization
117           Thanks to their ability to preprocess arguments, callbacks enable
118           developers to develop easier-to-use, more dynamic widgets that can
119           then be used in any and all Mason component, or even with other
120           templating systems. For example, a widget that puts many related
121           fields into a form (such as a date selection widget) can have its
122           fields preprocessed by a callback (for example, to properly combine
123           the fields into a unified date field) before the Mason component
124           that responds to the form submission gets the data. See
125           Params::Callback for an example solution for this very problem.
126
127       Shared Memory
128           Callbacks are just Perl subroutines in modules, and are therefore
129           loaded at server startup time in a mod_perl environment. Thus the
130           memory they consume is all in the Apache parent process, and shared
131           by the child processes. For code that executes frequently, this can
132           be much less resource-intensive than code in Mason components,
133           since components are loaded separately in each Apache child process
134           (unless they're preloaded via the "preloads" parameter to the
135           HTML::Mason::Interp constructor).
136
137       Performance
138           Since they're executed before Mason creates a component stack and
139           executes the components, callbacks have the opportunity to short-
140           circuit the Mason processing by doing something else. A good
141           example is redirection. Often the application logic in callbacks
142           does its thing and then redirects the user to a different page.
143           Executing the redirection in a callback eliminates a lot of
144           extraneous processing that would otherwise be executed before the
145           redirection, creating a snappier response for the user.
146
147       Testing
148           Mason components are not easy to test via a testing framework such
149           as Test::Harness. Subroutines in modules, on the other hand, are
150           fully testable. This means that you can write tests in your
151           application test suite to test your callback subroutines.
152
153       And if those aren't enough reasons, then just consider this: Callbacks
154       are just way cool.
155

USAGE

157       MasonX::Interp::WithCallbacks uses Params::CallbackRequest for its
158       callback architecture, and therefore supports its two different types
159       of callbacks: those triggered by a specially named key in the Mason
160       request arguments hash, and those executed for every request.
161
162   Argument-Triggered Callbacks
163       Argument-triggered callbacks are triggered by specially named request
164       argument keys. These keys are constructed as follows: The package name
165       followed by a pipe character ("|"), the callback key with the string
166       "_cb" appended to it, and finally an optional priority number at the
167       end. For example, if you specified a callback with the callback key
168       "save" and the package key "world", a callback field might be added to
169       an HTML form like this:
170
171         <input type="button" value="Save World" name="world|save_cb" />
172
173       This field, when submitted to the Mason server, would trigger the
174       callback associated with the "save" callback key in the "world"
175       package. If such a callback hasn't been configured, then
176       Params::CallbackRequest will throw a
177       Params::CallbackReuest::Exception::InvalidKey exception. Here's how to
178       configure a functional callback when constructing your
179       MasonX::Interp::WithCallbacks object so that that doesn't happen:
180
181         my $interp = MasonX::Interp::WithCallbacks->new
182           ( callbacks => [ { pkg_key => 'world',
183                              cb_key  => 'save',
184                              cb      => \&My::World::save } ] );
185
186       With this configuration, the request argument created by the above HTML
187       form field will trigger the execution of the &My::World::save
188       subroutine.
189
190       Functional Callback Subroutines
191
192       Functional callbacks use a code reference for argument-triggered
193       callbacks, and Params::CallbackRequest executes them with a single
194       argument, a Params::Callback object. Thus, a callback subroutine will
195       generally look something like this:
196
197         sub foo {
198             my $cb = shift;
199             # Do stuff.
200         }
201
202       The Params::Callback object provides accessors to data relevant to the
203       callback, including the callback key, the package key, and the request
204       arguments (or parameters). It also includes "redirect()" and "abort()"
205       methods. See the Params::Callback documentation for all the goodies.
206
207       Note that all callbacks are executed in a "eval {}" block, so if any of
208       your callback subroutines "die", Params::CallbackRequest will throw an
209       Params::CallbackRequest::Exception::Execution exception If you don't
210       like this, use the "cb_exception_handler" parameter to "new()" to
211       install your own exception handler.
212
213       Object-Oriented Callback Methods
214
215       Object-oriented callback methods are defined in subclasses of
216       Params::Callback. Unlike functional callbacks, they are not called with
217       a Params::Callback object, but with an instance of the callback
218       subclass. These classes inherit all the goodies provided by
219       Params::Callback, so you can essentially use their instances exactly as
220       you would use the Params::Callback object in functional callback
221       subroutines. But because they're subclasses, you can add your own
222       methods and attributes. See Params::Callback for all the gory details
223       on subclassing, along with a few examples. Generally, callback methods
224       will look like this:
225
226         sub foo : Callback {
227             my $self = shift;
228             # Do stuff.
229         }
230
231       As with functional callback subroutines, method callbacks are executed
232       in a "eval {}" block. Again, see the "cb_exception_handler" parameter
233       to install your own exception handler.
234
235       Note: It's important that you "use" any and all MasonX::Callback
236       subclasses before you "use MasonX::Interp::WithCallbacks" or "use
237       Params::CallbackRequest". This is to get around an issue with
238       identifying the names of the callback methods in mod_perl. Read the
239       comments in the MasonX::Callback source code if you're interested in
240       learning more.
241
242       The Package Key
243
244       The use of the package key is a convenience so that a system with many
245       functional callbacks can use callbacks with the same keys but in
246       different packages. The idea is that the package key will uniquely
247       identify the module in which each callback subroutine is found, but it
248       doesn't necessarily have to be so. Use the package key any way you
249       wish, or not at all:
250
251         my $interp = MasonX::Interp::WithCallbacks->new
252           ( callbacks => [ { cb_key  => 'save',
253                              cb      => \&My::World::save } ] );
254
255       But note that if you don't use the package key at all, you'll still
256       need to provide one in the parameters to be submitted to "exec()" By
257       default, that key is "DEFAULT". Such a callback field in an HTML form
258       would then look like this:
259
260         <input type="button" value="Save World" name="DEFAULT|save_cb" />
261
262       If you don't like the "DEFAULT" package name, you can set an
263       alternative default using the "default_pkg_name" parameter to "new()":
264
265         my $interp = MasonX::Interp::WithCallbacks->new
266           ( callbacks        => [ { cb_key  => 'save',
267                                     cb      => \&My::World::save } ],
268             default_pkg_name => 'MyPkg' );
269
270       Then, of course, any callbacks without a specified package key of their
271       own will then use the custom default:
272
273         <input type="button" value="Save World" name="MyPkg|save_cb" />
274
275       The Class Key
276
277       The class key is essentially a synonym for the package key, but applies
278       more directly to object-oriented callbacks. The difference is mainly
279       that it corresponds to an actual class, and that all Params::Callback
280       subclasses are required to have a class key; it's not optional as it is
281       with functional callbacks. The class key may be declared in your
282       Params::Callback subclass like so:
283
284         package MyApp::CallbackHandler;
285         use base qw(Params::Callback);
286         __PACKAGE__->register_subclass( class_key => 'MyCBHandler' );
287
288       The class key can also be declared by implementing a "CLASS_KEY()"
289       method, like so:
290
291         package MyApp::CallbackHandler;
292         use base qw(Params::Callback);
293         __PACKAGE__->register_subclass;
294         use constant CLASS_KEY => 'MyCBHandler';
295
296       If no class key is explicitly defined, Params::Callback will use the
297       subclass name, instead. In any event, the "register_callback()" method
298       must be called to register the subclass with Params::Callback. See the
299       Params::Callback documentation for complete details.
300
301       Priority
302
303       Sometimes one callback is more important than another. For example, you
304       might rely on the execution of one callback to set up variables needed
305       by another.  Since you can't rely on the order in which callbacks are
306       executed (the Mason request arguments are stored in a hash, and the
307       processing of a hash is, of course, unordered), you need a method of
308       ensuring that the setup callback executes first.
309
310       In such a case, you can set a higher priority level for the setup
311       callback than for callbacks that depend on it. For functional
312       callbacks, you can do it like this:
313
314         my $interp = MasonX::Interp::WithCallbacks->new
315           ( callbacks        => [ { cb_key   => 'setup',
316                                     priority => 3,
317                                     cb       => \&setup },
318                                   { cb_key   => 'save',
319                                     cb       => \&save }
320                                 ] );
321
322       For object-oriented callbacks, you can define the priority right in the
323       callback method declaration:
324
325         sub setup : Callback( priority => 3 ) {
326             my $self = shift;
327             # ...
328         }
329
330         sub save : Callback {
331             my $self = shift;
332             # ...
333         }
334
335       In these examples, the "setup" callback has been configured with a
336       priority level of "3". This ensures that it will always execute before
337       the "save" callback, which has the default priority of "5". This is
338       true regardless of the order of the fields in the corresponding
339       HTML::Form:
340
341         <input type="button" value="Save World" name="DEFAULT|save_cb" />
342         <input type="hidden" name="DEFAULT|setup_cb" value="1" />
343
344       Despite the fact that the "setup" callback field appears after the
345       "save" field (and will generally be submitted by the browser in that
346       order), the "setup" callback will always execute first because of its
347       higher priority.
348
349       Although the "save" callback got the default priority of "5", this too
350       can be customized to a different priority level via the
351       "default_priority" parameter to "new()" for functional callbacks and
352       the "default_priority" to the class declaration for object-oriented
353       callbacks For example, this functional callback configuration:
354
355         my $interp = MasonX::Interp::WithCallbacks->new
356           ( callbacks        => [ { cb_key   => 'setup',
357                                     priority => 3,
358                                     cb       => \&setup },
359                                   { cb_key   => 'save',
360                                     cb       => \&save }
361                                 ],
362             default_priority => 2 );
363
364       And this Params::Callback subclass declaration:
365
366         package MyApp::CallbackHandler;
367         use base qw(Params::Callback);
368         __PACKAGE__->register_subclass( class_key => 'MyCBHandler',
369                                         default_priority => 2 );
370
371       Will cause the "save" callback to always execute before the "setup"
372       callback, since its priority level will default to "2".
373
374       In addition, the priority level can be overridden via the form
375       submission field itself by appending a priority level to the end of the
376       callback field name. Hence, this example:
377
378         <input type="button" value="Save World" name="DEFAULT|save_cb2" />
379         <input type="hidden" name="DEFAULT|setup_cb" value="1" />
380
381       Causes the "save" callback to execute before the "setup" callback by
382       overriding the "save" callback's priority to level "2". Of course, any
383       other form field that triggers the "save" callback without a priority
384       override will still execute "save" at its configured level.
385
386   Request Callbacks
387       Request callbacks come in two separate flavors: those that execute
388       before the argument-triggered callbacks, and those that execute after
389       the argument-triggered callbacks. All of them execute before the Mason
390       component stack executes. Functional request callbacks may be specified
391       via the "pre_callbacks" and "post_callbacks" parameters to "new()",
392       respectively:
393
394         my $interp = MasonX::Interp::WithCallbacks->new
395           ( pre_callbacks  => [ \&translate, \&foobarate ],
396             post_callbacks => [ \&escape, \&negate ] );
397
398       Object-oriented request callbacks may be declared via the "PreCallback"
399       and "PostCallback" method attributes, like so:
400
401         sub translate : PreCallback { ... }
402         sub foobarate : PreCallback { ... }
403         sub escape : PostCallback { ... }
404         sub negate : PostCallback { ... }
405
406       In these examples, the "translate()" and "foobarate()" subroutines or
407       methods will execute (in that order) before any argument-triggered
408       callbacks are executed (none will be in these examples, since none are
409       specified).
410
411       Conversely, the "escape()" and "negate()" subroutines or methods will
412       be executed (in that order) after all argument-triggered callbacks have
413       been executed. And regardless of what argument-triggered callbacks may
414       be triggered, the request callbacks will always be executed for every
415       request.
416
417       Although they may be used for different purposes, the "pre_callbacks"
418       and "post_callbacks" functional callback code references expect the
419       same argument as argument-triggered functional callbacks: a
420       Params::Callback object:
421
422         sub foo {
423             my $cb = shift;
424             # Do your business here.
425         }
426
427       Similarly, object-oriented request callback methods will be passed an
428       object of the class defined in the class key portion of the callback
429       trigger -- either an object of the class in which the callback is
430       defined, or an object of a subclass:
431
432         sub foo : PostCallback {
433             my $self = shift;
434             # ...
435         }
436
437       Of course, the attributes of the Params::Callback or subclass object
438       will be different than in argument-triggered callbacks. For example,
439       the "priority", "pkg_key", and "cb_key" attributes will naturally be
440       undefined. It will, however, be the same instance of the object passed
441       to all other functional callbacks -- or to all other class callbacks
442       with the same class key -- in a single request.
443
444       Like the argument-triggered callbacks, request callbacks are executed
445       in a "eval {}" block, so if any of them "die"s, an
446       Params::CallbackRequest::Exception::Execution exception will be thrown.
447       Use the "cb_exception_handler" parameter to "new()" if you don't like
448       this.
449

INTERFACE

451   Parameters To The "new()" Constructor
452       In addition to those offered by the HTML::Mason::Interp base class,
453       this module supports a number of its own parameters to the "new()"
454       constructor based on those required by Params::CallbackRequest. Each
455       also has a corresponding httpd.conf variable as well, so, if you really
456       want to, you can use MasonX::Interp::WithCallbacks right in your
457       httpd.conf file:
458
459         PerlModule MasonX::Interp::WithCallbacks
460         PerlSetVar MasonInterpClass MasonX::Interp::WithCallbacks
461         SetHandler perl-script
462         PerlHandler HTML::Mason::ApacheHandler
463
464       The parameters to "new()" and their corresponding httpd.conf variables
465       are as follows:
466
467       "callbacks"
468           Argument-triggered functional callbacks are configured via the
469           "callbacks" parameter. This parameter is an array reference of hash
470           references, and each hash reference specifies a single callback.
471           The supported keys in the callback specification hashes are:
472
473           "cb_key"
474               Required. A string that, when found in a properly-formatted
475               Mason request argument key, will trigger the execution of the
476               callback.
477
478           "cb"
479               Required. A reference to the Perl subroutine that will be
480               executed when the "cb_key" has been found in a Mason request
481               argument key. Each code reference should expect a single
482               argument: a Params::Callback object. The same instance of a
483               Params::Callback object will be used for all functional
484               callbacks in a single request.
485
486           "pkg_key"
487               Optional. A key to uniquely identify the package in which the
488               callback subroutine is found. This parameter is useful in
489               systems with many callbacks, where developers may wish to use
490               the same "cb_key" for different subroutines in different
491               packages. The default package key may be set via the
492               "default_pkg_key" parameter.
493
494           "priority"
495               Optional. Indicates the level of priority of a callback. Some
496               callbacks are more important than others, and should be
497               executed before the others.  Params::CallbackRequest supports
498               priority levels ranging from "0" (highest priority) to "9"
499               (lowest priority). The default priority for functional
500               callbacks may be set via the "default_priority" parameter.
501
502           The <callbacks> parameter can also be specified via the httpd.conf
503           configuration variable "MasonCallbacks". Use "PerlSetVar" to
504           specify several callbacks; each one should be an "eval"able string
505           that converts into a hash reference as specified here. For example,
506           to specify two callbacks, use this syntax:
507
508             PerlAddVar MasonCallbacks "{ cb_key  => 'foo', cb => sub { ... }"
509             PerlAddVar MasonCallbacks "{ cb_key  => 'bar', cb => sub { ... }"
510
511           Note that the "eval"able string must be entirely on its own line in
512           the httpd.conf file.
513
514       "pre_callbacks"
515           This parameter accepts an array reference of code references that
516           should be executed for every request before any other callbacks.
517           They will be executed in the order in which they're listed in the
518           array reference. Each code reference should expect a single
519           Params::Callback argument. The same instance of a Params::Callback
520           object will be used for all functional callbacks in a single
521           request. Use pre-argument-triggered request callbacks when you want
522           to do something with the arguments submitted for every request,
523           such as convert character sets.
524
525           The <pre_callbacks> parameter can also be specified via the
526           httpd.conf configuration variable "MasonPreCallbacks". Use multiple
527           "PerlAddVar" to add multiple pre-request callbacks; each one should
528           be an "eval"able string that converts into a code reference:
529
530             PerlAddVar MasonPreCallbacks "sub { ... }"
531             PerlAddVar MasonPreCallbacks "sub { ... }"
532
533       "post_callbacks"
534           This parameter accepts an array reference of code references that
535           should be executed for every request after all other callbacks have
536           been called. They will be executed in the order in which they're
537           listed in the array reference. Each code reference should expect a
538           single Params::Callback argument. The same instance of a
539           Params::Callback object will be used for all functional callbacks
540           in a single request. Use post-argument-triggered request callbacks
541           when you want to do something with the arguments submitted for
542           every request, such as HTML-escape their values.
543
544           The <post_callbacks> parameter can also be specified via the
545           httpd.conf configuration variable "MasonPostCallbacks". Use
546           multiple "PerlAddVar" to add multiple post-request callbacks; each
547           one should be an "eval"able string that converts into a code
548           reference:
549
550             PerlAddVar MasonPostCallbacks "sub { ... }"
551             PerlAddVar MasonPostCallbacks "sub { ... }"
552
553       "cb_classes"
554           An array reference listing the class keys of all of the
555           Params::Callback subclasses containing callback methods that you
556           want included in your MasonX::Interp::WithCallbacks object.
557           Alternatively, the "cb_classes" parameter may simply be the word
558           "ALL", in which case all Params::Callback subclasses will have
559           their callback methods registered with your
560           MasonX::Interp::WithCallbacks object. See the Params::Callback
561           documentation for details on creating callback classes and methods.
562
563           Note: Be sure to "use MasonX::Interp::WithCallbacks" or "use
564           Params::CallbackRequest" only after you've "use"d all of the
565           Params::Callback subclasses you need or else you won't be able to
566           use their callback methods.
567
568           The <cb_classes> parameter can also be specified via the httpd.conf
569           configuration variable "MasonCbClasses". Use multiple "PerlAddVar"
570           to add multiple callback class keys. But, again, be sure to load
571           MasonX::Interp::WithCallbacks or Params::CallbackRequest only after
572           you've loaded all of your MasonX::Callback handler subclasses:
573
574             PerlModule My::CBClass
575             PerlModule Your::CBClass
576             PerlSetVar MasonCbClasses myCBClass
577             PerlAddVar MasonCbClasses yourCBClass
578             # Load MasonX::Interp::WithCallbacks last!
579             PerlModule MasonX::Interp::WithCallbacks
580
581       "default_priority"
582           The priority level at which functional callbacks will be executed.
583           Does not apply to object-oriented callbacks. This value will be
584           used in each hash reference passed via the "callbacks" parameter to
585           "new()" that lacks a "priority" key. You may specify a default
586           priority level within the range of "0" (highest priority) to "9"
587           (lowest priority). If not specified, it defaults to "5".
588
589           Use the "MasonDefaultPriority" variable to set the the
590           "default_priority" parameter in your httpd.conf file:
591
592             PerlSetVar MasonDefaultPriority 3
593
594       "default_pkg_key"
595           The default package key for functional callbacks. Does not apply to
596           object-oriented callbacks. This value that will be used in each
597           hash reference passed via the "callbacks" parameter to "new()" that
598           lacks a "pkg_key" key. It can be any string that evaluates to a
599           true value, and defaults to "DEFAULT" if not specified.
600
601           Use the "MasonDefaultPkgKey" variable to set the the
602           "default_pkg_key" parameter in your httpd.conf file:
603
604             PerlSetVar MasonDefaultPkgKey CBFoo
605
606       "ignore_nulls"
607           By default, Params::CallbackRequest will execute all request
608           callbacks. However, in many situations it may be desirable to skip
609           any callbacks that have no value for the callback field. One can do
610           this by simply checking "$cb->value" in the callback, but if you
611           need to disable the execution of all callbacks, pass the
612           "ignore_nulls" parameter with a true value. It is set to a false
613           value by default.
614
615           Use the "MasonIgnoreNulls" variable to set the the "ignore_nulls"
616           parameter in your httpd.conf file:
617
618             PerlSetVar MasonIgnoreNulls 1
619
620       "cb_exception_handler"
621           When Params::CallbackRequest encounters an exception during the
622           execution of callbacks, it normally calls
623           "Params::CallbackRequest::Exceptions::rethrow_exception" to handle
624           the exception. But if you throw your own exceptions in your
625           callbacks, and want to handle them differently (say, to handle them
626           and then let the request continue), pass the "cb_exception_handler"
627           parameter a code reference to do what you need.
628
629           Use the "MasonCbExceptionHandler" variable to set the
630           "cb_exception_handler" parameter in your httpd.conf file:
631
632             MasonCbExceptionHandler "sub {...}"
633
634           Note: This is the only parameter that differs in name from the same
635           parameter to "Params::CallbackRequest->new". This is so that it can
636           be easily distinguished from the possible addition of a
637           "exception_handler" parameter to a future version of Mason.
638
639   Accessor Methods
640       All of the above parameters to "new()" are passed to the
641       Params::CallbackRequest constructor and deleted from the
642       MasonX::Interp::WithCallbacks object. MasonX::Interp::WithCallbacks
643       then contains a Params::CallbackRequest object that it uses to handle
644       the execution of all callbacks for each request.
645
646       cb_request
647
648         my $interp = MasonX::Interp::WithCallbacks->new;
649         my $cb_request = $interp->cb_request;
650
651       Returns the Params::CallbackRequest object in use during the execution
652       of "make_request()".
653
654       comp_path
655
656         my $comp_path = $interp->comp_path;
657         $interp->comp_path($comp_path);
658
659       Returns the component path resolved by Mason during the execution of
660       "handle_request()". The cool thing is that it can be changed during the
661       execution of callback methods:
662
663         sub change_path :Callback {
664             my $cb = shift;
665             my $interp = $cb->requester;
666             $inpter->comp_path($some_other_path);
667         }
668
669       In this example, we have overridden the component path determined by
670       the Mason resolver in favor of an alternate component, which will be
671       executed, instead.
672
673   Requester
674       The MasonX::Interp::WithCallbacks object is available in all callback
675       methods via the "requester()" accessor:
676
677         sub access_interp :Callback {
678             my $cb = shift;
679             my $interp = $cb->requester;
680             # ...
681         }
682
683   Notes
684         $interp->cb_request->notes($key => $value);
685         my $note = $interp->cb_request->notes($key);
686         my $notes = $interp->cb_request->notes;
687
688       The Params::CallbackRequest notes interface remains available via the
689       "notes()" method of both Params::CallbackRequest and Params::Callback.
690       Notes stored via this interface will be copied to the
691       HTML::Mason::Request "notes()" interface before the execution of the
692       request, and continue to be available for the lifetime of the Mason
693       request via "$interp->cb_request->notes". Notes will be cleared out at
694       the end of the request, just as with "$r->pnotes".
695

SUPPORT

697       This module is stored in an open GitHub repository
698       <http://github.com/theory/masonx-interp-withcallbacks/>. Feel free to
699       fork and contribute!
700
701       Please file bug reports via GitHub Issues
702       <http://github.com/theory/masonx-interp-withcallbacks/issues/> or by
703       sending mail to bug-MasonX-Interp-WithCallbacks.cpan.org <mailto:bug-
704       MasonX-Interp-WithCallbacks.cpan.org>.
705

SEE ALSO

707       Params::CallbackRequest handles the processing of the Mason request
708       arguments and the execution of callbacks. See its documentation for the
709       most up-to-date documentation of the underlying callback architecture.
710
711       Params::Callback objects get passed as the sole argument to all
712       functional callbacks, and offer access to data relevant to the
713       callback. Params::Callback also defines the object-oriented callback
714       interface, making its documentation a must-read for anyone who wishes
715       to create callback classes and methods.
716
717       This module works with HTML::Mason by subclassing HTML::Mason::Interp.
718       Inspired by the implementation of callbacks in Bricolage
719       (<http://bricolage.cc/>), it is however a completely new code base with
720       a rather different approach.
721

AUTHOR

723       David E. Wheeler <david@justatheory.com>
724
726       Copyright 2003-2011 by David E. Wheeler. Some Rights Reserved.
727
728       This library is free software; you can redistribute it and/or modify it
729       under the same terms as Perl itself.
730
731
732
733perl v5.32.1                      2021-01-27  MasonX::Interp::WithCallbacks(3)
Impressum