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