MasonX::Request::ExtendedCompRoot - Extend functionality of Mason's component root
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.
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.
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:
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.
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'
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);
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.
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.
HTML::Mason
No known bugs. Unless the inability to insert non-existent or non-absolute paths into the component root is considered a bug.
0.03
HTML::Mason, MasonX::Resolver::ExtendedCompRoot, MasonX::Request::WithApacheSession
Alex Robinson, <cpan[@]alex.cloudband.com>
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.
