.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "HTML::Template::Plugin::Dot 3pm"
.TH HTML::Template::Plugin::Dot 3pm "2011-01-04" "perl v5.10.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
HTML::Template::Plugin::Dot \- Add Magic Dot notation to HTML::Template
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use HTML::Template::Pluggable;
\&  use HTML::Template::Plugin::Dot;
\&
\&  my $t = HTML::Template::Pluggable\->new(...);
.Ve
.PP
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.
.PP
For example, in your code:
.PP
.Vb 1
\&  $t\->param( my_complex_struct => $struct );
.Ve
.PP
And then in your template you can reference specific values in the structure:
.PP
.Vb 2
\&  my_complex_struct.key.obj.accessor(\*(Aqhash\*(Aq)
\&  my_complex_struct.other_key
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.SS "\s-1EXAMPLES\s0"
.IX Subsection "EXAMPLES"
.SS "Class::DBI integration"
.IX Subsection "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.
.PP
In the code:
.PP
.Vb 1
\&  $t\->param ( my_row => $class_dbi_obj );
.Ve
.PP
In the template:
.PP
.Vb 1
\&  my_row.last_name
.Ve
.PP
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:
.PP
.Vb 2
\&  my_row.my_date.mdy(\*(Aq/\*(Aq)
\&  my_row.my_date.strftime(\*(Aq%D\*(Aq)
.Ve
.PP
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.
.PP
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:
.PP
.Vb 5
\&  <tmpl_if customer.billing_address>
\&    <tmpl_var customer.billing_address.street>
\&    <tmpl_var customer.billing_address.city>
\&    ...
\&  </tmpl_if>
.Ve
.SS "More complex uses"
.IX Subsection "More complex uses"
The dot notation allows you to pass arguments to method calls (as in the 
\&\f(CW\*(C`my_date.dmy(\*(Aq/\*(Aq)\*(C'\fR 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.
.PP
In your code:
.PP
.Vb 2
\&  $t\->param( Formatter => Formatter\->new,
\&             order         => $order_obj     );
.Ve
.PP
In your template:
.PP
.Vb 1
\&  Amount: <tmpl_var Formatter.format_currency(\*(AqUS\*(Aq,order.total_amount)>
.Ve
.PP
(hint: see Number::Format)
.PP
This even extends to references to plain tmpl_vars in your template:
.PP
.Vb 2
\&  $t\->param( Formatter => Formatter\->new,
\&             plain     => \*(AqJane\*(Aq         );
\&
\&  <tmpl_var Formatter.reverse(plain)> is
\&  <tmpl_var plain> backwards
.Ve
.SS "TMPL_LOOPs"
.IX Subsection "TMPL_LOOPs"
As of version 0.94, the dot notation is also supported on \s-1TMPL_LOOP\s0 tags (but
see the \*(L"\s-1LIMITATIONS\s0\*(R" section).
.PP
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 \f(CW\*(C`{ \*(Aqthis\*(Aq => $elt }\*(C'\fR, so that you can refer
to them in TMPL_VARs as \*(L"this.something\*(R".
.PP
An example might help. Let's use the canonical Class::DBI example for our data.
Suppose you have an \f(CW$artist\fR object, which has_many CDs. You can now pass just
the \f(CW$artist\fR object, and handle the loops in the template:
.PP
.Vb 1
\&  $t\->param( artist => $artist );
.Ve
.PP
The template:
.PP
.Vb 4
\&  <tmpl_var artist.name> has released these albums:
\&  <tmpl_loop artist.cds>
\&    <tmpl_var this.title> \- <tmpl_var this.year>
\&  </tmpl_loop>
.Ve
.PP
As you can see, each element from the artist.\fIcds()\fR array is called \*(L"this\*(R" by
default. You can supply your own name by appending ': name' like this:
.PP
.Vb 3
\&  <tmpl_loop artist.cds:cd>
\&    <tmpl_var cd.title>
\&    ...
.Ve
.PP
That's not the end of it! You can even nest these loops, displaying the Tracks
for each \s-1CD\s0 like so:
.PP
.Vb 6
\&  <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>
.Ve
.SS "\s-1LIMITATIONS\s0"
.IX Subsection "LIMITATIONS"
.IP "\(bu" 4
Casing of parameter names
.Sp
Casing of parameter names follows the option \f(CW\*(C`case_sensitive\*(C'\fR 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.
.IP "\(bu" 4
Quotes and spaces
.Sp
Because of the way HTML::Template parses parameter names (which follows the
rules of \s-1HTML\s0 attributes), you have to be careful when your expressions contain
spaces or quote characters. You can say
\&\f(CW\*(C`<tmpl_var something.without.spaces>\*(C'\fR, but not
\&\f(CW\*(C`<tmpl_var something with spaces>\*(C'\fR. You can use single or double quotes
around your entire expression, and then use the other one inside:
\&\f(CW\*(C`<tmpl_var name="some.method(\*(Aqwith arguments\*(Aq)">\*(C'\fR This is the recommended
way to write your expressions.
.Sp
(Note: within expressions, the characters in \f(CW\*(C`[\`\*(Aq"]\*(C'\fR are recognised as
quote characters. So if you need to pass literal quotes to a method, you could
do it like this: \f(CW\*(C`<tmpl_var name=\*(Aqsome.method(\`need a " here\`)\*(Aq>\*(C'\fR. )
.SS "\s-1PERFORMANCE\s0"
.IX Subsection "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!
.SH "CONTRIBUTING"
.IX Header "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/
.SH "AUTHORS"
.IX Header "AUTHORS"
Mark Stosberg, <mark@summersault.com>;
Rhesa Rozendaal, <rhesa@cpan.org>
.SH "Copyright & License"
.IX Header "Copyright & License"
.Vb 2
\& Parts copyright 2006 Mark Stosberg
\& Parts copyright 2006 Rhesa Rozendaal
.Ve
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as perl itself.