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.

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