Template::Manual::Config is a Perl module with template configuration options.
< b >Template Style and Parsing Options< /b >
START_TAG, END_TAG
The START_TAG and END_TAG options are used to specify character sequences or regular expressions that mark the start and end of a template directive. The default values for START_TAG and END_TAG are '[%' and '%]' respectively, giving us the familiar directive style:
[% example %]
Any Perl regex characters can be used and therefore should be escaped (or use the Perl quotemeta function) if they are intended to represent literal characters.
my $template = Template- >new({
START_TAG = > quotemeta('< +'),
END_TAG = > quotemeta('+ >'),
});
example:
< + INCLUDE foobar + >
The TAGS directive can also be used to set the START_TAG and END_TAG values on a per-template file basis.
[% TAGS < + + > %]
TAG_STYLE
The TAG_STYLE option can be used to set both START_TAG and END_TAG according to pre-defined tag styles.
my $template = Template- >new({
TAG_STYLE = > 'star',
});
Available styles are:
template [% ... %] (default)
template1 [% ... %] or %% ... %% (TT version 1)
metatext %% ... %% (Text::MetaText)
star [* ... *] (TT alternate)
php < ? ... ? > (PHP)
asp < % ... % > (ASP)
mason < % ... > (HTML::Mason)
html < !-- ... -- > (HTML comments)
Any values specified for START_TAG and/or END_TAG will over-ride those defined by a TAG_STYLE.
The TAGS directive may also be used to set a TAG_STYLE
[% TAGS html %]
< !-- INCLUDE header -- >
PRE_CHOMP, POST_CHOMP
Anything outside a directive tag is considered plain text and is generally passed through unaltered (but see the INTERPOLATE option). This includes all whitespace and newlines characters surrounding directive tags. Directives that don't generate any output will leave gaps in the output document.
Example:
Foo
[% a = 10 %]
Bar
Output:
Foo
Bar
The PRE_CHOMP and POST_CHOMP options can help to clean up some of this extraneous whitespace. Both are disabled by default.
my $template = Template-E< gt >new({
PRE_CHOMP =E< gt > 1,
POST_CHOMP =E< gt > 1,
});
With PRE_CHOMP set to 1, the newline and whitespace preceding a directive at the start of a line will be deleted. This has the effect of concatenating a line that starts with a directive onto the end of the previous line.
Foo E< lt >----------.
|
,---(PRE_CHOMP)----'
|
`-- [% a = 10 %] --.
|
,---(POST_CHOMP)---'
|
`-E< gt > Bar
With POST_CHOMP set to 1, any whitespace after a directive up to and including the newline will be deleted. This has the effect of joining a line that ends with a directive onto the start of the next line.
If PRE_CHOMP or POST_CHOMP is set to 2, all whitespace including any number of newline will be removed and replaced with a single space. This is useful for HTML, where (usually) a contiguous block of whitespace is rendered the same as a single space.
With PRE_CHOMP or POST_CHOMP set to 3, all adjacent whitespace (including newlines) will be removed entirely.
These values are defined as CHOMP_NONE, CHOMP_ONE, CHOMP_COLLAPSE and CHOMP_GREEDY constants in the Template::Constants module. CHOMP_ALL is also defined as an alias for CHOMP_ONE to provide backwards compatability with earlier version of the Template Toolkit.
Additionally the chomp tag modifiers listed below may also be used for the PRE_CHOMP and POST_CHOMP configuration.
my $template = Template-E< gt >new({
PRE_CHOMP =E< lt > '~',
POST_CHOMP =E< gt > '-',
});
PRE_CHOMP and POST_CHOMP can be activated for individual directives by placing a '-' immediately at the start and/or end of the directive.
[% FOREACH user IN userlist %]
[%- user -%]
[% END %]
This has the same effect as CHOMP_ONE in removing all whitespace before or after the directive up to and including the newline. The template will be processed as if written:
[% FOREACH user IN userlist %][% user %][% END %]
To remove all whitespace including any number of newlines, use the '~' character instead.
[% FOREACH user IN userlist %]
[%~ user ~%]
[% END %]
To collapse all whitespace to a single space, use the '=' character.
[% FOREACH user IN userlist %]
[%= user =%]
[% END %]
Here the template is processed as if written:
[% FOREACH user IN userlist %] [% user %] [% END %]
If you have PRE_CHOMP or POST_CHOMP set as configuration options then you can use '+' to disable any chomping options (i.e. leave the whitespace intact) on a per-directive basis.
[% FOREACH user = userlist %]
User: [% user +%]
[% END %]
With POST_CHOMP set to CHOMP_ONE, the above example would be parsed as if written:
[% FOREACH user = userlist %]User: [% user %]
[% END %]
For reference, the PRE_CHOMP and POST_CHOMP configuration options may be set to any of the following:
Constant Value Tag Modifier
----------------------------------
CHOMP_NONE 0 +
CHOMP_ONE 1 -
CHOMP_COLLAPSE 2 =
CHOMP_GREEDY 3 ~
TRIM
The TRIM option can be set to have any leading and trailing whitespace automatically removed from the output of all template files and BLOCKs.
By example, the following BLOCK definition
[% BLOCK foo %]
Line 1 of foo
[% END %]
will be processed is as "nLine 1 of foon". When INCLUDEd, the surrounding newlines will also be introduced.
before
[% INCLUDE foo %]
after
output: before
Line 1 of foo
after
With the TRIM option set to any true value, the leading and trailing newlines (which count as whitespace) will be removed from the output of the BLOCK.
before
Line 1 of foo
after
The TRIM option is disabled (0) by default.
INTERPOLATE
The INTERPOLATE flag, when set to any true value will cause variable references in plain text (i.e. not surrounded by START_TAG and END_TAG) to be recognised and interpolated accordingly.
my $template = Template- >new({
INTERPOLATE = > 1,
});
Variables should be prefixed by a '$' to identify them. Curly braces can be used in the familiar Perl/shell style to explicitly scope the variable name where required.
# INTERPOLATE = > 0
< a href="http://[% server %]/[% help %]" >
< img src="[% images %]/help.gif" >< /a >
[% myorg.name %]
# INTERPOLATE = > 1
< a href="http://$server/$help" >
< img src="$images/help.gif" >< /a >
$myorg.name
# explicit scoping with { }
< img src="$images/${icon.next}.gif" >
Note that a limitation in Perl's regex engine restricts the maximum length of an interpolated template to around 32 kilobytes or possibly less. Files that exceed this limit in size will typically cause Perl to dump core with a segmentation fault. If you routinely process templates of this size then you should disable INTERPOLATE or split the templates in several smaller files or blocks which can then be joined backed together via PROCESS or INCLUDE.
ANYCASE
By default, directive keywords should be expressed in UPPER CASE. The ANYCASE option can be set to allow directive keywords to be specified in any case.
# ANYCASE = > 0 (default)
[% INCLUDE foobar %] # OK
[% include foobar %] # ERROR
[% include = 10 %] # OK, 'include' is a variable
# ANYCASE = > 1
[% INCLUDE foobar %] # OK
[% include foobar %] # OK
[% include = 10 %] # ERROR, 'include' is reserved word
One side-effect of enabling ANYCASE is that you cannot use a variable of the same name as a reserved word, regardless of case. The reserved words are currently:
GET CALL SET DEFAULT INSERT INCLUDE PROCESS WRAPPER
IF UNLESS ELSE ELSIF FOR FOREACH WHILE SWITCH CASE
USE PLUGIN FILTER MACRO PERL RAWPERL BLOCK META
TRY THROW CATCH FINAL NEXT LAST BREAK RETURN STOP
CLEAR TO STEP AND OR NOT MOD DIV END
The only lower case reserved words that cannot be used for variables, regardless of the ANYCASE option, are the operators:
and or not mod div
Requirements:
· Perl
Product's homepage
Requirements:
· Perl
Find us on Google+
