EXAMPLES

Class::DBI integration

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

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

TMPL_LOOPs

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