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

NAME

Qtpl - Parse text files from saved templates and substitutes variables

SYNOPSIS

        use Qtpl;
        $q = new Qtpl('template.html');
        $q->assign('SIMPLEVAR', $SIMPLEVAL);
        $q->assign('HASHVAR', {id => $id, name => $name} );
        for ($i=0;$i<3;$i+){
                $q->assign('rowid', $i);
                $q->parse('main.row');
        }
        $q->parse('main');
        $q->out('main');

DESCRIPTION

Qtpl (Quick Template) module handles substitution of variables in text files. Templates are splitted into blocks which may be displayed once, sometimes or to not displayed at all, depending on the logic of your program.

For example, such approach is very useful for display db query results. Also supported is display of conditional "IF" blocks. The module allows to put the result of processing in a variable, thus you may do email templates, for example.

TEMPLATES SYNTAX

Templates are stored in files. Basically a template you want to display is written in HTML code. It contains all blocks at once. You can repeat it as many times as you need it in code later.

BLOCKS

Block is the basic concept of this library. It contains some piece of text. Here's an example of a template:

File: first_template.qtpl

    <!-- BEGIN: main -->
         <HTML>
         <HEAD><TITLE>First Template</TITLE></HEAD>
         <BODY>
                         Hello world!
         </BODY>
         </HTML>
    <!-- END: main -->

There is a block named 'main'. It contains all your html-code. Blocks can be enclosed. How show this template to user? There is small example:

        use Qtpl;
        $q = new Qtpl("first_example.qtpl");
        $q->parse('main');
        $q->out('main');

 The beginning of the block is made out as follows:
   <!-- BEGIN: block_name -->
 The end of the block is made out as:
   <!-- END: block_name -->

All spaces there is optional. Syntax of these definitions can be customized by call set_block_start_delim, set_block_end_delim, set_block_start_word and set_block_end_word methods.

There are 2 kind of blocks: usual and ordered.

Usual blocks

Blocks occur always in the same place (and in the same order) as in an template. Their occurence is independent from the order you call parse().

Ordered blocks

But you can define special blocks named 'ordered'. To achieve this, add :your_block_type to block name. For example:

    <!-- BEGIN: main -->
        <!-- BEGIN: usual -->
                Usual blocks:
                <!-- BEGIN: row1 -->Row1u<!-- END: row1 -->
                <!-- BEGIN: row2 -->Row2u<!-- END: row2 -->
            <!-- END: usual -->
            <!-- BEGIN: ordered -->
                Ordered blocks:
                <!-- BEGIN: row:1 -->Row1o<!-- END: row:1 -->
                <!-- BEGIN: row:2 -->Row2o<!-- END: row:2 -->
            <!-- END: ordered -->
    <!-- END: main -->

We call :

        $q = new Qtpl('template.qtpl');
        $q->parse('main.usual.row1');
        $q->parse('main.usual.row2');
        $q->parse('main.usual.row1');
        $q->parse('main.usual.row2');
        $q->parse('main.usual');

        $q->parse('main.ordered.row:1');
        $q->parse('main.ordered.row:2');
        $q->parse('main.ordered.row:1');
        $q->parse('main.ordered.row:2');
        $q->parse('main.ordered');

        $q->parse('main'); $q->out('main');

Result:

        Usual blocks:
                        Row1u
                        Row1u
                        Row2u
                        Row2u

        Ordered blocks:
                        Row1o
                        Row2o
                        Row1o
                        Row2o

VARIABLES

Variables occuring while parsing are replaced with the values declared by you. For any variable a substitute value can be assigned using the assign method.

There is 3 methods to assign variables:

Simple variables

Simple variable assignment is done as : $q->assign('VARIABLE_IN_TEMPLATE', $variable_value); Your template must contain such a string: some text..{VARIABLE_IN_TEMPLATE}..bla..bla

The variable in the template is substituted by the 'assign'-ed value.

Hash variables

You may assign a whole hash in a pattern, using only the assign call only once.

 This is achieved using these syntax:
       $q->assign('HASH',{'row_id'=>1,'row_value'=>2});

 Your template can contain string:
       .....{HASH.row_id}...{HASH.row_value}..

 You would get there :
       .....1...2 ..

Attention! You should assign hash reference, not hash itself! Use $q->assign('h', \%hash) instead of $q->assign('h', %hash);

Predefined variables

These are variables which are given implicitly. In Perl versions you may address to all global namespace. For example: ..{main::ENV.HTTP_HOST}....{main::var1}......

can print your WWW hostname (if you run it from CGI) and value of $var1. You don't need do a special call to assign it.

IF BLOCKS

Example: {IF img}<IMG SRC="{img}">{ELSE}NO IMAGE{END IF} So we may show IMG tag when value have not null and show NO IMAGE message if is not present. IF blocks cannot be enclosed.

FILE INCLUSION

You can include external files into your template. It will be done with {FILE "filename"} syntax.

OBJECT METHODS

new ($template_filename)

The 'new' method returns the object handle by which the template is initialized. File is completely readed and splitted by 'original blocks'. Is any error occured, set_error private method is called. set_error will call 'die' function.

assign ($var_name, $var_value)

Assign method assign $var_value to variable $var_name in template. The assigned $var_value is stored in a internal structure and substitutes $var_name on futher 'parse' calls. $var value can be a scalar value or a hash reference.

parse ($block_name)

Parse takes the 'original block', substitutes all known variables by the 'assign'-ed values, substitutes possibly enclosed blocks for which call 'parse' was made and adds the resulting text to 'parse value' of the given $block_name.

text ($block_name)

Text return 'parsed value' of $block_name. It will return empty string if block has never been parsed.

out ($block_name)

Text print 'parsed value' of $block_name. It will print nothing if block has never been parsed.

set_null_string set_null_string ($null_value [,$var_name])

Function set value which will be used as substitute in case that the value of variable is not known. in case value of a variable is not known. If the 'assign' call was not made. If $var_name that it is specified is done only for the specified variable.

set_null_block ($null_block, [,$block_name])

Does the same that the set_null_string function for blocks.

set_autoreset

Set that all enclosed blocks will be reset after the 'parse' call for the parent block is made. Is true by default.

clear_autoreset

Set that all enclosed blocks will not be reset after the 'parse' call for the parent block is made. Is true by default.

STATIC FUNCTIONS

block_start_delim([$start_delim])

No comments. Default value is: '<!--'. Return old value.

block_end_delim ([$end_delim])

Default value is: '<!--'.

block_start_word ([$start_word])

Default value is 'BEGIN:'.

block_end_word ([$end_word])

Default value is 'END:'

var_begin ([$var_begin])

Default value is '{'

var_end ([$var_end])

Default value is '}'

file_delim ([$file_begin])

Default value is string: "\{FILE\s*\"(.+?)\"\s*\}". Change it as you need.

HISTORY

This module is complete rewrite of PHP XTemplate engine by <cranx@scene.hu>. IF processing and ordered blocks added only by Perl version while.

AUTHOR

All bug reports, gripes, adulations, and comments can be sent to Alexey Presnyakov <alexey_pres@users.sourceforge.net>.

Thanks to Paul Miller's this document translation.

http://qtpl.sourceforge.net/