1Template(3) User Contributed Perl Documentation Template(3)
2
6 Template - Front-end module to the Template Toolkit
7
9 use Template;
10 # some useful options (see below for full list)
12 my $config = {
13 INCLUDE_PATH => '/search/path', # or list ref
14 INTERPOLATE => 1, # expand "$var" in plain text
15 POST_CHOMP => 1, # cleanup whitespace
16 PRE_PROCESS => 'header', # prefix each template
17 EVAL_PERL => 1, # evaluate Perl code blocks
18 };
19 # create Template object
21 my $template = Template->new($config);
22 # define template variables for replacement
24 my $vars = {
25 var1 => $value,
26 var2 => \%hash,
27 var3 => \@list,
28 var4 => \&code,
29 var5 => $object,
30 };
31 # specify input filename, or file handle, text reference, etc.
33 my $input = 'myfile.html';
34 # process input template, substituting variables
36 $template->process($input, $vars)
37 || die $template->error();
38
40 This documentation describes the Template module which is the direct
41 Perl interface into the Template Toolkit. It covers the use of the
42 module and gives a brief summary of configuration options and template
43 directives. Please see Template::Manual for the complete reference
44 manual which goes into much greater depth about the features and use of
45 the Template Toolkit. The Template::Tutorial is also available as an
46 introductory guide to using the Template Toolkit.
47
49 new(\%config)
50 The "new()" constructor method (implemented by the Template::Base base
51 class) instantiates a new "Template" object. A reference to a hash
52 array of configuration items may be passed as a parameter.
53 my $tt = Template->new({
55 INCLUDE_PATH => '/usr/local/templates',
56 EVAL_PERL => 1,
57 }) || die $Template::ERROR, "\n";
58 A reference to a new "Template" object is returned, or undef on error.
60 In the latter case, the error message can be retrieved by calling
61 error() as a class method or by examining the $Template::ERROR package
62 variable directly.
63 my $tt = Template->new(\%config)
65 || die Template->error(), "\n";
66 my $tt = Template->new(\%config)
68 || die $Template::ERROR, "\n";
69 For convenience, configuration items may also be specified as a list of
71 items instead of a hash array reference. These are automatically
72 folded into a hash array by the constructor.
73 my $tt = Template->new(INCLUDE_PATH => '/tmp', POST_CHOMP => 1)
75 || die $Template::ERROR, "\n";
76 process($template, \%vars, $output, %options)
78 The "process()" method is called to process a template. The first
79 parameter indicates the input template as one of: a filename relative
80 to "INCLUDE_PATH", if defined; a reference to a text string containing
81 the template text; or a file handle reference (e.g. "IO::Handle" or
82 sub-class) or "GLOB" (e.g. "\*STDIN"), from which the template can be
83 read. A reference to a hash array may be passed as the second
84 parameter, containing definitions of template variables.
85 # filename
87 $tt->process('welcome.tt2')
88 || die $tt->error(), "\n";
89 # text reference
91 $text = "[% INCLUDE header %]\nHello world!\n[% INCLUDE footer %]";
92 $tt->process(\$text)
93 || die $tt->error(), "\n";
94 # file handle (GLOB)
96 $tt->process(\*DATA)
97 || die $tt->error(), "\n";
98 __END__
100 [% INCLUDE header %]
101 This is a template defined in the __END__ section which is
102 accessible via the DATA "file handle".
103 [% INCLUDE footer %]
104 By default, the processed template output is printed to "STDOUT". The
106 "process()" method then returns 1 to indicate success. A third
107 parameter may be passed to the "process()" method to specify a
108 different output location. This value may be one of: a plain string
109 indicating a filename which will be opened (relative to "OUTPUT_PATH",
110 if defined) and the output written to; a file GLOB opened ready for
111 output; a reference to a scalar (e.g. a text string) to which
112 output/error is appended; a reference to a subroutine which is called,
113 passing the output as a parameter; or any object reference which
114 implements a "print()" method (e.g. "IO::Handle", "Apache::Request",
115 etc.) which will be called, passing the generated output as a
116 parameter.
117 Examples:
119 # output filename
121 $tt->process('welcome.tt2', $vars, 'welcome.html')
122 || die $tt->error(), "\n";
123 # reference to output subroutine
125 sub myout {
126 my $output = shift;
127 ...
128 }
129 $tt->process('welcome.tt2', $vars, \&myout)
130 || die $tt->error(), "\n";
131 # reference to output text string
133 my $output = '';
134 $tt->process('welcome.tt2', $vars, \$output)
135 || die $tt->error(), "\n";
136 print "output: $output\n";
138 In an Apache/mod_perl handler:
140 sub handler {
142 my $req = shift;
143 # ...your code here...
145 # direct output to Apache::Request via $req->print($output)
147 $tt->process($file, $vars, $req) || do {
148 $req->log_reason($tt->error());
149 return SERVER_ERROR;
150 };
151 return OK;
152 }
153 After the optional third output argument can come an optional reference
155 to a hash or a list of "(name, value)" pairs providing further options
156 for the output. The only option currently supported is "binmode"
157 which, when set to any true value will ensure that files created (but
158 not any existing file handles passed) will be set to binary mode.
159 # either: hash reference of options
161 $tt->process($infile, $vars, $outfile, { binmode => 1 })
162 || die $tt->error(), "\n";
163 # or: list of name, value pairs
165 $tt->process($infile, $vars, $outfile, binmode => 1)
166 || die $tt->error(), "\n";
167 Alternately, the "binmode" argument can specify a particular IO layer
169 such as ":utf8".
170 $tt->process($infile, $vars, $outfile, binmode => ':utf8')
172 || die $tt->error(), "\n";
173 The "OUTPUT" configuration item can be used to specify a default output
175 location other than "\*STDOUT". The "OUTPUT_PATH" specifies a
176 directory which should be prefixed to all output locations specified as
177 filenames.
178 my $tt = Template->new({
180 OUTPUT => sub { ... }, # default
181 OUTPUT_PATH => '/tmp',
182 ...
183 }) || die Template->error(), "\n";
184 # use default OUTPUT (sub is called)
186 $tt->process('welcome.tt2', $vars)
187 || die $tt->error(), "\n";
188 # write file to '/tmp/welcome.html'
190 $tt->process('welcome.tt2', $vars, 'welcome.html')
191 || die $tt->error(), "\n";
192 The "process()" method returns 1 on success or "undef" on error. The
194 error message generated in the latter case can be retrieved by calling
195 the error() method. See also "CONFIGURATION SUMMARY" which describes
196 how error handling may be further customised.
197 error()
199 When called as a class method, it returns the value of the $ERROR
200 package variable. Thus, the following are equivalent.
201 my $tt = Template->new()
203 || die Template->error(), "\n";
204 my $tt = Template->new()
206 || die $Template::ERROR, "\n";
207 When called as an object method, it returns the value of the internal
209 "_ERROR" variable, as set by an error condition in a previous call to
210 process().
211 $tt->process('welcome.tt2')
213 || die $tt->error(), "\n";
214 Errors are represented in the Template Toolkit by objects of the
216 Template::Exception class. If the process() method returns a false
217 value then the "error()" method can be called to return an object of
218 this class. The type() and info() methods can called on the object to
219 retrieve the error type and information string, respectively. The
220 as_string() method can be called to return a string of the form "$type
221 - $info". This method is also overloaded onto the stringification
222 operator allowing the object reference itself to be printed to return
223 the formatted error string.
224 $tt->process('somefile') || do {
226 my $error = $tt->error();
227 print "error type: ", $error->type(), "\n";
228 print "error info: ", $error->info(), "\n";
229 print $error, "\n";
230 };
231 service()
233 The "Template" module delegates most of the effort of processing
234 templates to an underlying Template::Service object. This method
235 returns a reference to that object.
236 context()
238 The Template::Service module uses a core Template::Context object for
239 runtime processing of templates. This method returns a reference to
240 that object and is equivalent to "$template->service->context()".
241 template($name)
243 This method is a simple wrapper around the Template::Context method of
244 the same name. It returns a compiled template for the source provided
245 as an argument.
246
248 The following list gives a short summary of each Template Toolkit
249 configuration option. See Template::Manual::Config for full details.
250 Template Style and Parsing Options
252 ENCODING
253 Specifies the character encoding.
255 START_TAG, END_TAG
257 Define tokens that indicate start and end of directives (default:
259 '"[%"' and '"%]"').
260 TAG_STYLE
262 Set "START_TAG" and "END_TAG" according to a pre-defined style
264 (default: '"template"', as above).
265 PRE_CHOMP, POST_CHOMP
267 Removes whitespace before/after directives (default: 0/0).
269 TRIM
271 Remove leading and trailing whitespace from template output (default:
273 0).
274 INTERPOLATE
276 Interpolate variables embedded like $this or "${this}" (default: 0).
278 ANYCASE
280 Allow directive keywords in lower case (default: 0 - UPPER only).
282 Template Files and Blocks
284 INCLUDE_PATH
285 One or more directories to search for templates.
287 DELIMITER
289 Delimiter for separating paths in "INCLUDE_PATH" (default: '":"').
291 ABSOLUTE
293 Allow absolute file names, e.g. "/foo/bar.html" (default: 0).
295 RELATIVE
297 Allow relative filenames, e.g. "../foo/bar.html" (default: 0).
299 DEFAULT
301 Default template to use when another not found.
303 BLOCKS
305 Hash array pre-defining template blocks.
307 AUTO_RESET
309 Enabled by default causing "BLOCK" definitions to be reset each time a
311 template is processed. Disable to allow "BLOCK" definitions to
312 persist.
313 RECURSION
315 Flag to permit recursion into templates (default: 0).
317 Template Variables
319 VARIABLES
320 Hash array of variables and values to pre-define in the stash.
322 Runtime Processing Options
324 EVAL_PERL
325 Flag to indicate if "PERL"/"RAWPERL" blocks should be processed
327 (default: 0).
328 PRE_PROCESS, POST_PROCESS
330 Name of template(s) to process before/after main template.
332 PROCESS
334 Name of template(s) to process instead of main template.
336 ERROR
338 Name of error template or reference to hash array mapping error types
340 to templates.
341 OUTPUT
343 Default output location or handler.
345 OUTPUT_PATH
347 Directory into which output files can be written.
349 DEBUG
351 Enable debugging messages.
353 Caching and Compiling Options
355 CACHE_SIZE
356 Maximum number of compiled templates to cache in memory (default: undef
358 - cache all)
359 COMPILE_EXT
361 Filename extension for compiled template files (default: undef - don't
363 compile).
364 COMPILE_DIR
366 Root of directory in which compiled template files should be written
368 (default: undef - don't compile).
369 Plugins and Filters
371 PLUGINS
372 Reference to a hash array mapping plugin names to Perl packages.
374 PLUGIN_BASE
376 One or more base classes under which plugins may be found.
378 LOAD_PERL
380 Flag to indicate regular Perl modules should be loaded if a named
382 plugin can't be found (default: 0).
383 FILTERS
385 Hash array mapping filter names to filter subroutines or factories.
387 Customisation and Extension
389 LOAD_TEMPLATES
390 List of template providers.
392 LOAD_PLUGINS
394 List of plugin providers.
396 LOAD_FILTERS
398 List of filter providers.
400 TOLERANT
402 Set providers to tolerate errors as declinations (default: 0).
404 SERVICE
406 Reference to a custom service object (default: Template::Service).
408 CONTEXT
410 Reference to a custom context object (default: Template::Context).
412 STASH
414 Reference to a custom stash object (default: Template::Stash).
416 PARSER
418 Reference to a custom parser object (default: Template::Parser).
420 GRAMMAR
422 Reference to a custom grammar object (default: Template::Grammar).
424
426 The following list gives a short summary of each Template Toolkit
427 directive. See Template::Manual::Directives for full details.
428 GET
430 Evaluate and print a variable or value.
431 [% GET variable %] # 'GET' keyword is optional
433 [% variable %]
434 [% hash.key %]
435 [% list.n %]
436 [% code(args) %]
437 [% obj.meth(args) %]
438 [% "value: $var" %]
439 CALL
441 As per GET but without printing result (e.g. call code)
442 [% CALL variable %]
444 SET
446 Assign a values to variables.
447 [% SET variable = value %] # 'SET' also optional
449 [% variable = other_variable
450 variable = 'literal text @ $100'
451 variable = "interpolated text: $var"
452 list = [ val, val, val, val, ... ]
453 list = [ val..val ]
454 hash = { var => val, var => val, ... }
455 %]
456 DEFAULT
458 Like SET, but variables are only set if currently unset (i.e. have no
459 true value).
460 [% DEFAULT variable = value %]
462 INSERT
464 Insert a file without any processing performed on the contents.
465 [% INSERT legalese.txt %]
467 PROCESS
469 Process another template file or block and insert the generated output.
470 Any template BLOCKs or variables defined or updated in the "PROCESS"ed
471 template will thereafter be defined in the calling template.
472 [% PROCESS template %]
474 [% PROCESS template var = val, ... %]
475 INCLUDE
477 Similar to "PROCESS", but using a local copy of the current variables.
478 Any template "BLOCK"s or variables defined in the "INCLUDE"d template
479 remain local to it.
480 [% INCLUDE template %]
482 [% INCLUDE template var = val, ... %]
483 WRAPPER
485 The content between the "WRAPPER" and corresponding "END" directives is
486 first evaluated, with the output generated being stored in the
487 "content" variable. The named template is then process as per
488 "INCLUDE".
489 [% WRAPPER layout %]
491 Some template markup [% blah %]...
492 [% END %]
493 A simple layout template might look something like this:
495 Your header here...
497 [% content %]
498 Your footer here...
499 BLOCK
501 Define a named template block for INCLUDE, PROCESS and WRAPPER to use.
502 [% BLOCK hello %]
504 Hello World
505 [% END %]
506 [% INCLUDE hello %]
508 FOREACH
510 Repeat the enclosed "FOREACH" ... "END" block for each value in the
511 list.
512 [% FOREACH variable IN [ val, val, val ] %] # either
514 [% FOREACH variable IN list %] # or
515 The variable is set to [% variable %]
516 [% END %]
517 WHILE
519 The block enclosed between "WHILE" and "END" block is processed while
520 the specified condition is true.
521 [% WHILE condition %]
523 content
524 [% END %]
525 IF / UNLESS / ELSIF / ELSE
527 The enclosed block is processed if the condition is true / false.
528 [% IF condition %]
530 content
531 [% ELSIF condition %]
532 content
533 [% ELSE %]
534 content
535 [% END %]
536 [% UNLESS condition %]
538 content
539 [% # ELSIF/ELSE as per IF, above %]
540 content
541 [% END %]
542 SWITCH / CASE
544 Multi-way switch/case statement.
545 [% SWITCH variable %]
547 [% CASE val1 %]
548 content
549 [% CASE [ val2, val3 ] %]
550 content
551 [% CASE %] # or [% CASE DEFAULT %]
552 content
553 [% END %]
554 MACRO
556 Define a named macro.
557 [% MACRO name <directive> %]
559 [% MACRO name(arg1, arg2) <directive> %]
560 ...
561 [% name %]
562 [% name(val1, val2) %]
563 FILTER
565 Process enclosed "FILTER" ... "END" block then pipe through a filter.
566 [% FILTER name %] # either
568 [% FILTER name( params ) %] # or
569 [% FILTER alias = name( params ) %] # or
570 content
571 [% END %]
572 USE
574 Load a plugin module (see "Template::<Manual::Plugins"), or any regular
575 Perl module when the "LOAD_PERL" option is set.
576 [% USE name %] # either
578 [% USE name( params ) %] # or
579 [% USE var = name( params ) %] # or
580 ...
581 [% name.method %]
582 [% var.method %]
583 PERL / RAWPERL
585 Evaluate enclosed blocks as Perl code (requires the "EVAL_PERL" option
586 to be set).
587 [% PERL %]
589 # perl code goes here
590 $stash->set('foo', 10);
591 print "set 'foo' to ", $stash->get('foo'), "\n";
592 print $context->include('footer', { var => $val });
593 [% END %]
594 [% RAWPERL %]
596 # raw perl code goes here, no magic but fast.
597 $output .= 'some output';
598 [% END %]
599 TRY / THROW / CATCH / FINAL
601 Exception handling.
602 [% TRY %]
604 content
605 [% THROW type info %]
606 [% CATCH type %]
607 catch content
608 [% error.type %] [% error.info %]
609 [% CATCH %] # or [% CATCH DEFAULT %]
610 content
611 [% FINAL %]
612 this block is always processed
613 [% END %]
614 NEXT
616 Jump straight to the next item in a "FOREACH" or "WHILE" loop.
617 [% NEXT %]
619 LAST
621 Break out of "FOREACH" or "WHILE" loop.
622 [% LAST %]
624 RETURN
626 Stop processing current template and return to including templates.
627 [% RETURN %]
629 STOP
631 Stop processing all templates and return to caller.
632 [% STOP %]
634 TAGS
636 Define new tag style or characters (default: "[%" "%]").
637 [% TAGS html %]
639 [% TAGS <!-- --> %]
640 COMMENTS
642 Ignored and deleted.
643 [% # this is a comment to the end of line
645 foo = 'bar'
646 %]
647 [%# placing the '#' immediately inside the directive
649 tag comments out the entire directive
650 %]
651
653 The source code for the Template Toolkit is held in a public git
654 repository on Github: <https://github.com/abw/Template2>
655
657 Andy Wardley <abw@wardley.org> <http://wardley.org/>
658
660 Template Toolkit version 3.009, released on July 13 2020.
661
663 Copyright (C) 1996-2020 Andy Wardley. All Rights Reserved.
664 This module is free software; you can redistribute it and/or modify it
666 under the same terms as Perl itself.
667perl v5.32.0 2020-07-28 Template(3)