/ 
dTemplate-2.5
River stage zero No dependents
/ dTemplate

NAME

dTemplate - A simple yet powerful template handling logic with advanced features.

$Id: dTemplate.pod 105 2004-07-24 12:08:22Z dlux $

$URL: http://svn.dlux.hu/public/dTemplate/trunk/dTemplate.pod $

SYNOPSIS

use dTemplate;

# definition 

$mail_template = dTemplate->new( file => "mail_tmpl.txt" );

$template = dTemplate->new( text => "<html>$BODY$</html>" ),



# parsing
$mail = $mail_template->parse(
    FROM    => {
        first_name => "Balazs",
        last_name  => "Szabo",
        email      => "dlux@dlux.hu"
    },
    TO      => "foo@bar.com",
    SUBJECT => $subject,
    BODY    => 
        sub { $email_type==3 ? $body_for_type_3 : $body_for_others },
    SIGNATURE=> $signature_template->parse( KEY => "value" )
);

print "Please send this mail:\n$mail";

where mail_tmpl.txt is:

    From    : "$FROM.first_name$ $FROM.last_name$" <$FROM.email$> 
    To      : $TO$
    Subject : $SUBJECT$

    Message body:
    $BODY$

    $SIGNATURE$

### Advanced feature: Styling

# Style definition
$style= { lang =>'hungarian', color=>'white' };

# Selector definition
$html_template = dTemplate->new(choose => $style,
    'hungarian+white' => 
        dTemplate->new(file => "hun_white_template.html"),
    'spanish'         => 
        dTemplate->new(file => "spanish.html"),
    'black+hungarian' => 
        dTemplate->new(file => "hun_black_template.html"),
    'english'         => 
        dTemplate->new(file => "english_template.html"),
    'empty'           => 
        "<html>This is a text, $BODY$ is NOT substituted!!!!"</html>",
    # default:
    ''                => 
        dTemplate->new(text => "<html>$BODY$</html>"),
);

# Selector definition
$body_template = dTemplate->new(choose => $style,
    'hungarian'       =>  
        dTemplate->new(file => "sziasztok_emberek.html"),
    'spanish'         =>  
        dTemplate->new(file => "adios_amigos.html"),
    # default:
    ''                =>  
        dTemplate->new(file => "bye_bye.html"),
);

print  $html_template->parse(BODY  =>  $body_template->parse());
    # will  print  "sziasztok_emberek.html"  in  the
    # "hun_white_template.html"

%$style = ();
print $html_template->parse(BODY => $body_template->parse());
    #  will print "bye_bye.html" surrounded by "<html>" and "</html>" tags.

%$style = ( lang => 'english' );
print $html_template->parse(BODY => $body_template->parse());
    # will print the "bye_bye.html" in of the "english_template.html"

### Advanced feature: Changing placeholder special characters:

$dTemplate::START_DELIMITER     = '<%\s*'; # default: \$
$dTemplate::END_DELIMITER       = '\s*%>'; # default: \$
$dTemplate::VAR_PATH_SEP        = '\/';    # default: \.
$dTemplate::PRINTF_SEP          = '\$';    # default: %+
$dTemplate::ENCODER_SEP         = '\@';    # default: \*+
$dTemplate::ENCODER_PARAM_START = '\(';    # default: \/
$dTemplate::ENCODER_PARAM_END   = '\)';    # default:

# dTemplate 2.2 Compatibility:
$template1 = define dTemplate "mail.txt";

$template2 = text dTemplate "This is the template text...";

$template3 = choose dTemplate \%hash, ...;

DESCRIPTION

This module is aimed to be a fast, general-purpose, lightweight but easily extendible templating system.

With this module, you can write template-parsing routines in the way the templates are structured logically: starting from outside to inside. Your code will be clear, well-structured and easy to understand. This logic can be attained using by inline subroutines as values of template variables. (Look at the example at the end of the document)

USAGE

A template is a text data (usually taken from a file), which contains special placeholders for variables.. A template object (a dTemplate::Template object) is basically the representation of this text data. The "placeholders" contain informations about:

  • What data to be written into the placeholder: the name and the "path" of the variable.

  • How the data is to be formatted and processed.

The format of a placeholder

A placeholder in a text file has the following format: (the format can be customized, see below)

$varname%printf_def*encoder_def$

, where:

varname

It is the name of the variable, which can be any string with alphanumeric characters. The "." in the varname has a special meaning, see the "Data Lookup" section below.

%printf_def

This is an optional part. Used only, when you want to format the output by printf before substitution. You can use as many '%' as you want here, it can be used to pad the variable, for example when your output is a table. E.g:

$MONEY%%%%%%011d$

is a valid placeholder.

*encoder_def

Encoders are specifal subroutines, which are used, to process a data before substitution. They works like "pipe" in UNIX. They got the data in the first parameter, and the return value will be substituted. They can be chained, so more than one encoder can be used for one value. In this case the encoders will be executed in the order of definition.

Encoders are separated with "*", and can have one parameter, which is separated with "/" from the encoder name.

There are some built-in encoders in dTemplate:

- u          : url-encoder
- h          : HTML-encoder (converts > to &gt;, etc)
- ha         : Advanced HTML encoder (\n => <BR>, tabs => spaces)
- uc         : convert the string to uppercase
- lc         : convert the string to lowercase
- eq/par     : returns true if the encoded string is "par"
- if/par     : returns "par" if the encoded string is true
- printf/par : returns printf formatted data, where "par" is the format
               string

Chaining of the encoders:

$TITLE*uc*h$

or

$weight*eq/7*if/CHECKED$

(the last example returns CHECKED if the weight is equal to "7", useful for radio-buttons or drop-down menus in HTML)

Read more on encoders (and how to make new encoders) in the Encoders part.

Template objects

There are three ways to create template objects

From a file:

$template = dTemplate->new( file => $filename );

From a scalar variable:

$template = dTemplate->new( text => "<html>$BODY$</html>" ),

Using the template chooser:

$template = dTemplate->new( choose => $style_hash_ref,
    "style1" => $dTemplate_object1,
    "style2" => $dTemplate_object2,
    ...
);

Note, the template chooser is not a "real" template object. It is a meta-object (a dTemplate::Choose object), which selects one of many real template objects based on the contents of a style hash. Read more about the chooser later.

Parsing

Once you have the template object, you can use them to create output by substituting and formatting data into the placeholders.

The parsing is done by the objects' parse methods. The return value of the parse method is the substituted text.

The variable substitution is done in following steps:

- Look for the data to substitute
    - Look for the data among the parameters of the parse method.
    - Look for the data among the parameters of the template
      object's parse hash ($obj->parsehash->{$varname})
    - Look for the data among the keys of %dTemplate::parse hash
- Process "path" information in the placeholder
- If we have not found the variable, then we use the value of the ""
  key of the object's parsehash ($obj->parsehash->{""}) if exists, or
  the $dTemplate::parse{""} if exists.
- If the value is a code reference, then we call it to return the
  value.
- Use the encoders on the returned value
- Use the printf-formatter on the returned value

Looking for the data to substitute

Each substitution is started by looking up the substitutable variable name. If the variable name contains path information (contains "." characters), then, it is not used at this step, so only the information before the first "." is used.

The parse method looks for the substitutable variable name in three places:

- Among the parameters of the parse method
- Among the keys of local parsehash ($object->parsehash)
- Among the keys of dTemplate::parse hash

Looking for the data in the parameters of the parse method

The parse method can have parameters in the following format:

- List of name => value pairs
- Hash-reference.

For example:

my $hashref = {
        name2 => $value2, 
        name3 => $value3
};

$template->parse(
    name => $value,
    $hashref,
    name4 => $value4,
    { name5 => $value5 },
    ...
)

This method call defines "name", "name2", "name3", "name4" and "name5" variable names, so they will be substituted in the $template object with $value, $value2, $value3, $value4 and $value5.

Looking for the data in the local parsehash

If we encounter a variable reference in the template placeholders, that is not assigned among the parameters of parse method, then we look up the variable in keys of the local parsehash of the dTemplate object. You can assign values to the local parsehash with the following expression:

$obj->parsehash->{key} = $value;

or you can assign hash-reference to multiple objects:

$obj1->parsehash = $obj2->parsehash = { key1 => "v1", key2 => "v2" };

If we found it, then we use its value for further processing.

Looking for the data in the dTemplate::parse hash

If we did not find the variable even in the local parsehash, then we look up the variable in keys of the global dTemplate::parse hash. If we found it, then we use its value for further processing.

Processing "path" information

After we have found the variable in the previous phase among the parameters of the parse method or in the dTemplate::parse hash, we process the "path" information in the placeholder if we have it.

Path information is appended to the variable name by "."-s.

If the variable definition in the placeholder contains "path", then we assume that the variable is a hash-reference, and we tries to access the specified hash key in it. For example in $template, you define the following placeholder:

$name3.key1.key2$

If you assign $value3 to name3 (in the parameter-list of the parse method or in the $dTemplate::parse{name3} hash), then it is not simply substitute $value3, but it tries to use the $value3 as a hash reference, and looks up a key in it with the name "key1". If it is found, then it tries to use the value as a hash reference, and looks up a key in it with the name "key2", and its value will be substituted:

$value3 = { key1 => { key2 => "This will be substituted" } };

If the value, which is found is a code reference, then we stop the key-lookup and call the sub e.g:

$value3 = { key1 => sub { return "This will be substituted"; } }

Using data in $obj->parsehash->{""} as value

If we did not find the referenced value by the process described above, then we use the the value of the "" hash-key of the object's parsehash instead of the variable. If it is a code-reference, then it is called exactly like it was the variable that has found, e.g:

$obj->parsehash->{""} = sub { "Fallback value for this template"; }

Using data in $dTemplate::parse{""} as value

If we did not find the referenced value by the process described above, then we use the the value of $dTemplate::parse{""} hash-key instead of the variable. If it is a code-reference, then it is called exactly like it was the variable that has found.

Calling code references

We can assign code references to variables, they will be called if we encounter the variable, which needs substitution.

The function-call will have the following parameters:

- Full matched placeholder as the first argument
- An array reference to the splitted variable and path information as a
  second argument.
- The dTemplate::Template object in which you called the "parse"
  method.

For example if a placeholder is like to this:

$HASH1.key1.key2*uc$

and the parsing code is the following:

$t1->parse(
    # ...
    HASH1 => sub { my ($placeholder, $pathref, $object) = @_;
        warn "Placeholder: $placeholder, Variable path:".@$pathref."\n";
        # ...
    }
);

Then it will print the following message to the standard error:

Placeholder: $HASH1.key1.key2*uc$, Variable path: HASH1 key1 key2

Calling encoders

If we have the data, which substitutes the placeholder, then we can encode them or format them by the dTemplate encoders. The encoders are code references, which are assigned the the values of the %dTemplate::ENCODERS hash. Names of the encoders are the keys of the hash.

Encoders are called in the order of declaration in the template, so

$variable*uc*h$

is not the same as

$variable*h*uc$

An encoder can have one optional parameter, which can be provided in the placeholder, e.g:

$weight*eq/7*if/CHECKED$

(the last example returns CHECKED if the weight variable is equal to "7", useful for radio-buttons or drop-down menus in HTML)

Note, that by default, the encoders are NOT called, if we did not find the variable and we are using the local key of the local parsehash or $dTemplate::parse. This is a feature, not a bug, because the "" keys are designed to be used only to report errors or warnings, like this:

use Carp qw(cluck);
$dTemplate::parse{""} = sub {
    cluck "$_[0] is not assigned";
    return "";
}

If you want to use the $dTemplate::parse{""} value (or the local parsehash's "" key) as it was a normal value, then set the $dTemplate::NOTASSIGNED_MODE variable to true. In this case, the encoders and the formatter are called on the value of $dTemplate::parse{""} also.

For example, if the $dTemplate::parse{""} is assigned to the subroutine above, and if $dTemplate::NOTASSIGNED_MODE is false (by default), the

$noassigned_variable%03d$

will be substituted with an empty string, but if it is true, it is substituted to "000" (because the formatter is called).

The parameter-list of an encoder if it is called:

- The encodable text
- The (optional) encoder parameter
- The dTemplate::Template object in which the parsing is done

Changing placeholder special characters

You can change the placeholder parameters by changing (or localizing) the following variables.

$dTemplate::START_DELIMITER     = '\$';
$dTemplate::END_DELIMITER       = '\$';
$dTemplate::VAR_PATH_SEP        = '\.';
$dTemplate::PRINTF_SEP          = '%+';
$dTemplate::ENCODER_SEP         = '\*';
$dTemplate::ENCODER_PARAM_START = '\/';
$dTemplate::ENCODER_PARAM_END   = '';

If you change these variables, then these are used in the compilation of the following templates. Currently there is no supported way to recompile an already compiled template, so you need to create a new instance.

Although if you want to compile a variable, which is not compiled, then you can call the $template->compile method on them by hand.

These variables can be set to any regular expressions, not just one single character.

If you don't want to use any of the features, then set the corresponding variable to any regexp that is too complex to be true.

Styles (Template choosers)

You can use the "chooser" to dynamically select one template from many based on styles.

The current "style" is represented by a hash, for example:

my %style = (lang => 'spanish', color => 'white');

Based on informations in the hash, the chooser (which is a dTemplate::Choose object) decides which dTemplate::Template object is used in the parse operation.

dTemplate::Choose object also has a parse method, and it is compatible with the parse method of dTemplate::Template, so you can use it transparently.

When you define a template chooser object in the following way:

$template = dTemplate->new( choose => \%style,
    "style1" => $dTemplate_object1,
    "style2" => $dTemplate_object2,
    "style3" => $dTemplate_object3,
    "style3+style4" => $dTemplate_object4,
    ...
);

, then you get a wrapper object, which wraps several dTemplate::Template objects, which selects $dTemplate_object1 if "style1" is active, $dTemplate_object2 if "style2" is active, $dTemplate_object3 if "style3" and "style4" is active, etc.

If you call the "parse" method of this template, then it selects one of the dTemplate objects ($dTemplate_object1, $dTemplate_object2, etc.) and calls the parse method of them.

The chooser selects the template, which has the most "style" matched.

For example if the style hash is:

%style = (first_style => "style3", second_stype => "style99");

Then

$template->parse(...)

calls the parse method of $dTemplate_object3, but if

%style = (first_style => "style3", second_stype => "style4");

then it activates the $dTemplate_object4.

Note, that the keys in the %style hash has no meaning.

COMPATIBILITY

Old-style constructors

Old-style constructors ("define dTemplate", "choose dTemplate", "text dTemplate") is obsoleted, but still can be used. The preferred way to call the "new" method in new programs.

Prior 2.3

dTemplate v2.3 removes the default value of $dTemplate::parse{""}. In the pre 2.3 versions, $dTemplate::parse{""} was a code reference, which returned the first parameter of it.

HINTS

Template compilation

In the first parse of every template, the templates will be compiled. It is used to speed up parsing.

%dTemplate::parse localization

Don't forget that %dTemplate::parse can be localized. This means you can define local-only variable assignments in a subroutine:

local %dTemplate::parse = ( 
    %dTemplate::parse, 
    local_name => $value 
);

References and encoders

You don't need to use text as the input value of an encoder, you can use any scalar, even references! If you want (for example) print a date by a date encoder, which expects the date to be an array ref of [ year, month, day ], then you can do this, e.g:

$dTemplate::ENCODERS{date} = sub {
    return "" if ref($_[0]) ne 'ARRAY';
    return $_[0]->[0]."-".$_[0]->[1]."-".$_[0]->[2];
}

Then, when you put $START_DATE*date$ to a template, you can parse this template:

$template->parse(
  START_DATE => [2000,11,13],
  ...
);

Magical (tied) hashes

You can use magical hashes everywhere in the "parse" method parameter list, where you can use normal hashes, but because I redesigned the "parse" method with the speed with the first priority, it works quite a bit different than the older ( <= 2.0 ) versions.

At template-compile time, the "compile" method collects the variable names, which are found in that template, and the "parse" method knows which variables are required for processing this template.

When the "parse" method realizes that a parameter is a hash reference, then it always tries all the remaining template variables (which are not assigned in the preceding part of the parameter list) in that hash reference.

Imagine the following situation:

$template->parse( name => "blow", \%hash);

... where %hash is a magical hash, and the $template contains the "name", "address" and "method.type" variables. When the parse method meets with the \%hash, the "name" is already assigned, so it olny tries to read the $hash{address} and $hash{method} variables.

This is not a problem with normal hashes, but if you use magical hashes, you may have a very expensive FETCH function, and this effect can cause problems.

There are two way to work around it:

  • Use qualified variable names. If you use the following form of parse:

    $template->parse( name => "blow", data => \%hash);

    ... then the %hash is called only when the template parser finds the "data.address" and "data.method.type" variable references in the template. Of course, you have to change the template variable names also.

  • Use the hash instead of a hash reference:

    $template->parse( name => "blow", %hash);

    In this case, the magical hash is iterated through when the parameter list is assembled. This is better only if you are afraid of random key retrieval, but it can be also slow, if the FIRSTKEY, NEXTKEY and FETCH operations are slow.

    But if the random-key retrieval is not a problem for your magical hash, then use the default form instead of this, because that requires less operation (only one FETCH).

EXAMPLE

It is an example, which contains most of the features this module has. It is not intended to be a real-world example, but it can show the usage of this module.

This example consists of one program, and some template modules.

The executable version of this program can be found in the example directory of the module distribution.

use dTemplate;

### definition of the standard templates

my @TEMPLATE_LIST=qw(page table_row table_cell);
my $templates={};
foreach my $template (@TEMPLATE_LIST) {
  $templates->{$template} = 
    define dTemplate("templates/$template.htm");
}

### definition of the styled templates (styles = languages)

my @STYLES=qw(eng hun);
my @STYLED_TEMPLATE_LIST=qw(table_title);

my $style_select={ lang => 'hun' }; 

foreach my $template (@STYLED_TEMPLATE_LIST) {
  my @array=();
  foreach my $style (@STYLES) {
    push @array, $style => 
      define dTemplate("text/$style/$template.txt");
  }
  $templates->{$template} = 
    choose dTemplate $style_select, @array;
}

### setting up input data

my $table_to_print=[
  [ "Buwam",   3, 6, 9 ],
  [ "Greg",    8, 4, 2 ],
  [ "You're",  8, 3, 4 ],
  [ "HTML chars: <>", 3],
];

### setting up the global parse hash with parse parameters;

$dTemplate::parse{PAGENO}=7;

### settings up a hash with personal data.

my $person_hash={
  name => { first_name => "Greg" },
  zip  => "9971",
};

### this hash is simply added to other parse parameters

my $parse_hash={
  "unknown" => { data => 157 },
};

### the main page parse routine

print $templates->{page}->parse(
  TABLE_TITLE =>             # name => value pair
    $templates->{table_title}->parse(),
  TABLE => sub {             # name => value pair. value is a sub
    my $ret="";
    foreach my $row (@$table_to_print) {
      $ret .= $templates->{table_row}->parse(
        BODY => sub {
          my $ret="";
          foreach my $cell (@$row) {
            $ret .= $templates->{table_cell}->parse(
              TEXT => $cell,
            )
          }
          return $ret;
        }
      )
    }
    return $ret;
  },
  "person" => $person_hash,  # name => value pair. value is a href
  $parse_hash,               # only a hash with parse parameters
);

And the templates:

templates/page.htm:
<html>
<body>

<h1>$TABLE_TITLE*h$</h1>

<table>
$TABLE$
</table>

<br>
Person name: $person.name*h$, zip code: $person.zip*h$
<br>

Unknown data: $unknown.data*h$
<br>

Page: $PAGENO%02d*h$

</body>
</html>
templates/table_row.htm:
<tr>$BODY$</tr>
templates/table_cell.htm:
<td>$TEXT*h$</td>
text/eng/table_title.txt:
Table 1
text/hun/table_title.txt:
1. táblázat

COPYRIGHT

Copyrigh (c) 2000-2001 Szabó, Balázs (dLux)

All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

dLux (Szabó, Balázs) <dlux@kapu.hu>

SEE ALSO

perl(1), HTML::Template, Text::Template, CGI::FastTemplate, Template.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 763:

Non-ASCII character seen before =encoding in 'táblázat'. Assuming CP1252