/ 
HTML-Template-Pluggable-0.04
River stage one • 4 direct dependents • 4 total dependents
/ HTML::Template::Plugin::Dot

NAME

HTML::Template::Plugin::Dot - Add Magic Dot notation to HTML::Template

SYNOPSIS

use HTML::Template::Pluggable;
use HTML::Template::Plugin::Dot;

my $t = HTML::Template::Pluggable->new(...);

Now you can use chained accessor calls and nested hashrefs as params, and access them with a dot notation. You can even pass basic arguments to the methods.

For example, in your code:

$t->param( my_complex_struct => $struct );

And then in your template you can reference specific values in the structure:

my_complex_struct.key.obj.accessor('hash')
my_complex_struct.other_key

DESCRIPTION

By adding support for this dot notation to HTML::Template, the programmers job of sending data to the template is easier, and designers have easier access to more data to display in the template, without learning any more tag syntax.

The dot notation is supported on the following tags: <TMPL_VAR>, <TMPL_IF> and <TMPL_UNLESS>.

EXAMPLES

Class::DBI integration

Class::DBI accessors can be used in the template. If the accessor is never called in the template, that data doesn't have to be loaded.

In the code:

$t->param ( my_row => $class_dbi_obj );

In the template:

my_row.last_name

This extends to related objects or inflated columns (commonly used for date fields). Here's an example with a date column that's inflated into a DateTime object:

my_row.my_date.mdy('/')
my_row.my_date.strftime('%D')

Of course, if date formatting strings look scary to the designer, you can keep them in the application, or even a database layer to insure consistency in all presentations.

Here's an example with related objects. Suppose you have a Customer object, that has_a BillingAddress object attached to it. Then you could say something like this:

<tmpl_if customer.billing_address>
  <tmpl_var customer.billing_address.street>
  <tmpl_var customer.billing_address.city>
  ...
</tmpl_if>

More complex uses

The dot notation allows you to pass arguments to method calls (as in the my_date.dmy('/') example above). In fact, you can pass other objects in the template as well, and this enables more complex usage. Imagine we had a (fictional) Formatter object which could perform some basic string formatting functions. This could be used in e.g. currencies, or dates.

In your code:

$t->param( Formatter => Formatter->new,
           order	   => $order_obj     );

In your template:

Amount: <tmpl_var Formatter.format_currency('US',order.total_amount)>

LIMITATIONS

  • TMPL_VARs inside of loops won't work unless a simple patch is applied to HTML::Template. We hope it will be updated with this patch soon.

    http://rt.cpan.org/NoAuth/Bug.html?id=14037

    Alternately, you can apply the patch to your own copy.

  • TMPL_LOOPs are not (yet) supported. You still need to pass an array of hashrefs yourself.

  • Casing of hash keys follows the option case_sensitive of HTML::Template. If you do not use that option, all parameter names are converted to lower case.

CONTRIBUTING

Patches, questions and feedback are welcome. This project is managed using the darcs source control system ( http://www.darcs.net/ ). My darcs archive is here: http://mark.stosberg.com/darcs_hive/ht-dot/

AUTHORS

Mark Stosberg, <mark@summersault.com>; Rhesa Rozendaal, <rhesa@cpan.org>

Copyright & License

Parts copyright 2005 Mark Stosberg
Parts copyright 2005 Rhesa Rozendaal

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