/ 
HTML-KTemplate-1.21
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 (@some_data) {

    $tpl->block('LOOP');
    $tpl->assign( 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 main features:

  • Template syntax can consist only of variables and blocks.

  • Support for multidimensional data structures.

  • Everything is very simple and very fast.

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 -->. The following example shows the easiest way to create a block:

$tpl->assign( HEADER  => 'Some numbers:' );

@block_values= ('One', 'Two', 'Three', 'Four');

foreach ( @block_values ) {

    $tpl->block('LOOP_NUMBERS');
    $tpl->assign( NUMBER => $_ );

}

$tpl->block();   # leave the 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 access global variables again).

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

Here is an example of a template for the script above:

[% HEADER %]

<!-- BEGIN LOOP_NUMBERS -->

  [% NUMBER %]

<!-- END LOOP_NUMBERS -->

[% FOOTER %]

Because a block is a normal variable with an array reference, blocks can also be created (faster) 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 blocknames separated by a dot, for example BLOCK_1.BLOCK_2. This way, a new loop called 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($_);

    foreach (@block_two) {

        $tpl->block('BLOCK_1.BLOCK_2');  # block name is just BLOCK_2
        $tpl->assign($_);

    }
}

Blocks can also 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 also 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 won't work with the begin block:

<!-- LOOP ARRAY -->

<!-- END LOOP -->

<!-- IF VARIABLE -->

<!-- ELSE IF -->

<!-- END IF -->

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',
    loop_vars    => 0,
    cache        => 0,
    blind_cache  => 0,
    max_includes => 15,  
    no_includes  => 0,
    strict       => 0,
);

assign()

Assigns values for the variables used in the templates. Accepts a hash or a hash reference.

%hash = (
    VARIABLE => 'Value',
);

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

block()

See the description of BLOCKS.

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. 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');

print()

Prints the output data to STDOUT. If a filehandle 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 filepath 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 };

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;

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>