HTML::Template::Pro always use die_on_bad_params => 0. It currently can't be changed, because HTML::Template::Pro can't know whether a parameter is bad until it finishes output.

Note that it is wrapper-only option: it is not implemented in the htmltmplpro C library.

In the original HTML::Template, if the "force_untaint" option is set an error occurs if you try to set a value that is tainted in the param() call. In HTML::Template::Pro, an error occurs when output is called.

Note that the tainted value will never be printed; but, to completely suppress output, one should use call to output() that returns string, like print $tmpl->output(); Then output() will die before it returns the string to print.

Note that it is wrapper-only perl-specific option: it is not implemented in the htmltmplpro C library.

   <TMPL_HUH NAME=ZUH>
    

Would normally cause an error, but if you call new with strict => 0, HTML::Template will ignore it. Defaults to 1.

HTML::Template::Pro always implies strict => 0.

Example:

   my $template = HTML::Template->new( filename => 'file.tmpl',
                                       path => [ '/path/to/templates',
                                                 '/alternate/path'
                                               ]
                                      );
    

NOTE: the paths in the path list must be expressed as UNIX paths, separated by the forward-slash character ('/').

  my $query = new CGI;
  my $template = HTML::Template->new(filename => 'template.tmpl',
                                     associate => $query);
    

Now, "$template->output()" will act as though

  $template->param('FormField', $cgi->param('FormField'));
    

had been specified for each key/value pair that would be provided by the "$cgi->param()" method. Parameters you set directly take precedence over associated parameters.

You can specify multiple objects to associate by passing an anonymous array to the associate option. They are searched for parameters in the order they appear:

  my $template = HTML::Template->new(filename => 'template.tmpl',
                                     associate => [$query, $other_obj]);
    

NOTE: If the option case_sensitive => 0, the parameter names are matched in a case-insensitive manner. If you have two parameters in a CGI object like 'NAME' and 'Name' one will be chosen randomly by associate. This behavior can be changed by setting option case_sensitive to 1.

  my $template = HTML::Template->new(filename => 'template.tmpl',
                                     case_sensitive => 1);
  $template->param(
    FieldA => 'foo',
    fIELDa => 'bar',
  );
    

This option defaults to off to keep compatibility with HTML::Template. Nevertheless, setting case_sensitive => 1 is encouraged, because it significantly improves performance.

If case_sensitive is set to 0, the perl wrapper is forced to lowercase keys in every hash it will find in "param" tree, which is sometimes an expensive operation. To avoid this, set case_sensitive => 1.

If case conversion is necessary, there is an alternative lightweight option tmpl_var_case, which is HTML::Template::Pro specific.

Note that case_sensitive is wrapper-only option: it is not implemented in the htmltmplpro C library.

For example, in case of <tmpl_var name="CamelCaseName"> setting tmpl_var_case = ASK_NAME_AS_IS | ASK_NAME_LOWERCASE | ASK_NAME_UPPERCASE will cause HTML::Template::Pro to look into "param" tree for 3 names: CamelCaseName, camelcasename, and CAMELCASENAME.

By default, the name is asked "as is".

In addition to the above, a __counter__ var is also made available when loop context variables are turned on.

Example:

   <TMPL_LOOP NAME="FOO">
      <TMPL_IF NAME="__first__">
        This only outputs on the first pass.
      </TMPL_IF>

      <TMPL_IF NAME="__odd__">
        This outputs every other pass, on the odd passes.
      </TMPL_IF>

      <TMPL_UNLESS NAME="__odd__">
        This outputs every other pass, on the even passes.
      </TMPL_UNLESS>

      <TMPL_IF NAME="__inner__">
        This outputs on passes that are neither first nor last.
      </TMPL_IF>

      This is pass number <TMPL_VAR NAME="__counter__">.

      <TMPL_IF NAME="__last__">
        This only outputs on the last pass.
      </TMPL_IF>
   </TMPL_LOOP>
    

One use of this feature is to provide a "separator" similar in effect to the perl function join(). Example:

   <TMPL_LOOP FRUIT>
      <TMPL_IF __last__> and </TMPL_IF>
      <TMPL_VAR KIND><TMPL_UNLESS __last__>, <TMPL_ELSE>.</TMPL_UNLESS>
   </TMPL_LOOP>
    

Would output (in a browser) something like:

  Apples, Oranges, Brains, Toes, and Kiwi.
    

Given an appropriate "param()" call, of course. NOTE: A loop with only a single pass will get both __first__ and __last__ set to true, but not __inner__.

NOTE: in the original HTML::Template with case_sensitive = 1 and loop_context_vars the special loop variables are available in lower-case only. In HTML::Template::Pro they are recognized regardless of case.

Example:

  This is a normal variable: <TMPL_VAR NORMAL>.<P>

  <TMPL_LOOP NAME=FROOT_LOOP>
     Here it is inside the loop: <TMPL_VAR NORMAL><P>
  </TMPL_LOOP>
    

Normally this wouldn't work as expected, since <TMPL_VAR NORMAL>'s value outside the loop is not available inside the loop.

The global_vars option also allows you to access the values of an enclosing loop within an inner loop. For example, in this loop the inner loop will have access to the value of OUTER_VAR in the correct iteration:

   <TMPL_LOOP OUTER_LOOP>
      OUTER: <TMPL_VAR OUTER_VAR>
        <TMPL_LOOP INNER_LOOP>
           INNER: <TMPL_VAR INNER_VAR>
           INSIDE OUT: <TMPL_VAR OUTER_VAR>
        </TMPL_LOOP>
   </TMPL_LOOP>
    

NOTE: "global_vars" is not "global_loops" (which does not exist). That means that loops you declare at one scope are not available inside other loops even when "global_vars" is on.

Example: {{{ <TMPL_LOOP NAME=class> <TMPL_LOOP NAME=person> <TMPL_VAR NAME="../teacher_name"> <!-- access to class.teacher_name --> <TMPL_VAR NAME="name"> <TMPL_VAR NAME="/top_level_value"> <!-- access to top level value --> <TMPL_VAR NAME="age"> <TMPL_LOOP NAME="../../school"> <!-- enter loop before accessing its vars --> <TMPL_VAR NAME="school_name"> <!-- access to [../../]school.school_name --> </TMPL_LOOP> </TMPL_LOOP> </TMPL_LOOP> }}}

In the most simple usage, you simply assign a code reference to the filter parameter. This subroutine will receive a single argument - a reference to a string containing the template file text. Here is an example that accepts templates with tags that look like "!!!ZAP_VAR FOO!!!" and transforms them into HTML::Template tags:

   my $filter = sub {
     my $text_ref = shift;
     $$text_ref =~ s/!!!ZAP_(.*?)!!!/<TMPL_$1>/g;
   };

   # open zap.tmpl using the above filter
   my $template = HTML::Template->new(filename => 'zap.tmpl',
                                      filter => $filter);
    

More complicated usages are possible. You can request that your filter receive the template text as an array of lines rather than as a single scalar. To do that you need to specify your filter using a hash-ref. In this form you specify the filter using the "sub" key and the desired argument format using the "format" key. The available formats are "scalar" and "array". Using the "array" format will incur a performance penalty but may be more convenient in some situations.

   my $template = HTML::Template->new(filename => 'zap.tmpl',
                                      filter => { sub => $filter,
                                                  format => 'array' });
    

You may also have multiple filters. This allows simple filters to be combined for more elaborate functionality. To do this you specify an array of filters. The filters are applied in the order they are specified.

   my $template = HTML::Template->new(filename => 'zap.tmpl',
                                      filter => [ 
                                           { sub => \&decompress,
                                             format => 'scalar' },
                                           { sub => \&remove_spaces,
                                             format => 'array' }
                                        ]);
    

The specified filters will be called for any TMPL_INCLUDEed files just as they are for the main template file.