HTML::Mason::Plugin(3)User Contributed Perl DocumentatioHTML::Mason::Plugin(3)NAMEHTML::Mason::Plugin - Plugin Base class for Mason
VERSION
version 1.54
DESCRIPTION
Use a Mason plugin to have actions occur at the beginning or end of
requests or components. Plugins are activated by passing plugins in the
interpreter or request object. Each plugin in the list can be specified
as a class name (in which case the plugin object is created once for
each request) or as an actual object of the plugin class.
If your plugin can be configured, place the configuration in class
variables - for example,
$MasonX::Plugin::Timer::Units = 'seconds';
These can be set either from httpd.conf via PerlSetVar directives, or
in perl directly from a handler.pl file.
SYNOPIS
package MasonX::Plugin::Timer;
use base qw(HTML::Mason::Plugin);
use Time::HiRes;
sub start_component_hook {
my ($self, $context) = @_;
push @{$self->{ timers }}, Time::HiRes::time;
}
sub end_component_hook {
my ($self, $context) = @_;
my $elapsed = Time::HiRes::time - pop @{$self->{ timers }};
printf STDERR "Component '%s' took %.1f seconds\n",
$context->comp->title, $elapsed;
}
1;
PLUGIN HOOKS
A plugin class defines one or more of the following hooks (methods):
start_request_hook, end_request_hook, start_component_hook, and
end_component_hook.
Every hook receives two arguments: the plugin object itself, and a
context object with various methods.
start_request_hook
"start_request_hook" is called before the Mason request begins
execution. Its context has the following read-only methods:
request # the current request ($m)
args # arguments the request was called with
When called in scalar context, args returns a list reference which
may be modified to change or add to the arguments passed to the
first component. When called in list context, args returns a list
(which may be assigned to a hash).
Note that subrequests (see HTML::Mason::Request will create a new
plugin object and execute this code again; you can skip your code
for subrequests by checking "is_subrequest" on request. e.g.
sub start_request_hook {
my ($self, $context) = @_;
unless ($context->request->is_subrequest()) {
# perform hook action
}
}
Currently, this hook is called before any information about the
requested component is available, so you cannot call methods like
"base_comp()" or "request_args()" on the Request object.
end_request_hook
"end_request_hook" is called before the Mason request exits. Its
context has the following read-only methods:
request # the current request ($m)
args # arguments the request was called with
output # reference to the contents of the output buffer
wantarray # value of wantarray the request was called with
result # arrayref of value(s) that the request is about to return
error # reference to error, if any, that the request is about to throw
When called in scalar context, args returns a list reference; when
called in list context, it returns a list (which may be assigned to
a hash).
result always contains an array ref; if wantarray is 0, the return
value is the the first element of that array. The plugin may modify
output to affect what the request outputs, and result and error to
affect what the request returns.
start_component_hook
"start_component_hook" is called before a component begins
executing. Its context has the following read-only methods:
request # the current request ($m)
comp # the component object
args # arrayref of arguments the component was called with
The plugin may NOT modify args currently.
end_component_hook
"end_component_hook()" is called after a component has completed.
Its context has the following read-only methods:
request # the current request ($m)
comp # the component object
args # arrayref of arguments the component was called with
wantarray # value of wantarray the component was called with
result # arrayref of value(s) that the component is about to return
error # reference to error, if any, that the component is about to throw
result always contains an array ref; if wantarray is 0, the return
value is the first element of that array. The plugin may modify
both result and error to affect how the request returns.
It would be desirable for this hook to have access to the
component's output as well as its return value, but this is
currently impossible because output from multiple components
combine into a single buffer.
WARNINGS
Do not keep an unweakened reference to a request or component object in
your plugin object, or you will create a nasty circular reference.
SEE ALSO
Mason
AUTHORS
· Jonathan Swartz <swartz@pobox.com>
· Dave Rolsky <autarch@urth.org>
· Ken Williams <ken@mathforum.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2012 by Jonathan Swartz.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
perl v5.18.2 2014-01-19 HTML::Mason::Plugin(3)
