1HTML::Mason::Plugin(3)User Contributed Perl DocumentationHTML::Mason::Plugin(3)
2
6 HTML::Mason::Plugin - Plugin Base class for Mason
7
9 package MasonX::Plugin::Timer;
10 use base qw(HTML::Mason::Plugin);
11 use Time::HiRes;
12 sub start_component_hook {
14 my ($self, $context) = @_;
15 push @{$self->{ timers }}, Time::HiRes::time;
16 }
17 sub end_component_hook {
19 my ($self, $context) = @_;
20 my $elapsed = Time::HiRes::time - pop @{$self->{ timers }};
21 printf STDERR "Component '%s' took %.1f seconds\n",
22 $context->comp->title, $elapsed;
23 }
24 1;
26
28 Use a Mason plugin to have actions occur at the beginning or end of
29 requests or components. Plugins are activated by passing plugins in the
30 interpreter or request object. Each plugin in the list can be specified
31 as a class name (in which case the plugin object is created once for
32 each request) or as an actual object of the plugin class.
33 If your plugin can be configured, place the configuration in class
35 variables - for example,
36 $MasonX::Plugin::Timer::Units = 'seconds';
38 These can be set either from httpd.conf via PerlSetVar directives, or
40 in perl directly from a handler.pl file.
41
43 A plugin class defines one or more of the following hooks (methods):
44 start_request_hook, end_request_hook, start_component_hook, and
45 end_component_hook.
46 Every hook receives two arguments: the plugin object itself, and a
48 context object with various methods.
49 start_request_hook
51 "start_request_hook" is called before the Mason request begins
52 execution. Its context has the following read-only methods:
53 request # the current request ($m)
55 args # arguments the request was called with
56 When called in scalar context, args returns a list reference which
58 may be modified to change or add to the arguments passed to the
59 first component. When called in list context, args returns a list
60 (which may be assigned to a hash).
61 Note that subrequests (see HTML::Mason::Request will create a new
63 plugin object and execute this code again; you can skip your code
64 for subrequests by checking "is_subrequest" on request. e.g.
65 sub start_request_hook {
67 my ($self, $context) = @_;
68 unless ($context->request->is_subrequest()) {
69 # perform hook action
70 }
71 }
72 Currently, this hook is called before any information about the
74 requested component is available, so you cannot call methods like
75 "base_comp()" or "request_args()" on the Request object.
76 end_request_hook
78 "end_request_hook" is called before the Mason request exits. Its
79 context has the following read-only methods:
80 request # the current request ($m)
82 args # arguments the request was called with
83 output # reference to the contents of the output buffer
84 wantarray # value of wantarray the request was called with
85 result # arrayref of value(s) that the request is about to return
86 error # reference to error, if any, that the request is about to throw
87 When called in scalar context, args returns a list reference; when
89 called in list context, it returns a list (which may be assigned to
90 a hash).
91 result always contains an array ref; if wantarray is 0, the return
93 value is the the first element of that array. The plugin may modify
94 output to affect what the request outputs, and result and error to
95 affect what the request returns.
96 start_component_hook
98 "start_component_hook" is called before a component begins
99 executing. Its context has the following read-only methods:
100 request # the current request ($m)
102 comp # the component object
103 args # arrayref of arguments the component was called with
104 The plugin may NOT modify args currently.
106 end_component_hook
108 "end_component_hook()" is called after a component has completed.
109 Its context has the following read-only methods:
110 request # the current request ($m)
112 comp # the component object
113 args # arrayref of arguments the component was called with
114 wantarray # value of wantarray the component was called with
115 result # arrayref of value(s) that the component is about to return
116 error # reference to error, if any, that the component is about to throw
117 result always contains an array ref; if wantarray is 0, the return
119 value is the first element of that array. The plugin may modify
120 both result and error to affect how the request returns.
121 It would be desirable for this hook to have access to the
123 component's output as well as its return value, but this is
124 currently impossible because output from multiple components
125 combine into a single buffer.
126
128 Do not keep an unweakened reference to a request or component object in
129 your plugin object, or you will create a nasty circular reference.
130perl v5.34.0 2022-01-21 HTML::Mason::Plugin(3)