Mojo::Template(3pm)

1Mojo::Template(3)     User Contributed Perl Documentation    Mojo::Template(3)
2
3
4

NAME

6       Mojo::Template - Perl-ish templates
7

SYNOPSIS

9         use Mojo::Template;
10
11         # Use Perl modules
12         my $mt = Mojo::Template->new;
13         say $mt->render(<<'EOF');
14         % use Time::Piece;
15         <div>
16           % my $now = localtime;
17           Time: <%= $now->hms %>
18         </div>
19         EOF
20
21         # Render with arguments
22         say $mt->render(<<'EOF', [1 .. 13], 'Hello World!');
23         % my ($numbers, $title) = @_;
24         <div>
25           <h1><%= $title %></h1>
26           % for my $i (@$numbers) {
27             Test <%= $i %>
28           % }
29         </div>
30         EOF
31
32         # Render with named variables
33         say $mt->vars(1)->render(<<'EOF', {title => 'Hello World!'});
34         <div>
35           <h1><%= $title %></h1>
36           %= 5 + 5
37         </div>
38         EOF
39

DESCRIPTION

41       Mojo::Template is a minimalistic, fast, and very Perl-ish template
42       engine, designed specifically for all those small tasks that come up
43       during big projects. Like preprocessing a configuration file,
44       generating text from heredocs and stuff like that.
45
46       See Mojolicious::Guides::Rendering for information on how to generate
47       content with the Mojolicious renderer.
48

SYNTAX

50       For all templates strict, warnings, utf8 and Perl 5.10 features are
51       automatically enabled.
52
53         <% Perl code %>
54         <%= Perl expression, replaced with result %>
55         <%== Perl expression, replaced with XML escaped result %>
56         <%# Comment, useful for debugging %>
57         <%% Replaced with "<%", useful for generating templates %>
58         % Perl code line, treated as "<% line =%>" (explained later)
59         %= Perl expression line, treated as "<%= line %>"
60         %== Perl expression line, treated as "<%== line %>"
61         %# Comment line, useful for debugging
62         %% Replaced with "%", useful for generating templates
63
64       Escaping behavior can be reversed with the "auto_escape" attribute,
65       this is the default in Mojolicious ".ep" templates, for example.
66
67         <%= Perl expression, replaced with XML escaped result %>
68         <%== Perl expression, replaced with result %>
69
70       Mojo::ByteStream objects are always excluded from automatic escaping.
71
72         % use Mojo::ByteStream 'b';
73         <%= b('<div>excluded!</div>') %>
74
75       Whitespace characters around tags can be trimmed by adding an
76       additional equal sign to the end of a tag.
77
78         <% for (1 .. 3) { %>
79           <%= 'Trim all whitespace characters around this expression' =%>
80         <% } %>
81
82       Newline characters can be escaped with a backslash.
83
84         This is <%= 1 + 1 %> a\
85         single line
86
87       And a backslash in front of a newline character can be escaped with
88       another backslash.
89
90         This will <%= 1 + 1 %> result\\
91         in multiple\\
92         lines
93
94       A newline character gets appended automatically to every template,
95       unless the last character is a backslash. And empty lines at the end of
96       a template are ignored.
97
98         There is <%= 1 + 1 %> no newline at the end here\
99
100       You can capture whole template blocks for reuse later with the "begin"
101       and "end" keywords. Just be aware that both keywords are part of the
102       surrounding tag and not actual Perl code, so there can only be
103       whitespace after "begin" and before "end".
104
105         <% my $block = begin %>
106           <% my $name = shift; =%>
107           Hello <%= $name %>.
108         <% end %>
109         <%= $block->('Baerbel') %>
110         <%= $block->('Wolfgang') %>
111
112       Perl lines can also be indented freely.
113
114         % my $block = begin
115           % my $name = shift;
116           Hello <%= $name %>.
117         % end
118         %= $block->('Baerbel')
119         %= $block->('Wolfgang')
120
121       Mojo::Template templates get compiled to a Perl subroutine, that means
122       you can access arguments simply via @_.
123
124         % my ($foo, $bar) = @_;
125         % my $x = shift;
126         test 123 <%= $foo %>
127
128       The compilation of templates to Perl code can make debugging a bit
129       tricky, but Mojo::Template will return Mojo::Exception objects that
130       stringify to error messages with context.
131
132         Bareword "xx" not allowed while "strict subs" in use at template line 4.
133         2: </head>
134         3: <body>
135         4: % my $i = 2; xx
136         5: %= $i * 2
137         6: </body>
138         template:4 (Mojo::Template::Sandbox)
139         path/to/Mojo/Template.pm:123 (Mojo::Template)
140         path/to/myapp.pl:123 (main)
141

ATTRIBUTES

143       Mojo::Template implements the following attributes.
144
145   auto_escape
146         my $bool = $mt->auto_escape;
147         $mt      = $mt->auto_escape($bool);
148
149       Activate automatic escaping.
150
151         # "&lt;html&gt;"
152         Mojo::Template->new(auto_escape => 1)->render("<%= '<html>' %>");
153
154   append
155         my $code = $mt->append;
156         $mt      = $mt->append('warn "Processed template"');
157
158       Append Perl code to compiled template. Note that this code should not
159       contain newline characters, or line numbers in error messages might end
160       up being wrong.
161
162   capture_end
163         my $end = $mt->capture_end;
164         $mt     = $mt->capture_end('end');
165
166       Keyword indicating the end of a capture block, defaults to "end".
167
168         <% my $block = begin %>
169           Some data!
170         <% end %>
171
172   capture_start
173         my $start = $mt->capture_start;
174         $mt       = $mt->capture_start('begin');
175
176       Keyword indicating the start of a capture block, defaults to "begin".
177
178         <% my $block = begin %>
179           Some data!
180         <% end %>
181
182   code
183         my $code = $mt->code;
184         $mt      = $mt->code($code);
185
186       Perl code for template if available.
187
188   comment_mark
189         my $mark = $mt->comment_mark;
190         $mt      = $mt->comment_mark('#');
191
192       Character indicating the start of a comment, defaults to "#".
193
194         <%# This is a comment %>
195
196   compiled
197         my $compiled = $mt->compiled;
198         $mt          = $mt->compiled($compiled);
199
200       Compiled template code if available.
201
202   encoding
203         my $encoding = $mt->encoding;
204         $mt          = $mt->encoding('UTF-8');
205
206       Encoding used for template files, defaults to "UTF-8".
207
208   escape
209         my $cb = $mt->escape;
210         $mt    = $mt->escape(sub {...});
211
212       A callback used to escape the results of escaped expressions, defaults
213       to "xml_escape" in Mojo::Util.
214
215         $mt->escape(sub {
216           my $str = shift;
217           return reverse $str;
218         });
219
220   escape_mark
221         my $mark = $mt->escape_mark;
222         $mt      = $mt->escape_mark('=');
223
224       Character indicating the start of an escaped expression, defaults to
225       "=".
226
227         <%== $foo %>
228
229   expression_mark
230         my $mark = $mt->expression_mark;
231         $mt      = $mt->expression_mark('=');
232
233       Character indicating the start of an expression, defaults to "=".
234
235         <%= $foo %>
236
237   line_start
238         my $start = $mt->line_start;
239         $mt       = $mt->line_start('%');
240
241       Character indicating the start of a code line, defaults to "%".
242
243         % $foo = 23;
244
245   name
246         my $name = $mt->name;
247         $mt      = $mt->name('foo.mt');
248
249       Name of template currently being processed, defaults to "template".
250       Note that this value should not contain quotes or newline characters,
251       or error messages might end up being wrong.
252
253   namespace
254         my $namespace = $mt->namespace;
255         $mt           = $mt->namespace('main');
256
257       Namespace used to compile templates, defaults to
258       "Mojo::Template::SandBox".  Note that namespaces should only be shared
259       very carefully between templates, since functions and global variables
260       will not be cleared automatically.
261
262   prepend
263         my $code = $mt->prepend;
264         $mt      = $mt->prepend('my $self = shift;');
265
266       Prepend Perl code to compiled template. Note that this code should not
267       contain newline characters, or line numbers in error messages might end
268       up being wrong.
269
270   replace_mark
271         my $mark = $mt->replace_mark;
272         $mt      = $mt->replace_mark('%');
273
274       Character used for escaping the start of a tag or line, defaults to
275       "%".
276
277         <%% my $foo = 23; %>
278
279   tag_start
280         my $start = $mt->tag_start;
281         $mt       = $mt->tag_start('<%');
282
283       Characters indicating the start of a tag, defaults to "<%".
284
285         <% $foo = 23; %>
286
287   tag_end
288         my $end = $mt->tag_end;
289         $mt     = $mt->tag_end('%>');
290
291       Characters indicating the end of a tag, defaults to "%>".
292
293         <%= $foo %>
294
295   tree
296         my $tree = $mt->tree;
297         $mt      = $mt->tree([['text', 'foo'], ['line']]);
298
299       Template in parsed form if available. Note that this structure should
300       only be used very carefully since it is very dynamic.
301
302   trim_mark
303         my $mark = $mt->trim_mark;
304         $mt      = $mt->trim_mark('-');
305
306       Character activating automatic whitespace trimming, defaults to "=".
307
308         <%= $foo =%>
309
310   unparsed
311         my $unparsed = $mt->unparsed;
312         $mt          = $mt->unparsed('<%= 1 + 1 %>');
313
314       Raw unparsed template if available.
315
316   vars
317         my $bool = $mt->vars;
318         $mt      = $mt->vars($bool);
319
320       Instead of a list of values, use a hash reference with named variables
321       to pass data to templates.
322
323         # "works!"
324         Mojo::Template->new(vars => 1)->render('<%= $test %>!', {test => 'works'});
325

METHODS

327       Mojo::Template inherits all methods from Mojo::Base and implements the
328       following new ones.
329
330   parse
331         $mt = $mt->parse('<%= 1 + 1 %>');
332
333       Parse template into "tree".
334
335   process
336         my $output = $mt->process;
337         my $output = $mt->process(@args);
338         my $output = $mt->process({foo => 'bar'});
339
340       Process previously parsed template and return the result, or a
341       Mojo::Exception object if rendering failed.
342
343         # Parse and process
344         say Mojo::Template->new->parse('Hello <%= $_[0] %>')->process('Bender');
345
346         # Reuse template (for much better performance)
347         my $mt = Mojo::Template->new;
348         say $mt->render('Hello <%= $_[0] %>!', 'Bender');
349         say $mt->process('Fry');
350         say $mt->process('Leela');
351
352   render
353         my $output = $mt->render('<%= 1 + 1 %>');
354         my $output = $mt->render('<%= shift() + shift() %>', @args);
355         my $output = $mt->render('<%= $foo %>', {foo => 'bar'});
356
357       Render template and return the result, or a Mojo::Exception object if
358       rendering failed.
359
360         # Longer version
361         my $output = $mt->parse('<%= 1 + 1 %>')->process;
362
363         # Render with arguments
364         say Mojo::Template->new->render('<%= $_[0] %>', 'bar');
365
366         # Render with named variables
367         say Mojo::Template->new(vars => 1)->render('<%= $foo %>', {foo => 'bar'});
368
369   render_file
370         my $output = $mt->render_file('/tmp/foo.mt');
371         my $output = $mt->render_file('/tmp/foo.mt', @args);
372         my $output = $mt->render_file('/tmp/bar.mt', {foo => 'bar'});
373
374       Same as "render", but renders a template file.
375

DEBUGGING

377       You can set the "MOJO_TEMPLATE_DEBUG" environment variable to get some
378       advanced diagnostics information printed to "STDERR".
379
380         MOJO_TEMPLATE_DEBUG=1
381