The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
HTML-KTemplate-1.33
River stage zero No dependents
++
/ HTML::KTemplate

NAME

HTML::KTemplate - Perl module to process HTML templates.

SYNOPSIS

CGI-Script:

  #!/usr/bin/perl -w
  use HTML::KTemplate;
  
  $tpl = HTML::KTemplate->new('path/to/templates');
  
  $tpl->assign( TITLE  => 'Template Test Page'    );
  $tpl->assign( TEXT   => 'Some welcome text ...' );
  
  foreach (1 .. 3) {
  
      $tpl->assign( LOOP,
          TEXT => 'Just a test ...',
      );
  
  }
  
  $tpl->process('template.tpl');
  
  $tpl->print();

Template:

  <html>
  <head><title>[% TITLE %]</title>
  <body>
  
  Hello! [% TEXT %]<p>
  
  <!-- BEGIN LOOP -->  
  
  [% TEXT %]<br>
  
  <!-- END LOOP -->
  
  </body>
  </html>

Output:

  Hello! Some welcome text ...
  
  Just a test ...
  Just a test ...
  Just a test ...

MOTIVATION

Although there are many different template modules at CPAN, I couldn't find any that would meet my expectations. So I created this one with following features:

  • Template syntax can consist only of variables and blocks.

  • Support for multidimensional data structures.

  • Everything is very simple and very fast.

  • Still there are many advanced options available.

Please email me any comments, suggestions or bug reports to <kasper@repsak.de>.

VARIABLES

By default, template variables are embedded within [% %] and may contain any alphanumeric characters including the underscore and the hyphen. The values for the variables are assigned with assign(), passed as a hash or a hash reference.

  %hash = (
      VARIABLE => 'Value',
  );
  
  $tpl->assign( %hash );
  $tpl->assign(\%hash );
  $tpl->assign( VARIABLE => 'Value' );

To access a multidimensional hash data structure, the variable names are separated by a dot. In the following example, two values for the variables [% USER.NAME %] and [% USER.EMAIL %] are assigned:

  $tpl->assign(
  
      USER => {
          NAME  => 'Kasper Dziurdz',     # [% USER.NAME %]
          EMAIL => 'kasper@repsak.de',   # [% USER.EMAIL %]
      },
      
  );

If the value of a variable is a reference to a subroutine, the subroutine is called and the returned string is included in the output. This is the only way to execute Perl code in a template.

  $tpl->assign(
  
      BENCHMARK => sub {
          # get benchmark data
          return 'created in 0.01 seconds';
      }
  
  );

BLOCKS

Blocks allow you to create loops and iterate over a part of a template or to write simple if-statements. A block begins with <!-- BEGIN BLOCKNAME --> and ends with <!-- END BLOCKNAME -->. This is an example of creating a block with the block() method:

  $tpl->assign( HEADER  => 'Some numbers:' );
  
  @block_values = ('One', 'Two', 'Three', 'Four');
  
  foreach (@block_values) {
  
      $tpl->block('LOOP_NUMBERS');
      $tpl->assign( NUMBER    => $_ );
      $tpl->assign( SOMETHING => '' );
  
  }
  
  $tpl->block();  # leave block
  
  $tpl->assign( FOOTER => '...in words.' );

Each time block() is called it creates a new loop in the selected block. All variable values passed to assign() are assigned only to this loop until a new loop is created or block() is called without any arguments to assign global variables again. This is a template for the script above:

  [% HEADER %]
  
  <!-- BEGIN LOOP_NUMBERS -->
  
    [% NUMBER %]
  
  <!-- END LOOP_NUMBERS -->
  
  [% FOOTER %]

Global variables (or outer block variables) are also available inside a block. However, if there is a block variable with the same name, the block variable is preferred.

Because a block is a normal variable with an array reference, blocks can also be created without the block() method:

  $tpl->assign( 
      HEADER  => 'Some numbers:',
      LOOP_NUMBERS => 
          [
              { NUMBER => 'One'   },
              { NUMBER => 'Two'   },
              { NUMBER => 'Three' },
              { NUMBER => 'Four'  },
          ],
      FOOTER => '...in words.',
  );

Loops within loops work as you would expect. To create a nested loop with block(), you have to pass all block names separate as a list or joined with a dot, for example as BLOCK_1.BLOCK_2. This way, a new loop for BLOCK_2 is created in the last loop of BLOCK_1. The variable values are assigned with assign().

  foreach (@block_one) {
  
      $tpl->block('BLOCK_1');
      $tpl->assign(VAR => $_);
  
      foreach (@block_two) {
  
          $tpl->block('BLOCK_1', 'BLOCK_2');
          $tpl->assign(VAR => $_);
  
      }
  }
  
  $tpl->block();  # leave block

The template would look like this:

  <!-- BEGIN BLOCK_1 -->
  
      <!-- BEGIN BLOCK_2 -->
  
      <!-- END BLOCK_2 -->
  
  <!-- END BLOCK_1 -->

Important: You have to call block() without any arguments to assign global variables again.

It is also possible to create a loop with the assign() method by passing the block name as the first argument (or all block names joined with a dot to create nested loops). The variables can be assigned only once and not as a hash reference but there is no need to use the block() method.

  $tpl->assign( BLOCK,  # assign to this block
      VARIABLE_1 => 'Block ...',
      VARIABLE_2 => 'Block ...',
  );
  
  $tpl->assign(  # assign global again
      VARIABLE_3 => 'Global ...'.
  );

Blocks can even be used to create if-statements. Simply assign a variable with a true or false value. Based on that, the block is skipped or included in the output.

  $tpl->assign( SHOW_INFO  => 1 );  # show block SHOW_INFO
  $tpl->assign( SHOW_LOGIN => 0 );  # skip block SHOW_LOGIN

For a better control of the loop output, three special loop variables can be made available inside a loop: FIRST, INNER and LAST. This variables are disabled by default (see OPTIONS section how to enable them).

  <!-- BEGIN LOOP -->
  
  
      <!-- BEGIN FIRST -->
       First loop pass
      <!-- END FIRST -->
  
  
      <!-- BEGIN INNER -->
       Neither first nor last
      <!-- END INNER -->
  
  
      <!-- BEGIN LAST -->
       Last loop pass
      <!-- END LAST -->
  
  
  <!-- END LOOP -->

INCLUDES

Includes are used to process and include the output of another template file directly into the current template in place of the include tag. All variables and blocks assigned to the current template are also available inside the included template.

  <!-- INCLUDE file.tpl -->
  
  <!-- INCLUDE "file.tpl" -->
  
  <!-- INCLUDE 'file.tpl' -->

If the template can't be found under the specified file path (considering the root path), the path to the enclosing file is tried. See OPTIONS section how to disable includes or change the limit for recursive includes.

It is possible to include template files defined by a variable when the option for including variables is enabled (it is disabled by default).

  <!-- INCLUDE VARIABLE -->

ADVANCED

Although it is possible to create loops and if statements with the block tag, sometimes the template syntax might get too confusing or not allow to write the wanted conditions in an easy way. For this reason if, unless, else and loop tags are available.

  <!-- IF VARIABLE -->
  
  <!-- END VARIABLE -->
   
   
  <!-- UNLESS VARIABLE -->
 
  <!-- END VARIABLE -->
   
   
  <!-- LOOP ARRAY -->
  
  <!-- END ARRAY -->
   
   
  <!-- IF VARIABLE -->
  
  <!-- ELSE VARIABLE -->
  
  <!-- END VARIABLE -->

The else tag can be used with all statements, even with loops. For an even cleaner template syntax, the else and the end tag can be written without the variable name.

  <!-- BEGIN ARRAY -->
  
  <!-- END -->
   
   
  <!-- IF VARIABLE -->
  
  <!-- ELSE -->
  
  <!-- END -->

The following syntax is also allowed but will not work with the block tag:

  <!-- IF VARIABLE -->
  
  <!-- ELSE -->
  
  <!-- END IF -->
   
   
  <!-- LOOP ARRAY -->
  
  <!-- END LOOP -->

METHODS

new()

Creates a new template object.

  $tpl = HTML::KTemplate->new();
  
  $tpl = HTML::KTemplate->new('/path/to/templates');
  
  $tpl = HTML::KTemplate->new( 
      root         => '/path/to/templates',
      cache        => 0,
      strict       => 0,
      no_includes  => 0,
      max_includes => 15,
      loop_vars    => 0,
      blind_cache  => 0,
      include_vars => 0,
      parse_vars   => 0,
  );

assign()

Assigns values for the variables used in the template.

  %hash = (
      VARIABLE => 'Value',
  );
  
  $tpl->assign( %hash );
  $tpl->assign(\%hash );
  $tpl->assign( VARIABLE => 'Value' ); 
    
  $tpl->assign( BLOCK,
      VARIABLE => 'Value',
      VARIABLE => 'Value',
  );

block()

See the description of BLOCKS.

  $tpl->block('BLOCK_1');
  
  $tpl->block('BLOCK_1','BLOCK_2');
  $tpl->block('BLOCK_1.BLOCK_2');
  
  $tpl->block();  # leave block

process()

The process() method is called to process the template files passed as arguments. It loads each template file, parses it and adds it to the template output. It is also possible to pass a reference to a scalar, array or file handle to initialize the template from memory. The use of the template output is determined by the print() or the fetch() method.

  $tpl->process('header.tpl', 'footer.tpl');
  
  $tpl->process('header.tpl');
  $tpl->process('footer.tpl');
  
  $tpl->process(\$scalar);
  $tpl->process(\@array);
  $tpl->process(\*FH);

print()

Prints the output data to STDOUT. If a file handle reference is passed, it is used instead of the standard output.

  $tpl->print();
  
  $tpl->print(\*FILE);

fetch()

Returns a scalar reference to the output data.

  $output_ref = $tpl->fetch();
  
  print FILE $$output_ref;

clear()

Clears all variable values and other data being held in memory (except cache data).

  $tpl->clear();

Equivalent to:

  $tpl->clear_vars();
  $tpl->clear_out();

clear_vars()

Clears all assigned variable values.

  $tpl->clear_vars();

clear_out()

Clears all output data created by process().

  $tpl->clear_out();

clear_cache()

Empties all cache data.

  $tpl->clear_cache();

OPTIONS

Variable Tag

  $HTML::KTemplate::VAR_START_TAG = '[%';
  $HTML::KTemplate::VAR_END_TAG   = '%]';

Block Tag

  $HTML::KTemplate::BLOCK_START_TAG = '<!--';
  $HTML::KTemplate::BLOCK_END_TAG   = '-->';

Include Tag

  $HTML::KTemplate::INCLUDE_START_TAG = '<!--';
  $HTML::KTemplate::INCLUDE_END_TAG   = '-->';

Root

  $HTML::KTemplate::ROOT = undef;  # default
  $HTML::KTemplate::ROOT = '/path/to/templates';
  
  $tpl = HTML::KTemplate->new( '/path/to/templates' );
  $tpl = HTML::KTemplate->new( root => '/path/to/templates' );

No Includes

Set this option to 1 to disable includes. The include tags will be skipped unless the strict option is set to 1.

  $tpl = HTML::KTemplate->new( no_includes => 0 );  # default
  $tpl = HTML::KTemplate->new( no_includes => 1 );

Max Includes

Allows to set the maximum depth that includes can reach. An error is raised when this depth is exceeded.

  $tpl = HTML::KTemplate->new( max_includes => 15 );  # default

Include Vars

Allows to include template files defined by a variable (see the description of INCLUDES for more information).

  $tpl = HTML::KTemplate->new( include_vars => 0 );  # default
  $tpl = HTML::KTemplate->new( include_vars => 1 );

Cache

Caching option for a persistent environment like mod_perl. Parsed templates will be cached in memory based on their file path and modification date. Use clear_cache() to empty cache.

  $tpl = HTML::KTemplate->new( cache => 0 );  # default
  $tpl = HTML::KTemplate->new( cache => 1 );

Blind Cache

Behaves as the normal caching option but does not check the modification date to see if the template has changed. This might result in some speed improvement over normal caching.

  $tpl = HTML::KTemplate->new( blind_cache => 0 );  # default
  $tpl = HTML::KTemplate->new( blind_cache => 1 );

Loop Vars

Set this option to 1 to enable the loop variables FIRST, INNER and LAST.

  $tpl = HTML::KTemplate->new( loop_vars => 0 );  # default
  $tpl = HTML::KTemplate->new( loop_vars => 1 );

The default loop variables can be changed in the following way:

  $HTML::KTemplate::FIRST = { 'FIRST' => 1, 'first' => 1 };
  $HTML::KTemplate::INNER = { 'INNER' => 1, 'inner' => 1 };
  $HTML::KTemplate::LAST  = { 'LAST'  => 1, 'last'  => 1 };

Parse Vars

Set this option to 1 to parse variables. That way all template variables inside of a variable will be replaced with their assigned values.

  $tpl = HTML::KTemplate->new( parse_vars => 0 );  # default
  $tpl = HTML::KTemplate->new( parse_vars => 1 );

Strict

Set this option to 1 to raise errors on not defined variables and include tags when disabled.

  $tpl = HTML::KTemplate->new( strict => 0 );  # default
  $tpl = HTML::KTemplate->new( strict => 1 );

Chomp

Removes the newline before and after a block tag.

  $HTML::KTemplate::CHOMP = 1;  # default
  $HTML::KTemplate::CHOMP = 0;

MAILING LIST

If you want to get email when a new version of HTML::KTemplate is released, join the announcements mailing list:

  http://lists.sourceforge.net/lists/listinfo/html-ktemplate-announce

A mailing list for discussing HTML::KTemplate is available at <html-ktemplate-users@lists.sourceforge.net>. To join, visit:

  http://lists.sourceforge.net/lists/listinfo/html-ktemplate-users

You can also email me questions, comments, suggestions or bug reports directly to <kasper@repsak.de>.

WEBSITE

More information about HTML::KTemplate can be found at:

  http://html-ktemplate.sourceforge.net/

COPYRIGHT

  Copyright (c) 2002-2003 Kasper Dziurdz. All rights reserved.
  
  This module is free software; you can redistribute it and/or
  modify it under the same terms as Perl itself.
  
  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 the
  Artistic License for more details.

AUTHOR

Kasper Dziurdz <kasper@repsak.de>