NAME

HTML::Template::HashWrapper - Easy association with HTML::Template

SYNOPSIS

  use HTML::Template;
  use HTML::Template::HashWrapper;

  my $context = { var1 => 'Stuff',
                  var2 => [ { name => 'Name1', value => 'Val1', },
                            { name => 'Name2', value => 'Val2', },
                          ],
                };

  my $template = HTML::Template->new
    ( associate => HTML::Template::HashWrapper->new( $context ) );

  # Some::Object creates blessed hash references:
  my $something = Some::Object->new();
  my $wrapper = HTML::Template::HashWrapper->new( $something );
  my $template = HTML::Template->new( associate => $wrapper );

  # the wrapper keeps the original's interface:
  my $val1 = $something->somemethod( 251 );
  my $val2 = $wrapper->somemethod( 251 );

DESCRIPTION

HTML::Template::HashWrapper provides a simple way to use arbitrary hash references (and hashref-based objects) with HTML::Template's "associate" option.

"new($ref)" returns an object with a "param()" method which conforms to HTML::Template's expected interface:

"param($key)" returns the value of "$ref->{$key}".
"param()" with no argument returns the set of keys.
"param($key,$value)" may also be used to set values in the underlying hash.

"new()" will die if given something which is not a hash reference as an argument.

The object returned by $new retains its identity with its original class, so you can continue to use the object as normal (call its methods, etc).

Internals

HTML::Template::HashWrapper works by re-blessing the input object (or blessing it, if the input is an unblessed hash reference) into a new package which extends the original package and provides an implementation of "param()".

If for some reason the input reference cannot be re-blessed (for example, you're using someone else's code which checks "ref($orig)" when it should be using "isa()"), you may use HTML::Template::HashWrapper::Plain:

    $wrapper = HTML::Template::HashWrapper::Plain->new( $obj );

The "Plain" wrapper object provides only the compliant "param()" method, but not any of the original object's methods. The original object is left completely untouched. Most of the time this will be unneccesary.

For purposes of testing the object type, HTML::Template::HashWrapper::Plain "isa" HTML::Template::HashWrapper.

HashWrapper works by creating an unique package whose @ISA includes both HashWrapper and the original package (if there is one) of the wrapped object.

If you don't like the way the unique package names are generated, you can override "_GENERATE_PACKAGENAME()". Be aware that you will see strange behavior if this method does not return unique values (for a sufficient definition of "unique").

Should you desire to subclass HashWrapper, you may wish to also subclass HashWrapper::Plain, which manages its state slightly differently.

OTHER

In theory, "param()" should also support setting multiple parameters by passing in a hash or hash reference. This interface currently does not support that, but HTML::Template only uses the two supported forms.

It should be possible to make this more efficient by memoizing the pairs of base package names, at the expense of some space for the mapping.

AUTHOR

Greg Fast <gdf@speakeasy.net>

COPYRIGHT

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