1HTML::Mason::Plugin(3)User Contributed Perl DocumentationHTML::Mason::Plugin(3)
2
3
4

NAME

6       HTML::Mason::Plugin - Plugin Base class for Mason
7

SYNOPIS

9          package MasonX::Plugin::Timer;
10          use base qw(HTML::Mason::Plugin);
11          use Time::HiRes;
12
13          sub start_component_hook {
14              my ($self, $context) = @_;
15              push @{$self->{ timers }}, Time::HiRes::time;
16          }
17
18          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
25          1;
26

DESCRIPTION

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
34       If your plugin can be configured, place the configuration in class
35       variables - for example,
36
37           $MasonX::Plugin::Timer::Units = 'seconds';
38
39       These can be set either from httpd.conf via PerlSetVar directives, or
40       in perl directly from a handler.pl file.
41

PLUGIN HOOKS

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
47       Every hook receives two arguments: the plugin object itself, and a
48       context object with various methods.
49
50       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
54               request # the current request ($m)
55               args    # arguments the request was called with
56
57           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
62           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
66              sub start_request_hook {
67                  my ($self, $context) = @_;
68                  unless ($context->request->is_subrequest()) {
69                      # perform hook action
70                  }
71              }
72
73           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
77       end_request_hook
78           "end_request_hook" is called before the Mason request exits. Its
79           context has the following read-only methods:
80
81               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
88           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
92           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
97       start_component_hook
98           "start_component_hook" is called before a component begins
99           executing. Its context has the following read-only methods:
100
101               request     # the current request ($m)
102               comp        # the component object
103               args        # arrayref of arguments the component was called with
104
105           The plugin may NOT modify args currently.
106
107       end_component_hook
108           "end_component_hook()" is called after a component has completed.
109           Its context has the following read-only methods:
110
111               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
118           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
122           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

WARNINGS

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.
130
131
132
133perl v5.32.1                      2021-01-27            HTML::Mason::Plugin(3)
Impressum