Mark Overmeer > OODoc-Template > OODoc::Template

Download:
OODoc-Template-0.16.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.16   Source  

NAME ^

OODoc::Template - Simple template system

SYNOPSIS ^

 use OODoc::Template;
 my $t = OODoc::Template->new;

 my $template = ".....";  # usually read from file
 my %values   = ( a => 3 );

 # list context keeps parse tree as well
 my ($output, $tree) = $t->process($template, \%values);

 # scalar context catches output in string
 my $output = $t->process($template, \%values);
 my $output = $t->process($tree, \%values);
 
 # void context output to selected file-handle
 select OUTPUT;
 $t->process($template, \%values);
 $t->process($tree, \%values);

DESCRIPTION ^

The OODoc::Template module is a light-weight but powerful template system, only providing display needs for applications, not behavior. Let's start with a promise: this module will never grow into a new programming language, as all the other template systems did over time.

There are at least a zillion comparible modules on CPAN, but this one is mine ;-)

Short introduction

If you are used to template systems, then you should read this to get a rapid overview on the features implemented by this module.

METHODS ^

Constructors

OODoc::Template->new(OPTIONS)

Create a new formatter object. All OPTIONS are used as global set of attributes, so used for each template processing started via this object. Probably, it is a good habit to set the required changes of the predefined tags (like template and search) here.

Processing

$obj->process(STRING|SCALAR|ARRAY, HASH|PAIRS)

The template is passed as unprocessed SCALAR to the STRING, or an already parsed template (which is an ARRAY). Values are passed as a HASH or list of PAIRS.

$obj->processFile(FILENAME, HASH|PAIRS)

Process the content of the file with specified FILENAME. The current value of the search path is used as path to find it. The returns behaves the same as process().

If the FILENAME is not found, then undef is returned as output. However, then this method is used in VOID context, there is no output: then an error is raised in stead.

The result of parsing is cached, so there is no need for optimization: call this method as often as you want without serious penalty.

Internal administration

$obj->allValuesFor(TAG, [ATTRIBUTES, THEN, ELSE])

Collects all values related to TAG in all nestings of values. The most preferred is listed first.

$obj->defineMacro(TAG, ATTRIBUTES, THEN, ELSE)
$obj->includeTemplate(TAG, ATTRIBUTES, THEN, ELSE)

This is the implementation for the template tag.

$obj->loadFile(FILENAME)

Returns a string containing the whole contents of the file, or undef if the file was not found.

$obj->popValues()

Remove one level of values.

$obj->pushValues(HASH)

Add new level of values to the known list. The data in the HASH is copied, and a reference to the copy returned. The copy may be changed afterwards.

$obj->valueFor(TAG, [ATTRIBUTES, THEN, ELSE])

Lookup the value for TAG in the known data. See section "values" about the way this is done. The ATTRIBUTES (HASH of key-value pairs) and THEN/ELSE content text references are used when the TAG relates to a code reference which is to produce new values dynamicly.

Parsing

$obj->parse(STRING, (HASH|PAIRS))

This method is deprecated. Please use process().

$obj->parseAttrs(STRING)

Returns an ARRAY of PAIRS which will create the attributes for the called code fragments. The STRING syntax is described in the DETAILS section of this manual page.

$obj->parseTemplate(STRING)

Try to understand the STRING. Returned is a reference to a tree which needs to be called with the correct values.

DETAILS ^

This module works as simple as possible: pass a string to process() with some values to be inserted in the string, and the result is printed to STDOUT.

Getting started

context

There are three ways to produce output via the template system. It depends in which context you call process(), where the output goes to.

. VOID context

the output is sent to the selected file-handle:

 use OODoc::Template;
 my $t = OODoc::Template->new;

 my $template = ".....";  # usually read from file
 my %values   = ( a => 3 );

 open OUTPUT, ">", $filename or die;
 select OUTPUT;

 $t->process($template, \%values);

or

 $t->process($template, a => 3);
. SCALAR context

the output is returned as string:

 my $output = $t->process($parsed, a => 13);
. LIST context

now both the output as the parsed template are returned. You can reuse the parsed templates, improving the performance enormously:

 my ($output, $parsed) = $t->process($template, a => 42);

prepare for performance

When used in a website, you may want to produce the various templates once, before the processes get forked. Just select the output to the null device, and then call all templates once.

   my %top;
   foreach my $lang ( qw/en nl de/ )
   {   my ($output, $parsed) = $t->process($template, lang => $lang);
       $top{$lang} = $parsed;
   }

   print $t->process($top{nl}, a => 42);

Some processing tricks will seriously hinder the caching of the parsed templates. If you use DYNAMIC, then you are on your own. If you use variables in the filenames for included templates, then you may miss the cache.

Expanding variables

The $template string contains HTML with special comment blocks. These special comment blocks are replaced by the specified values. The block can appear in two shapes (which may provided different output):

   <!--{TAG ATTRIBUTES}-->
      some text
   <!--{/TAG}-->

or

   <!--{TAG ATTRIBUTES}-->

The first example shows a container, the second a terminal tag. The TAG is one of the specified values. ATTRIBUTES are used when the TAG is not a constant value, but dynamically produced.

Containers are used to enclose a region where additional values as set. The TAG is related to an ARRAY of HASHes, which are effeciated one after the other, as such creating a loop around this block

Conditionals

The standard conditional structure, which is used everywhere, is the simple container. When the container has values attached to is (always a HASH or ARRAY-of-HASHES filled with key-value pairs), the content is displayed. So, a simple if-then looks like this:

 <!--{want_something ATTRIBUTES}-->
   ...
 <!--{/want_something}-->

The optional ATTRIBUTES are extra values set when processing the container. The pre-defined tag defined can be used to only set attributes: it's a no-op.

You may decide to be more explicit in the if-then, by using the optional IF keyword:

 <!--{IF want_something ATTRIBUTES}-->
   ...
 <!--{/want_something}-->

When the TAG starts with <NOT > or <NOT_>, it is used to negate the boolean interpretation of the values returned by evaluating the tag:

 <!--{NOT want_something ATTRIBUTES}-->
   ...
 <!--{/want_something}-->

An if-then-else looks like this:

 <!--{want_something ATTRIBUTES}-->
   ...
 <!--{ELSE want_something}-->
   ...
 <!--{/want_something}-->

The want_something tag must produce either a HASH or an ARRAY-of-HASHes or undef, because that is what containers do. Because of parser limitations, the

Definition

tags

Tags are barewords (may only contain [0-9a-zA-Z_]), which are looked-up in the %values, which are passed with new() and process() to produce a value.

attributes

Attibutes are values which are used when the text which is to be inserted is produced dynamically. Their syntax is like this:

 # attributes are optionally separated by comma's
 attrs:  attr , attrs
       | attr attrs

 # a hash initiation syntax may be used, but single
 # barewords as well
 attr:   bareword
       | bareword => " string " | bareword = " string "
       | bareword => ' char* '  | bareword = ' char* '
       | bareword => bareword   | bareword = bareword
       | bareword => variable   | bareword = variable

 string: ( char | variable ) *

 # pass value produced by other tag
 variable:
         '$' tag
       | '${' tag attrs '}'

A string may contain variables, which are stringified. This means that tags which produce hashes or arrays are not usuable to interpolate.

values

The values which are related to the tags are rather powerful. When a certain tag can not be found, the value is undef.

the DYNAMIC value

The procedure of a value lookup is quite straight forward: start with the values defined by the innermost block (container) which defined a HASH or ARRAY of HASHes, and work the way back through the enclosing blocks until the initial values have been reached.

If the tag was not found as key, undef is used. If the key was found, than the related value is treated as described in the previous section.

Working through the list of blocks, a miss on a value HASH will cause a second lookup: for the key DYNAMIC. If a block's set of values contains this key, the related CODE reference is called to produce a value. If the produced value is undef, the search will continue to outer blocks. Other results will be treated as any other value.

The DYNAMIC keys may be used like AUTOLOAD: to handle unexpected keys. For instance, used in the initial hash of values (passed to the parse method) it can be used to produce warnings on use of undefined tags.

Pre-defined tags

Tags can as well represent procedures, which are executed to produce data when filling in templates (via CODE references), or represent constants.

Pre-defined values:

. search STRING|ARRAY

A colon separated list of directories, packed in a STRING or an ARRAY of directories, to be searched to find a named template. All search paths are used when a template is being searched for, from inside out defined by the nestings. By default, only the current directory is searched.

. markers ARRAY-of-2..4|STRING

The markers are the open and close patterns which enclose tags which needs processing. Each element can be a STRING or a regular expression. The first two defined the opening of a container, the last two the closing. The third value defaults to the first with a slash appended. The fourth value defaults to the second. You can also use a comma-delimited STRING with three or four values.

The markers are initialized as <--{, }-->, <--{/, and }-->. (I should suffice to define only the first two, because the other follow the default production rules).

Pre-defined procedures:

. define

With this no-op code reference, you set additional values in the environment.

. macro

A name attribute is required. Macro blocks are not inserted on the place where they are defined, but only on the spot where they are used via a template tag. Only the variables available on the moment of application are used, with an exception of the markers, which is taken from the definition environment.

. template

Insert some template. The tag requires either a file or a macro attribute. The filename must be absolute or relative to one of the searched directories. The macro is the name of a pre-declared macro block.

Then the file cannot be found (for instance, when the path name contains a language component but that template has not yet be translated), then the alt (alternative) is attempted if available.

White-space removal

The template tags are usually quite large with respect to the output that they produce. Therefore, you often wish to use more lines in the template file, than will be present in the output. However, you have to help the output processor.

A backslash (followed by any number of invisible blanks) before a new-line will have that new-line, and all following (visually) blank lines removed. When the first line with (visual) content starts with a (start or end) marker, then the blanks before that are removed as well. In other cases, the blanks are left intact.

SEE ALSO ^

This module is part of OODoc-Template distribution version 0.16, built on January 11, 2013. Website: http://perl.overmeer.net/oodoc-template/

LICENSE ^

Copyrights 2003,2007-2013 by [Mark Overmeer]. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://www.perl.com/perl/misc/Artistic.html

syntax highlighting: