TemplateM - *ML templates processing module
Version 2.22
08 May 2008
use TemplateM;
use TemplateM 2.22;
use TemplateM 'galore';
use TemplateM 2.22 'galore';
$template = new TemplateM(
-file => 'template_file',
-login => 'user_login',
-password => 'user_password',
-cache => 'cache_files_absolute_path',
-timeout => 'timeout',
-header => 'HTTP_header',
-template => 'HTTP_content'
);
my %htm = ( ... );
$template = new TemplateM(\%htm);
# DEFAULT:
$template->cast({label1=>value1, label2=>value2, ... });
my %h = ( ... );
$template->cast(\%h);
$template->cast_loop ("block_label", {label1=>value1, label2=>value2, ... });
$template->finalize ("block_label);
$template->cast_if('block_label', predicate);
# GALORE:
my $block = $template->start('block_label');
$block->loop(label1 => 'A', label2 => 'B', ... );
$template->stash(label1 => 'value1', label2 => 'value2', ...);
$block->stash(label1 => 'value1', ... );
$template->ifelse("ifblock_label", $predicate)
$block->ifelse("ifblock_label", $predicate)
$block->output;
$block->finish;
$template->output;
$template->html("Content-type: text/html\n\n");
The TemplateM module means for text templates processing in XML, HTML, TEXT and so on formats. TemplateM is the alternative to most of standard modules, and it can accomplish remote access to template files, has simple syntax, small size and flexibility. Then you use TemplateM, functionality and data are completely separated, this is quality of up-to-date web-projects.
Set of methods prodiving process template's structures.
File or array of data which represents the set of instructions, directives and tags of markup languages and statistics.
Name of structure in a template for substitution. There are a number of directives:
cgi, val, do, loop, if, else
Structure is the tag or the group of tags in a template which defining a scope of substitution. The structure consist of tag <!-- --> and formatted content:
DIRECTIVE: LABEL
The structure can be simple or complex. Simple one is like this:
<!-- cgi: foo -->
or
<!-- val: bar -->
Complex structure is the group of simple structures which constitutive a ``section''
<!-- do: foo -->
...
<!-- loop: foo -->
even so:
<!-- if: foo -->
...
<!-- endif: foo -->
<!-- else: foo -->
...
<!-- endelse: foo -->
This is identifier of structure. E.g. foo, bar, baz
<!-- cgi: foo -->
While defining use it can specify 2 accessible schemes - galore or default. It is not obligatory to point at default scheme.
Default scheme is basic and defines using of basic methods:
cast, cast_if, cast_loop, finalize and html
Default scheme methods is expedient for small-datasize projects.
Galore scheme is the alternative for base scheme and it defines own set of methods:
stash, start, loop, finish, ifelse, output and html
In order to get knowing which of schemes is activated you need to invoke methods either module() or scheme()
my $module = $template->module;
my $module = $template->scheme;
In order to get know real module name of the used scheme it's enough to read property 'module' of $template object
my $module = $template->{module};
Constructor new() is the principal method independent of selected scheme. Almost simple way to use the constructor is:
my $template = new TemplateM( -cache => "." );
This invoking takes directive to use template file named index.shtml in current directory and uses the current directory for cache files storage.
Below is the attribute list of constructor:
my $template = new TemplateM( -header => "Content-type: text/html; charset=UTF-8\n\n");
print $template->html;
It is enough to define the module without parameters for using of basic methods.
use TemplateM;
After that only basic metods will be automatically enabled.
Modification of labels (cgi labels)
$template->cast({label1=>value1, label2=>value2, ... });
Block labels modification (val labels)
$template->cast_loop (block_label, {label1=>value1, label2=>value2, ... }]);
Block finalizing
$template->finalize(block_label);
Block finalizing uses for not-processed blocks deleting. You need use finalizing every time you use blockes.
$template->cast_if(ifblock_label, predicate);
Method analyses boolean value of predicate. If value is true, the method prints if-structure content only.
<!-- if: label -->
... blah blah blah ...
<!-- end_if: label -->
otherwise the method prints else-structure content only.
<!-- else: label -->
... blah blah blah ...
<!-- end_else: label -->
Template finalizing
print $template->html(-header=>HTTP_header);
print $template->html(HTTP_header);
print $template->html;
The procedure will return formed document after template processing. if header is present as argument it will be added at the beginning of template's return.
It is enough to define the module with parameter 'galore' for using of galore scheme methods.
use TemplateM 'galore';
stash (or cast) method is the function of import variables value into template.
$template->stash(title => 'PI' , pi => 3.1415926);
This example demonstrate how all of <!-- cgi: title --> and <!-- cgi: pi --> structures will be replaced by parameters of stash method invoking.
In contrast to default scheme, in galore scheme stash method process directives <!-- cgi: label --> only with defined labels when invoking, whereas cast method of default scheme precess all of directives <!-- cgi: label --> in template!
Start method defines the beginning of loop, and finish method defines the end. Start method returns reference to the subtemplate object, that is all between do and loop directives.
<!-- do: block_label -->
... blah blah blah ...
<!-- val: label1 -->
<!-- val: label2 -->
<!-- cgi: label -->
... blah blah blah ...
<!-- loop: block_label -->
my $block = $template->start(block_label);
...
$block->finish;
For acces to val directives it is necessary to use loop method, and for access to cgi directives use stash method.
The method takes as parameters a hash of arguments or a reference to this hash.
$block->loop(label1 => 'A', label2 => 'B');
$block->loop({label1 => 'A', label2 => 'B'});
Stash method also can be invoked in $block object context.
$block->stash(label => 3.1415926);
$template->ifelse("ifblock_label", $predicate)
$block->ifelse("ifblock_label", $predicate)
Method is equal to cast_if method of default scheme. The difference, ifelse method can be processed with $template or $block, whereas cast_if method has deal with $template object.
The method returns result of template processing. Output method has deal with $template and $block object:
$block->output;
$template->output;
The method is completely equal to html method of default scheme.
The module can be used with SSI directives together, like in this shtml-sample:
<html>
<!--#include virtual="head.htm"-->
<body>
<center><!-- cgi: head --><center>
<!-- do: BLOCK_P -->
<p><!-- val: content --></p>
<!-- loop: BLOCK_P -->
</body>
</html>
No environment variables are used.
Please report them.
LWP, CGI
The usual warnings if it cannot read or write the files involved.
1.00 Initial release
1.10 Working with cache ability is added
1.11 Inner method's interface had structured
1.21 New time managment for templates caching. You can set how long template file will be cached before renew.
2.00 New abilities
* Simultaneous templates using errors is eliminated.
* Alternate interface of using methods is added.
* Method of conditional representation of template CAST_IF is added.
2.01 Cache-file access errors corrected
2.20 Module structure has rebuilt and changes has done
* galore scheme added
* update method deleted and constructor interface changed
* errors of cachefile compiling was corrected
(prefix is deleted, CRLF consecution output is corrected)
* UTF-8 codepage for templates added
* mod_perl 1.00 and 2.00 support added
2.21 Mass data processing error under MS Windows is corrected
2.22 Files in the distribution package are changed
* simultaneous multiple declared do-loop structure blocks processing.
Thanks to Dmitry Klimov for technical translating http://fla-master.com.
Lepenkov Sergey (Serz Minus), minus@mail333.com
Copyright (C) 1998-2008 D&D Corporation. All Rights Reserved