/ 
HTML-KTemplate-1.01
River stage zero No dependents
/ HTML::KTemplate

NAME

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

SYNOPSIS

Perl code:

use KTemplate;

$tpl = KTemplate->new('path/to/templates');

$tpl->assign( TITLE => 'Template Test Page' );

%hash = (
    TEXT => 'Some welcome text ...',
    USER => {
        NAME => 'Kasper Dziurdz',
        EMAIL => 'kasper@repsak.de',
    },
);

$tpl->assign( \%hash );

for (1 .. 3) {
    $tpl->block('LOOP');
    $tpl->assign( TEXT => 'Just a test ...' );
}

$tpl->process('header.tpl', 'body.tpl') || die $tpl->error();
 
$tpl->print();

Template:

+--------- -- -- - - -  -  -   -
| [% TITLE %]
+--------- -- -- - - -  -  -   -

Hello [% USER.NAME %]! [% TEXT %]

Your eMail: [% USER.EMAIL %]

<!-- BEGIN LOOP -->

[% TEXT %]

<!-- END LOOP -->

Output:

+--------- -- -- - - -  -  -   -
| Template Test Page
+--------- -- -- - - -  -  -   -

Hello Kasper Dziurdz! Some welcome text ...

Your eMail: kasper@repsak.de

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:

  • No statements in the template files, only variables and blocks.

  • Support for multidimensional data structures.

  • Everything is very simple and (i believe) pretty 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',
        EMAIL => 'kasper@repsak.de',
    },
    
);

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

METHODS

new()

Creates a new template object.

$tpl = KTemplate->new();

$tpl = KTemplate->new( '/path/to/templates' );
$tpl = KTemplate->new( ROOT => '/path/to/templates' );

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 describtion of BLOCKS.

process()

The process() method is called to process the template files passed as arguments. It loads each template file and parses it into perl code. After all files are parsed the perl code is evaluated and the template output is created. The use of the template output is determined by the print() or the fetch() method.

$tpl->process(

    'header.tpl',
    'body.tpl',
    'footer.tpl',

) || die $tpl->error();

print()

Prints the output data to STDOUT.

$tpl->print();

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 (only needed for CGI scripts in a persistent environment like mod_perl).

$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();

error()

On error, the process() method returns false (undef). Then the error() method can be called to retrieve details of the error.

$tpl->process() || die $tpl->error();

OPTIONS

Variable Tag

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

Block Tag

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

Root

$KTemplate::ROOT = undef;  # default
$KTemplate::ROOT = '/path/to/templates';

$tpl = KTemplate->new( '/path/to/templates' );
$tpl = KTemplate->new( ROOT => '/path/to/templates' );

Chomp

Deletes all whitespace characters preceding a block tag.

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

COPYRIGHT

Copyright (c) 2002 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>