Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
HTML::Template::PluginUsertContributed Perl DocuHTML::Template::Plugin::Dot(3)

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

	 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

       For example, in your code:

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

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


       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.

   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:


       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:


       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>

   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

       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

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

       The template:

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

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

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

       o   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`)'>". )

       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!

       Patches,	questions and feedback are welcome. This project is managed
       using the darcs source control system ( ).	A
       public darcs archive is here:

       Mark Stosberg, <>; Rhesa Rozendaal,

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.

perl v5.32.1			  2007-05-17	HTML::Template::Plugin::Dot(3)


Want to link to this manual page? Use this URL:

home | help