1Text::Template::Simple(U3s)er Contributed Perl DocumentatTieoxnt::Template::Simple(3)
2
6 Text::Template::Simple
7
9 version 0.91
10
12 use Text::Template::Simple;
13 my $tts = Text::Template::Simple->new();
14 print $tts->compile( $FILEHANDLE );
15 print $tts->compile('Hello, your perl is at <%= $^X %>');
16 print $tts->compile(
17 'hello.tts', # the template file
18 [ name => 'Burak', location => 'Istanbul' ]
19 );
20 Where "hello.tts" has this content:
22 <% my %p = @_; %>
24 Hello <%= $p{name} %>,
25 I hope it's sunny in <%= $p{location} %>.
26 Local time is <%= scalar localtime time %>
27
29 This is a simple template module. There is no extra template/mini
30 language. Instead, it uses Perl as the template language. Templates can
31 be cached on disk or inside the memory via the internal cache manager.
32 It is also possible to use static/dynamic includes, pass parameters to
33 includes and apply filters on them. Also see
34 Text::Template::Simple::API for the full "API" reference.
35
37 Text::Template::Simple - Simple text template engine
38
40 Template syntax is very simple. There are few kinds of delimiters:
41 • "<% %>" Code Blocks
43 • "<%= %>" Self-printing Blocks
45 • "<%! %>" Escaped Delimiters
47 • "<%+ %>" Static Include Directives
49 • "<%* %>" Dynamic include directives
51 • "<%# %>" Comment Directives
53 • "<%| %>" Blocks with commands
55 A simple example:
57 <% foreach my $x (@foo) { %>
59 Element is <%= $x %>
60 <% } %>
61 Do not directly use print() statements, since they'll break the
63 template compilation. Use the self printing "<%= %>" blocks.
64 It is also possible to alter the delimiters:
66 $tts = Text::Template::Simple->new(
68 delimiters => [qw/<?perl ?>/],
69 );
70 then you can use them inside templates:
72 <?perl
74 my @foo = qw(bar baz);
75 foreach my $x (@foo) {
76 ?>
77 Element is <?perl= $x ?>
78 <?perl } ?>
79 If you need to remove a code temporarily without deleting, or need to
81 add comments:
82 <%#
84 This
85 whole
86 block
87 will
88 be
89 ignored
90 %>
91 If you put a space before the pound sign, the block will be a code
93 block:
94 <%
96 # this is normal code not a comment directive
97 my $foo = 42;
98 %>
99 If you want to include a text or HTML file, you can use the static
101 include directive:
102 <%+ my_other.html %>
104 <%+ my_other.txt %>
105 Included files won't be parsed and included statically. To enable
107 parsing for the included files, use the dynamic includes:
108 <%* my_other.html %>
110 <%* my_other.txt %>
111 Interpolation is also supported with both kinds of includes, so the
113 following is valid code:
114 <%+ "/path/to/" . $txt %>
116 <%* "/path/to/" . $myfile %>
117 Chomping
119 Chomping is the removal of white space before and after your
120 directives. This can be useful if you're generating plain text (instead
121 of HTML which will ignore spaces most of the time). You can either
122 remove all space or replace multiple white space with a single space
123 (collapse). Chomping can be enabled per directive or globally via
124 options to the constructor. See "pre_chomp" in
125 Text::Template::Simple::API and "post_chomp" in
126 Text::Template::Simple::API options to "new" in
127 Text::Template::Simple::API to globally enable chomping.
128 Chomping is enabled with second level commands for all directives. Here
130 is a list of commands:
131 - Chomp
133 ~ Collapse
134 ^ No chomp (override global)
135 All directives can be chomped. Here are some examples:
137 Chomp:
139 raw content
141 <%- my $foo = 42; -%>
142 raw content
143 <%=- $foo -%>
144 raw content
145 <%*- /mt/dynamic.tts -%>
146 raw content
147 Collapse:
149 raw content
151 <%~ my $foo = 42; ~%>
152 raw content
153 <%=~ $foo ~%>
154 raw content
155 <%*~ /mt/dynamic.tts ~%>
156 raw content
157 No chomp:
159 raw content
161 <%^ my $foo = 42; ^%>
162 raw content
163 <%=^ $foo ^%>
164 raw content
165 <%*^ /mt/dynamic.tts ^%>
166 raw content
167 It is also possible to mix the chomping types:
169 raw content
171 <%- my $foo = 42; ^%>
172 raw content
173 <%=^ $foo ~%>
174 raw content
175 <%*^ /mt/dynamic.tts -%>
176 raw content
177 For example this template:
179 Foo
181 <%- $prehistoric = $] < 5.008 -%>
182 Bar
183 Will become:
185 FooBar
187 And this one:
189 Foo
191 <%~ $prehistoric = $] < 5.008 -%>
192 Bar
193 Will become:
195 Foo Bar
197 Chomping is inspired by Template Toolkit (mostly the same
199 functionality, although "TT" seems to miss collapse/no-chomp per
200 directive option).
201 Accessing Template Names
203 You can use $0 to get the template path/name inside the template:
204 I am <%= $0 %>
206 Escaping Delimiters
208 If you have to build templates like this:
209 Test: <%abc>
211 or this:
213 Test: <%abc%>
215 This will result with a template compilation error. You have to use the
217 delimiter escape command "!":
218 Test: <%!abc>
220 Test: <%!abc%>
221 Those will be compiled as:
223 Test: <%abc>
225 Test: <%abc%>
226 Alternatively, you can change the default delimiters to solve this
228 issue. See the "delimiters" in Text::Template::Simple::API option for
229 "new" in Text::Template::Simple::API for more information on how to do
230 this.
231 Template Parameters
233 You can fetch parameters (passed to compile) in the usual "perl" way:
234 <%
236 my $foo = shift;
237 my %bar = @_;
238 %>
239 Baz is <%= $bar{baz} %>
240 INCLUDE COMMANDS
242 Include commands are separated by pipes in an include directive.
243 Currently supported parameters are:
244 "PARAM"
246 FILTER
247 SHARE
248 <%+ /path/to/static.tts | FILTER: MyFilter %>
250 <%* /path/to/dynamic.tts | FILTER: MyFilter | PARAM: test => 123 %>
251 "PARAM" defines the parameter list to pass to the included file.
253 "FILTER" defines the list of filters to apply to the output of the
254 include. "SHARE" used to list the variables to share with the included
255 template when the monolith option is disabled.
256 INCLUDE FILTERS
258 Use the include command "FILTER:" (notice the colon in the command):
260 <%+ /path/to/static.tts | FILTER: First, Second %>
262 <%* /path/to/dynamic.tts | FILTER: Third, Fourth, Fifth %>
263 IMPLEMENTING INCLUDE FILTERS
265 Define the filter inside "Text::Template::Simple::Dummy" with a
267 "filter_" prefix:
268 package Text::Template::Simple::Dummy;
270 sub filter_MyFilter {
271 # $tts is the current Text::Template::Simple object
272 # $output_ref is the scalar reference to the output of
273 # the template.
274 my($tts, $output_ref) = @_;
275 $$output_ref .= "FILTER APPLIED"; # add to output
276 return;
277 }
278 INCLUDE PARAMETERS
280 Just pass the parameters as described above and fetch them via @_
282 inside the included file.
283 SHARED VARIABLES
285 "Text::Template::Simple" compiles every template individually with
287 separate scopes. A variable defined in the master template is not
288 accessible from a dynamic include. The exception to this rule is the
289 "monolith" option to "new". If it is enabled; the master template and
290 any includes it has will be compiled into a single document, thus
291 making every variable defined at the top available to the includes
292 below. But this method has several drawbacks, it disables cache check
293 for the sub files (includes) --you'll need to edit the master template
294 to force a cache reload-- and it can not be used with interpolated
295 includes. If you use an interpolated include with monolith enabled,
296 you'll get an error.
297 If you don't use "monolith" (disabled by default), then you'll need to
299 share the variables somehow to don't repeat yourself. Variable sharing
300 is demonstrated in the below template:
301 <%
303 my $foo = 42;
304 my $bar = 23;
305 %>
306 <%* dyna.inc | SHARE: $foo, $bar %>
307 And then you can access $foo and $bar inside "dyna.inc". There is one
309 drawback by shared variables: only "SCALARs" can be shared. You can not
310 share anything else. If you want to share an array, use an array
311 reference instead:
312 <%
314 my @foo = (1..10);
315 my $fooref = \@foo;
316 %>
317 <%* dyna.inc | SHARE: $fooref %>
318 BLOCKS
320 A block consists of a header part and the content.
321 <%| HEADER;
323 BODY
324 %>
325 "HEADER" includes the commands and terminated with a semicolon. "BODY"
327 is the actual block content.
328 BLOCK FILTERS
330 WARNING Block filters are considered to be experimental. They may be
332 changed or completely removed in the future.
333 Identical to include filters, but works on blocks of text:
335 <%| FILTER: HTML, OtherFilter;
337 <p>&FooBar=42</p>
338 %>
339 Note that you can not use any variables in these blocks. They are
341 static.
342
344 new
345 cache
346 class_id
347 compile
348 connector
349 "io"
350 "tts"
351 See Text::Template::Simple::API for the technical/gory details.
352
354 TODO
355
357 You may need to "eval" your code blocks to trap exceptions. Some
358 recoverable failures are silently ignored, but you can display them as
359 warnings if you enable debugging.
360
362 Contact the author if you find any bugs.
363
365 No mini language
366 There is no mini-language. Only "perl" is used as the template
367 language. So, this may or may not be safe from your point of view. If
368 this is a problem for you, just don't use this module. There are plenty
369 of template modules with mini-languages inside "CPAN".
370 Speed
372 There is an initialization cost and this will show itself after the
373 first compilation process. The second and any following compilations
374 will be much faster. Using cache can also improve speed, since this
375 will eliminate the parsing phase. Also, using memory cache will make
376 the program run more faster under persistent environments. But the
377 overall speed really depends on your environment.
378 Internal cache manager generates ids for all templates. If you supply
380 your own id parameter, this will improve performance.
381 Optional Dependencies
383 Some methods/functionality of the module needs these optional modules:
384 Devel::Size
386 Text::Table
387 Perl::Tidy
388
390 Text::Template::Simple::API, Apache::SimpleTemplate, Text::Template,
391 Text::ScriptTemplate, Safe, Opcode.
392 MONOLITHIC VERSION
394 "Text::Template::Simple" consists of "15+" separate modules. If you are
395 after a single ".pm" file to ease deployment, download the distribution
396 from a "CPAN" mirror near you to get a monolithic
397 "Text::Template::Simple". It is automatically generated from the
398 separate modules and distributed in the "monolithic_version" directory.
399 However, be aware that the monolithic version is not supported.
401
403 Burak Gursoy <burak@cpan.org>
404
406 This software is copyright (c) 2004 by Burak Gursoy.
407 This is free software; you can redistribute it and/or modify it under
409 the same terms as the Perl 5 programming language system itself.
410perl v5.36.0 2022-07-22 Text::Template::Simple(3)