The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
HTML-Template-Set-1.009
River stage one • 1 direct dependent • 1 total dependent
++
/ HTML::Template::Set

NAME

HTML::Template::Set - HTML::Template extension adding set support

SYNOPSIS

in your HTML:

  <TMPL_SET NAME="handler">apples_to_oranges</TMPL_SET>
  <TMPL_SET NAME="title">Apples Are Green</TMPL_SET>
  <HTML>
    <HEAD>
      <TITLE><TMPL_VAR NAME="title"></TITLE>
    </HEAD>

    <BODY>
      <H1><TMPL_VAR NAME="title"></H1>
      <HR>
      <BR>
      <B>You authenticated as: </B> <TMPL_VAR NAME="ENV_REMOTE_USER"><BR><BR>
      <TMPL_IF NAME="oranges">You prefer oranges</TMPL_IF>
    </BODY>
  </HTML>

in your script:

  use HTML::Template::Set;

  my $tmpl = new HTML::Template::Set(
    filename      => 'foo.tmpl',
    associate_env => 1
  );

  my $handler = $tmpl->param('handler');
  if ($handler and $handler eq 'apples_to_oranges') {
    $tmpl->param('oranges' => 1);
  }

  print $tmpl->output();

DESCRIPTION

This module provides an extension to HTML::Template that allows params to be set in the template. This is purely an addition - all the normal HTML::Template options, syntax and behaviors will still work. See HTML::Template for details.

The TMPL_SET tags are parsed into params as the HTML::Template object is constructed, so they will be available in your script right away. You can have TMPL_VAR tags inside TMPL_SET tags which are translated each time param is called, and translated upon output.

TMPL_SET tags can span multiple lines, the only caveat being that you cannot nest a TMPL_SET within a TMPL_SET (and at the moment I can see no reason why you would want to).

The basic syntax is as follows:

  <TMPL_SET NAME="mouse">Mickey Mouse Inc 2004</TMPL_SET>

You can also have:

  <TMPL_SET NAME="mouse">
    Mickey Mouse Inc 2004
  </TMPL_SET>

The only thing to note about the above example is that all whitespace after the TMPL_SET tag untill the /TMPL_SET tag is retained. So if you do not wish to have whitespace in your document please use the former example.

The following is also permissable:

  <TMPL_SET NAME="info">
    Information: <TMPL_VAR NAME="description">
    Server Name: <TMPL_VAR NAME="ENV_SERVER_NAME">
  </TMPL_SET>

In this example the TMPL_VAR tags are parsed and translated when 'param' or 'output' is called. That means in your script you can update the param as many times as you like and have the TMPL_SET param automatically updated (this can also be seen as a downside if you wanted a constant TMPL_SET tag, i may add an option in future to allow for this).

When a TMPL_SET tag is parsed its stripped from the document unlike TMPL_VAR's and TMPL_IF's that leave whitespace in their place. This was done because in every case I can think of having alot of TMPL_SET tags will result in a chunk of whitespace left in the document (which is unsightly).

MOTIVATION

I had a mod_perl application that worked in an opposite direction, that being the templates were handled by a 'handler'. So for the 'handler' to know how to handle the template I needed to set a paramater in the template. The old templating system I was using supported this, but didnt handle nested if's very well and I wanted to use HTML::Template. I decided I would write this module, now I can have <TMPL_SET NAME="handler">index</TMPL_SET> and sub index will be called to handle my template.

BASIC SYNTAX

A TMPL_SET tag is essentially the same format as a TMPL_IF tag, however it cannot be nested and obviously does a very different thing.

  <TMPL_SET NAME="one">1</TMPL_SET>

  <TMPL_VAR NAME="one">

  <TMPL_SET NAME="two">two is not <TMPL_VAR NAME="one"></TMPL_SET>

Environment variables can be used just like any other param, except they are prefixed by 'ENV_'.

  <TMPL_VAR NAME="ENV_REMOTE_ADDR">

  <TMPL_IF NAME="ENV_HTTPS"> </TMPL_IF>

OPTIONS

TMPL_SET Options

  • set_order_bottom_up - if set to 1 the order the params are set by TMPL_SET changes so that the last included file's TMPL_SET becomes the param (usually I prefer the first file to be where I set the param from so I can set defaults in the included file). Defaults to 0.

  • chomp_after_set - if set to 1 all empty lines after a /TMPL_SET tag are taken out of the final output (I find this useful if I want to put a space between my TMPL_SET tags and the HTML markup, but dont want that space in the HTML it spits out). Defaults to 1.

ENV Options

  • associate_env - if set to 1 once 'output' is called the %ENV hash will be associated with any params that match 'ENV_{ENV KEY}' (i.e. ENV_SERVER_NAME). Defaults to 0.

  • env_names_to_lower_case - if set to 1 all ENV_ params will be in lowercase (instead of ENV_SERVER_NAME it will be env_server_name). This only applies when the HTML::Template option case_sensitive is on (as you can specify upper or lower, or mixed case if its not turned on). Defaults to 0.

CAVEATS

Currently the module forces the HTML::Template global_vars option to be set. This is because the TMPL_SET params and the ENV_ params will not work inside loops otherwise, as they have no scoping at all. If you for some reason do not want global vars to be turned on you need to manually turn it off but keep in mind the TMPL_SET params and ENV_ params will not be available in your loops.

Wrapping a TMPL_SET inside a TMPL_IF will at the moment have no effect, and likewise putting a TMPL_IF, TMPL_LOOP or anything other than a TMPL_VAR inside a TMPL_SET will just spit out the tags as is.

NOTES

If you are getting an error and cant work out what file its occuring on the best idea is to turn debug on (see HTML::Template for how to do this). The reason being, when the TMPL_SET's are parsed the filter has no idea what file is being processed as its not passed that information, so with debug turned on you will be able to see what the last INCLUDE loaded was and the line number in the error message will make more sense.

BUGS

I am aware of no bugs - if you find one, just drop me an email and i'll try and nut it out (or email a patch, that would be tops!).

CREDITS

I would like to thank the author of HTML::Template for writing such a useful perl module:

   Sam Tregar

SEE ALSO

HTML::Template

AUTHOR

David J Radunz <dj@boxen.net>

LICENSE

HTML::Template::Set : HTML::Template extension adding set support

Copyright (C) 2004 David J Radunz (dj@boxen.net)

This module is free software; you can redistribute it and/or modify it under the terms of either:

a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or

b) the "Artistic License" which comes with this module.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details.

You should have received a copy of the Artistic License with this module, in the file ARTISTIC. If not, I'll be glad to provide one.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA