1MasonX::Interp::WithCalUlsbearckCso(n3t)ributed Perl DocMuamseonntXa:t:iIonnterp::WithCallbacks(3)
2
6 MasonX::Interp::WithCallbacks - Mason callback support via
7 Params::CallbackRequest.
8
10 In your Mason component:
11 % 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 In handler.pl:
23 use strict;
25 use MasonX::Interp::WithCallbacks;
26 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 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 sub handler {
42 my $r = shift;
43 $ah->handle_request($r);
44 }
45 Or, in a subclass of Params::Callback:
47 package MyApp::CallbackHandler;
49 use base qw(Params::Callback);
50 __PACKAGE__->register_subclass( class_key => 'myCallbacker' );
51 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 And then, in handler.pl:
60 # Load order is important here!
62 use MyApp::CallbackHandler;
63 use MasonX::Interp::WithCallbacks;
64 my $ah = HTML::Mason::ApacheHandler->new
66 ( interp_class => 'MasonX::Interp::WithCallbacks',
67 cb_classes => [qw(myCallbacker)] );
68 sub handler {
70 my $r = shift;
71 $ah->handle_request($r);
72 }
73 Or, just use MasonX::Interp::WithCallbacks directly:
75 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
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 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 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
105 Why would you want to do this? Well, there are a number of reasons.
106 Some I can think of offhand include:
107 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 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 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 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 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 And if those aren't enough reasons, then just consider this: Callbacks
154 are just way cool.
155
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 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 <input type="button" value="Save World" name="world|save_cb" />
172 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 my $interp = MasonX::Interp::WithCallbacks->new
182 ( callbacks => [ { pkg_key => 'world',
183 cb_key => 'save',
184 cb => \&My::World::save } ] );
185 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 Functional Callback Subroutines
191 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 sub foo {
198 my $cb = shift;
199 # Do stuff.
200 }
201 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 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 Object-Oriented Callback Methods
214 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 sub foo : Callback {
227 my $self = shift;
228 # Do stuff.
229 }
230 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 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 The Package Key
243 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 my $interp = MasonX::Interp::WithCallbacks->new
252 ( callbacks => [ { cb_key => 'save',
253 cb => \&My::World::save } ] );
254 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 <input type="button" value="Save World" name="DEFAULT|save_cb" />
261 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 my $interp = MasonX::Interp::WithCallbacks->new
266 ( callbacks => [ { cb_key => 'save',
267 cb => \&My::World::save } ],
268 default_pkg_name => 'MyPkg' );
269 Then, of course, any callbacks without a specified package key of their
271 own will then use the custom default:
272 <input type="button" value="Save World" name="MyPkg|save_cb" />
274 The Class Key
276 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 package MyApp::CallbackHandler;
285 use base qw(Params::Callback);
286 __PACKAGE__->register_subclass( class_key => 'MyCBHandler' );
287 The class key can also be declared by implementing a "CLASS_KEY()"
289 method, like so:
290 package MyApp::CallbackHandler;
292 use base qw(Params::Callback);
293 __PACKAGE__->register_subclass;
294 use constant CLASS_KEY => 'MyCBHandler';
295 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 Priority
302 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 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 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 For object-oriented callbacks, you can define the priority right in the
323 callback method declaration:
324 sub setup : Callback( priority => 3 ) {
326 my $self = shift;
327 # ...
328 }
329 sub save : Callback {
331 my $self = shift;
332 # ...
333 }
334 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 <input type="button" value="Save World" name="DEFAULT|save_cb" />
342 <input type="hidden" name="DEFAULT|setup_cb" value="1" />
343 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 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 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 And this Params::Callback subclass declaration:
365 package MyApp::CallbackHandler;
367 use base qw(Params::Callback);
368 __PACKAGE__->register_subclass( class_key => 'MyCBHandler',
369 default_priority => 2 );
370 Will cause the "save" callback to always execute before the "setup"
372 callback, since its priority level will default to "2".
373 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 <input type="button" value="Save World" name="DEFAULT|save_cb2" />
379 <input type="hidden" name="DEFAULT|setup_cb" value="1" />
380 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 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 my $interp = MasonX::Interp::WithCallbacks->new
395 ( pre_callbacks => [ \&translate, \&foobarate ],
396 post_callbacks => [ \&escape, \&negate ] );
397 Object-oriented request callbacks may be declared via the "PreCallback"
399 and "PostCallback" method attributes, like so:
400 sub translate : PreCallback { ... }
402 sub foobarate : PreCallback { ... }
403 sub escape : PostCallback { ... }
404 sub negate : PostCallback { ... }
405 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 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 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 sub foo {
423 my $cb = shift;
424 # Do your business here.
425 }
426 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 sub foo : PostCallback {
433 my $self = shift;
434 # ...
435 }
436 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 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
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 PerlModule MasonX::Interp::WithCallbacks
460 PerlSetVar MasonInterpClass MasonX::Interp::WithCallbacks
461 SetHandler perl-script
462 PerlHandler HTML::Mason::ApacheHandler
463 The parameters to "new()" and their corresponding httpd.conf variables
465 are as follows:
466 "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 "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 "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 "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 "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 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 PerlAddVar MasonCallbacks "{ cb_key => 'foo', cb => sub { ... }"
509 PerlAddVar MasonCallbacks "{ cb_key => 'bar', cb => sub { ... }"
510 Note that the "eval"able string must be entirely on its own line in
512 the httpd.conf file.
513 "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 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 PerlAddVar MasonPreCallbacks "sub { ... }"
531 PerlAddVar MasonPreCallbacks "sub { ... }"
532 "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 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 PerlAddVar MasonPostCallbacks "sub { ... }"
551 PerlAddVar MasonPostCallbacks "sub { ... }"
552 "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 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 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 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 "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 Use the "MasonDefaultPriority" variable to set the the
590 "default_priority" parameter in your httpd.conf file:
591 PerlSetVar MasonDefaultPriority 3
593 "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 Use the "MasonDefaultPkgKey" variable to set the the
602 "default_pkg_key" parameter in your httpd.conf file:
603 PerlSetVar MasonDefaultPkgKey CBFoo
605 "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 Use the "MasonIgnoreNulls" variable to set the the "ignore_nulls"
616 parameter in your httpd.conf file:
617 PerlSetVar MasonIgnoreNulls 1
619 "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 Use the "MasonCbExceptionHandler" variable to set the
630 "cb_exception_handler" parameter in your httpd.conf file:
631 MasonCbExceptionHandler "sub {...}"
633 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 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 cb_request
647 my $interp = MasonX::Interp::WithCallbacks->new;
649 my $cb_request = $interp->cb_request;
650 Returns the Params::CallbackRequest object in use during the execution
652 of "make_request()".
653 comp_path
655 my $comp_path = $interp->comp_path;
657 $interp->comp_path($comp_path);
658 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 sub change_path :Callback {
664 my $cb = shift;
665 my $interp = $cb->requester;
666 $inpter->comp_path($some_other_path);
667 }
668 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 Requester
674 The MasonX::Interp::WithCallbacks object is available in all callback
675 methods via the "requester()" accessor:
676 sub access_interp :Callback {
678 my $cb = shift;
679 my $interp = $cb->requester;
680 # ...
681 }
682 Notes
684 $interp->cb_request->notes($key => $value);
685 my $note = $interp->cb_request->notes($key);
686 my $notes = $interp->cb_request->notes;
687 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
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 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
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 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 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
723 David E. Wheeler <david@justatheory.com>
724
726 Copyright 2003-2011 by David E. Wheeler. Some Rights Reserved.
727 This library is free software; you can redistribute it and/or modify it
729 under the same terms as Perl itself.
730perl v5.32.1 2021-01-27 MasonX::Interp::WithCallbacks(3)