NAME

MasonX::Request::ExtendedCompRoot - Extend functionality of Mason's component root

SYNOPSIS

In your httpd.conf file:

  PerlSetVar  MasonRequestClass   MasonX::Request::ExtendedCompRoot
  PerlSetVar  MasonResolverClass  MasonX::Resolver::ExtendedCompRoot

Or when creating an ApacheHandler object:

  my $ah =
      HTML::Mason::ApacheHandler->new
          ( request_class  => 'MasonX::Request::ExtendedCompRoot',
            resolver_class => 'MasonX::Resolver::ExtendedCompRoot'
            ...
          );

Once Mason is up and running, ExtendedCompRoot allows you to:

  # completely override the component root
  $m->comp_root({key1=>'/path/to/root1'}, {key2=>'/path/to/root2'});
  
  # add another root to the component root
  $m->prefix_comp_root('key=>/path/to/root');
  
  # call a component in a specific component root
  <& key=>/path/to/comp &>

MasonX::Request::ExtendedCompRoot can also be used as the request class when running Mason in standalone mode.

DESCRIPTION

DYNAMIC COMPONENT ROOT

MasonX::Request::ExtendedCompRoot lets you alter Mason's component root during the lifetime of any given request or subrequest.

This behaviour is useful if you want to override certain components, but cannot determine that at the moment you create your handler (when you could in theory create an interp object with a different component root) or because you configure Mason in an httpd.conf.

For example:

  # outputs component in /path/to/root1
  <& /path/to/comp &>
  
  % $m->prefix_comp_root('another_key=>/path/to/root2');
  
  # now outputs component in /path/to/root2 if it exists
  # if it doesn't, the output remains the component in /path/to/root1
  <& /path/to/comp &>

At the end of each request or subrequest, the component root is reset to its initial state.

ADDITIONAL COMPONENT CALL SYNTAX

MasonX::Request::ExtendedCompRoot also provides syntactical glue to enable calling a component in a specific component root that would otherwise be inaccessible via the usual search path.

  <& key=>/path/to/comp &>

ie. A given component path matches the first file found in an ordered search through the roots, but if preceded with the named key of a component root, matches the file found in that root.

This leaves the rules for calling methods that deal with component paths ($m-comp>, $m-comp_exists>, $m-fetch_comp>) as follows:

• If the path is absolute (starting with a '/'), then the component is found relative to the component root.

• If the path contains the component root delimiter ('=>'), then the component is found in the specified component root.

• If the path is relative (no leading '/'), then the component is found relative to the current component directory.

• If the path matches both a subcomponent and file-based component, the subcomponent takes precedence.

QUASI-INHERITANCE FOR MASON METHODS

Calls to component methods work slightly differently to standard Mason behaviour.

The standard behaviour is:

  a) search component root for component
  b) if a component is found, look up method in that component
  c) stop regardless of whether a method exists there or not

This makes perfect sense since a given component path can only ever match the first file found in an ordered search through the roots. However, that doesn't hold true for MasonX::Request::ExtendedCompRoot.

The ExtendedCompRoot way is:

  a) search component root for component
  b) if a component is found, look up method in that component
  c) if no method is found in that component, continue searching the component root

This has the effect of allowing methods to percolate up through the component root as if they were "inherited".

For example, given a component root [key1=>'path/to/root1', key2=>'/path/to/root2'], if '/path/to/comp' exists in both roots, but only the component in key2 has a method called 'method_name':

  # outputs component in key1
  <& /path/to/comp &> 

  # outputs method in key2
  <& /path/to/comp:method_name &>

NB. in the above example, only the method is accessed - the components in key1 and key2 are separate and variables are not shared between them. If you wanted such behaviour, you would either need to make any such variables global or else use $m->notes or even create get and set methods to pass the variables back and forth.

USAGE

SET UP

To use this module you need to tell Mason to use this class for requests and MasonX::Resolver::ExtendedCompRoot for its resolver. This can be done in two ways. If you are configuring Mason via your httpd.conf file, simply add this:

  PerlSetVar  MasonRequestClass    MasonX::Request::ExtendedCompRoot
  PerlSetVar  MasonResolverClass   MasonX::Resolver::ExtendedCompRoot

If you are using a handler.pl file, simply add this parameter to the parameters given to the ApacheHandler constructor:

  request_class  => 'MasonX::Request::ExtendedCompRoot'
  resolver_class => 'MasonX::Resolver::ExtendedCompRoot'

METHODS

• comp_root

  Returns an array of component roots if no arguments are passed.

    my @comp_root = $m->comp_root;     # just returns the comp_root

  If any arguments are passed, the existing component root is replaced with those values.

  Any argument passed must have a name and a path. The name must be unique and the path absolute and actually exist.

  Arguments can be passed as an argument list of scalars, hashes or arrays (or a combination of any of those) or as an array ref to such a list - the following examples are all equivalent:

    # as scalar - must take form NAME=>PATH
    $m->comp_root('key1=>/path/to/root1', 'key2=>/path/to/root2');
  
    $m->comp_root({key1=>'/path/to/root1'}, {key2=>'/path/to/root2'});
  
    $m->comp_root(['key1','/path/to/root1'], ['key2','/path/to/root2']);
  
    $m->comp_root('key1=>/path/to/root1', {key2=>'/path/to/root2'}, ['key3','/path/to/root3']);
  
    my @new_comp_root = ('key1=>/path/to/root1', 'key2=>/path/to/root2');
    $m->comp_root(\@new_comp_root);

• prefix_comp_root

  Adds passed arguments to the beginning of the current component root array.

    $m->prefix_comp_root('key=>/path/to/root');

  Arguments for prefix_comp_root are treated in exactly the same way as those for comp_root.

• reset_comp_root

  Resets the component root to how it was at the start of the current request or subrequest. Takes no arguments.

  NB. At the end of each request or subrequest, reset_comp_root is called to ensure that the component root returns to its initial state.

PREREQUISITES

HTML::Mason

BUGS

No known bugs. Unless the inability to insert non-existent or non-absolute paths into the component root is considered a bug.

SEE ALSO

HTML::Mason, MasonX::Resolver::ExtendedCompRoot, MasonX::Request::WithApacheSession

AUTHOR

Alex Robinson, <cpan[@]alex.cloudband.com>

LICENSE

MasonX::Request::ExtendedCompRoot is free software and can be used under the same terms as Perl, i.e. either the GNU Public Licence or the Artistic License.

cpanm MasonX::Request::ExtendedCompRoot

perl -MCPAN -e shell
install MasonX::Request::ExtendedCompRoot