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 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.

   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. (Note: for the latter example to
       work correctly, you should set the option "case_sensitive" to a true value.)

       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)>

       (hint: see Number::Format)

       This even extends to references to plain tmpl_vars in your template:

         $t->param( Formatter => Formatter->new,
                    plain     => 'Jane'         );

         <tmpl_var Formatter.reverse(plain)> is
         <tmpl_var plain> backwards

       Note: for "nested" parameters to work correctly, you should supply both params at the same time:

         # for this template snippet,
         <tmpl_var o1.m1(o2.m2)>

         # this works
         $t->param( o1 => $o1, o2 => $o2);

         # but this doesn't
         $t->param( o1 => $o1 );
         $t->param( o2 => $o2 );
         # and neither would swapping the two lines.

         # if your template has another, separate reference to the inner param,
         <tmpl_var o2.m2>
         <tmpl_var o1.m1(o2.m2)>

         # then it works, provided you specify o2 before o1
         $t->param( o2 => $o2 );
         $t->param( o1 => $o1 );

   TMPL_LOOPs
       As of version 0.94, the dot notation is also supported on TMPL_LOOP tags (but see the "LIMITATIONS"
       section).

       Given an object method (or a hash key) that returns an array or a reference to an array, we will unwrap
       that array for use in the loop. Individual array elements are mapped to a hash "{ 'this' => $elt }", so
       that you can refer to them in TMPL_VARs as "this.something".

       An example might help. Let's use the canonical Class::DBI example for our data.  Suppose you have an
       $artist object, which has_many CDs. You can now pass just the $artist object, and handle the loops in the
       template:

         $t->param( artist => $artist );

       The template:

         <tmpl_var artist.name> has released these albums:
         <tmpl_loop artist.cds>
           <tmpl_var this.title> - <tmpl_var this.year>
         </tmpl_loop>

       As you can see, each element from the artist.cds() array is called "this" by default. You can supply your
       own name by appending ': name' like this:

         <tmpl_loop artist.cds:cd>
           <tmpl_var cd.title>
           ...

       That's not the end of it! You can even nest these loops, displaying the Tracks for each CD like so:

         <tmpl_loop artist.cds:cd>
           <tmpl_var cd.title>
           <tmpl_loop cd.tracks:track>
             - <tmpl_var track.title> ( <tmpl_var track.tracktime> )
           </tmpl_loop>
         </tmpl_loop>

   LIMITATIONS
       •   Casing of parameter names

           Casing of parameter names follows the option "case_sensitive" of HTML::Template. If you do not use
           that option, all parameter names are converted to lower case. I suggest turning this option on to
           avoid confusion.

       •   Quotes and spaces

           Because of the way HTML::Template parses parameter names (which follows the rules of HTML
           attributes), you have to be careful when your expressions contain spaces or quote characters. You can
           say "<tmpl_var something.without.spaces>", but not "<tmpl_var something with spaces>". You can use
           single or double quotes around your entire expression, and then use the other one inside: "<tmpl_var
           name="some.method('with arguments')">" This is the recommended way to write your expressions.

           (Note: within expressions, the characters in "[`'"]" are recognised as quote characters. So if you
           need to pass literal quotes to a method, you could do it like this: "<tmpl_var
           name='some.method(`need a " here`)'>". )

   PERFORMANCE
       No attempt to even measure performance has been made. For now the focus is on usability and stability. If
       you carry out benchmarks, or have suggestions for performance improvements, be sure to let us know!

CONTRIBUTING

       Patches, questions and feedback are welcome. This project is managed using the darcs source control
       system ( http://www.darcs.net/ ). A public darcs archive is here:
       http://cgiapp.erlbaum.net/darcs_hive/ht-pluggable/

AUTHORS

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

Copyright & License

        Parts copyright 2006 Mark Stosberg
        Parts copyright 2006 Rhesa Rozendaal

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