NAME

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

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;

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.

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.