The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>HTML::Mason::Plugin - Plugin Base class for Mason</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:root@localhost" />
</head>

<body style="background-color: white">


<!-- INDEX BEGIN -->
<div name="index">
<p><A NAME="__index__"></a></p>

<ul>

	<li><A HREF="#name">NAME</a></li>
	<li><A HREF="#synopis">SYNOPIS</a></li>
	<li><A HREF="#description">DESCRIPTION</a></li>
	<li><A HREF="#plugin_hooks">PLUGIN HOOKS</a></li>
	<li><A HREF="#warnings">WARNINGS</a></li>
	<li><A HREF="#authors">AUTHORS</a></li>
	<li><A HREF="#see_also">SEE ALSO</a></li>
</ul>

<hr name="index" />
</div>
<!-- INDEX END -->

<p>
</p>
<h1><A NAME="name">NAME</a></h1>
<p>HTML::Mason::Plugin - Plugin Base class for Mason</p>
<p>
</p>
<hr />
<h1><A NAME="synopis">SYNOPIS</a></h1>
<pre>
   package MasonX::Plugin::Timer;
   use base qw(HTML::Mason::Plugin);
   use Time::HiRes;</pre>
<pre>
   sub start_component_hook {
       my ($self, $context) = @_;
       push @{$self-&gt;{ timers }}, Time::HiRes::time;
   }</pre>
<pre>
   sub end_component_hook {
       my ($self, $context) = @_;
       my $elapsed = Time::HiRes::time - pop @{$self-&gt;{ timers }};
       printf STDERR &quot;Component '%s' took %.1f seconds\n&quot;,
           $context-&gt;comp-&gt;title, $elapsed;
   }</pre>
<pre>
   1;</pre>
<p>
</p>
<hr />
<h1><A NAME="description">DESCRIPTION</a></h1>
<p>Use a Mason plugin to have actions occur at the beginning or end of
requests or components. Plugins are activated by passing <A HREF="Params.html#plugins">plugins</a> 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.</p>
<p>If your plugin can be configured, place the configuration in class
variables - for example,</p>
<pre>
    $MasonX::Plugin::Timer::Units = 'seconds';</pre>
<p>These can be set either from httpd.conf via PerlSetVar
directives, or in perl directly from a handler.pl file.</p>
<p>
</p>
<hr />
<h1><A NAME="plugin_hooks">PLUGIN HOOKS</a></h1>
<p>A plugin class defines one or more of the following hooks (methods):
<em>start_request_hook</em>, <em>end_request_hook</em>, <em>start_component_hook</em>,
and <em>end_component_hook</em>.</p>
<p>Every hook receives two arguments: the plugin object itself,
and a context object with various methods.</p>
<dl>
<dt><strong><A NAME="start_request_hook" class="item">start_request_hook</a></strong></dt>

<dd>
<p><A HREF="#start_request_hook"><code>start_request_hook</code></a> is called before the Mason request begins
execution.  Its context has the following read-only methods:</p>
<pre>
    request # the current request ($m)
    args    # arguments the request was called with</pre>
<p>When called in scalar context, <em>args</em> 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, <em>args</em> returns a list (which
may be assigned to a hash).</p>
<p>Note that subrequests (see
<a HREF="Request.html">HTML::Mason::Request</a> will create a new plugin
object and execute this code again; you can skip your code for
subrequests by checking <code>is_subrequest</code> on <em>request</em>. e.g.</p>
<pre>
   sub start_request_hook {
       my ($self, $context) = @_;
       unless ($context-&gt;request-&gt;is_subrequest()) {
           # perform hook action
       }
   }</pre>
<p>Currently, this hook is called before any information about the
requested component is available, so you cannot call methods like
<code>base_comp()</code> or <code>request_args()</code> on the Request object.</p>
</dd>
<dt><strong><A NAME="end_request_hook" class="item">end_request_hook</a></strong></dt>

<dd>
<p><A HREF="#end_request_hook"><code>end_request_hook</code></a> is called before the Mason request
exits. Its context has the following read-only methods:</p>
<pre>
    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</pre>
<p>When called in scalar context, <em>args</em> returns a list reference; when
called in list context, it returns a list (which may be assigned to a
hash).</p>
<p><em>result</em> always contains an array ref; if <em>wantarray</em> is 0, the
return value is the the first element of that array. The plugin may
modify <em>output</em> to affect what the request outputs, and 
<em>result</em> and <em>error</em> to affect what the request returns.</p>
</dd>
<dt><strong><A NAME="start_component_hook" class="item">start_component_hook</a></strong></dt>

<dd>
<p><A HREF="#start_component_hook"><code>start_component_hook</code></a> is called before a component begins
executing. Its context has the following read-only methods:</p>
<pre>
    request     # the current request ($m)
    comp        # the component object
    args        # arrayref of arguments the component was called with</pre>
<p>The plugin may NOT modify <em>args</em> currently.</p>
</dd>
<dt><strong><A NAME="end_component_hook" class="item">end_component_hook</a></strong></dt>

<dd>
<p><A HREF="#end_component_hook"><code>end_component_hook()</code></a> is called after a component has
completed. Its context has the following read-only methods:</p>
<pre>
    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</pre>
<p><em>result</em> always contains an array ref; if <em>wantarray</em>
is 0, the return value is the first element of that array.  The plugin
may modify both <em>result</em> and <em>error</em> to affect how the request
returns.</p>
<p>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.</p>
</dd>
</dl>
<p>
</p>
<hr />
<h1><A NAME="warnings">WARNINGS</a></h1>
<p>Do not keep an unweakened reference to a request or component object
in your plugin object, or you will create a nasty circular reference.</p>
<p>
</p>
<hr />
<h1><A NAME="authors">AUTHORS</a></h1>
<p>Doug Treder, Jonathan Swartz, Dave Rolsky</p>
<p>
</p>
<hr />
<h1><A NAME="see_also">SEE ALSO</a></h1>
<p><a HREF="Interp.html">HTML::Mason::Interp</a>, <a HREF="Request.html">HTML::Mason::Request</a></p>

</body>

</html>