NAME

HTML::MasonX::Free::Resolver - a resolver that lets you specialize components with dir overlays

VERSION

version 0.007

OVERVIEW

This class is a replacement for HTML::Mason::Resolver::File. If you don't know anything about what the resolver does or what comp roots are, this whole thing might make no sense. If you really like Mason, though, it might be worth reading about it. Right now.

Okay, are you caught up?

The next thing you need to keep in mind is that the comp_roots parameter is part of the interp and not part of the resolver. Does this seem weird to you? Me too, but that's how it is.

So, let's say you had this set of comp_roots:

my_app  =>  /usr/myapp/mason
shared  =>  /usr/share/mason

The idea is that you can have stuff in the my_app root that specializes generalized stuff in the shared root. Unfortunately, it's not really very useful. You can't have foo in the first comp root inherit from foo in the second. You can't easily take an existing set of templates and specialize them with an overlay.

That is the problem that this resolver is meant to solve. Instead of having the resolver try to find each path in each comp root independenly, the comp_roots are instead stored in the resolver's resolver_roots. When looking for a path, it looks in each root in turn. When it finds one, it returns that. If there's another one in one of the later paths, the one that was found will automatically be made to inherit from it and (by default) to call it by default.

Because you don't want the interp object to confuse things with comp roots, you must signal that you know that its comp roots will be ignored by setting comp_root to "/-".

Say you set up your resolver roots like this:

my_app  => /usr/myapp/mason
shared  => /usr/share/mason

Then you have these two files:

/usr/share/mason/welcome:

<h1>Welcome to <& SELF:site &>, <& SELF:user &>!</h1>
<%method site>the site</%method>
<%method user><% $m->user->name |h %></%method>

/usr/myapp/mason:

<%method site>my guestbook</%method>

If you resolve and render /welcome, it will say:

Welcome to my guestbook, User Name.

If you absolutely must render the shared welcome component directly, you can refer to /shared=/welcome.

This is pretty experimental code. It also probably doesn't work with some Mason options that I don't use, like preloading, because I haven't implemented the glob_path method.

PERL VERSION

This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years.

Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl.

ATTRIBUTES

comp_class

This argument is the class that will be used for components created by this resolver. The default is HTML::Mason::Component::FileBased.

Because HTML::MasonX::Resolver::AutoInherit is not (right now) part of Class::Container, you can't pass this as an argument to the interp constructor.

AUTHOR

Ricardo Signes <cpan@semiotic.systems>

COPYRIGHT AND LICENSE

This software is copyright (c) 2022 by Ricardo Signes.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.