NAME
Mojo::Template - Perl-ish templates!
SYNOPSIS
my $mt = Mojo::Template->new;
my $output = $mt->render(<<'EOF');
% use Time::Piece;
<!DOCTYPE html>
<html>
<head><title>Simple</title></head>
% my $now = localtime;
<body>Time: <%= $now->hms %></body>
</html>
EOF
say $output;
my $output = $mt->render(<<'EOF', 23, 'More advanced');
% my ($num, $title) = @_;
%= 5 * 5
<!DOCTYPE html>
<html>
<head><title><%= $title %></title></head>
<body>
test 123
foo <% my $i = $num + 2; %>
% for (1 .. 23) {
* some text <%= $i++ %>
% }
</body>
</html>
EOF
say $output;
|
DESCRIPTION
Mojo::Template is a minimalistic and very Perl-ish template engine, designed specifically for all those small tasks that come up during big projects. Like preprocessing a configuration file, generating text from heredocs and stuff like that.
See Mojolicious::Guides::Rendering for information on how to generate content with the Mojolicious renderer.
SYNTAX
For all templates strict, warnings, utf8 and Perl 5.10 features are automatically enabled.
<% Perl code %>
<%= Perl expression, replaced with result %>
<%== Perl expression, replaced with XML escaped result %>
<%
<%% Replaced with "<%", useful for generating templates %>% Perl code line, treated as "<% line =%>"
%= Perl expression line, treated as "<%= line %>"
%== Perl expression line, treated as "<%== line %>"
%
%% Replaced with "%", useful for generating templates |
Escaping behavior can be reversed with the "auto_escape" attribute, this is the default in Mojolicious .ep templates for example.
<%= Perl expression, replaced with XML escaped result %>
<%== Perl expression, replaced with result %>
|
Mojo::ByteStream objects are always excluded from automatic escaping.
<%= b('<div>excluded!</div>') %>
|
Whitespace characters around tags can be trimmed by adding an additional equal sign to the end of a tag.
<%= All whitespace characters around this expression will be trimmed =%>
|
Newline characters can be escaped with a backslash.
This is <%= 1 + 1 %> a\
single line
|
And a backslash in front of a newline character can be escaped with another backslash.
This will <%= 1 + 1 %> result\\
in multiple\\
lines
|
You can capture whole template blocks for reuse later with the begin and end keywords.
<% my $block = begin %>
<% my $name = shift; =%>
Hello <%= $name %>.
<% end %>
<%= $block->('Baerbel') %>
<%= $block->('Wolfgang') %>
|
Perl lines can also be indented freely.
% my $block = begin
% my $name = shift;
Hello <%= $name %>.
% end
%= $block->('Baerbel')
%= $block->('Wolfgang')
|
Mojo::Template templates get compiled to a Perl subroutine, that means you can access arguments simply via @_.
% my ($foo, $bar) = @_;
% my $x = shift;
test 123 <%= $foo %>
|
The compilation of templates to Perl code can make debugging a bit tricky, but Mojo::Template will return Mojo::Exception objects that stringify to error messages with context.
Bareword "xx" not allowed while "strict subs" in use at template line 4.2: </head>
3: <body>
4: % my $i = 2; xx
5: %= $i * 2
6: </body>
|
ATTRIBUTES
Mojo::Template implements the following attributes.
auto_escape
my $bool = $mt->auto_escape;
$mt = $mt->auto_escape($bool);
|
Activate automatic escaping.
append
my $code = $mt->append;
$mt = $mt->append('warn "Processed template"');
|
Append Perl code to compiled template. Note that this code should not contain newline characters, or line numbers in error messages might end up being wrong.
capture_end
my $end = $mt->capture_end;
$mt = $mt->capture_end('end');
|
Keyword indicating the end of a capture block, defaults to end.
<% my $block = begin %>
Some data!
<% end %>
|
capture_start
my $start = $mt->capture_start;
$mt = $mt->capture_start('begin');
|
Keyword indicating the start of a capture block, defaults to begin.
<% my $block = begin %>
Some data!
<% end %>
|
code
my $code = $mt->code;
$mt = $mt->code($code);
|
Perl code for template.
my $mark = $mt->comment_mark;
$mt = $mt->comment_mark('#');
|
Character indicating the start of a comment, defaults to #.
compiled
my $compiled = $mt->compiled;
$mt = $mt->compiled($compiled);
|
Compiled template code.
encoding
my $encoding = $mt->encoding;
$mt = $mt->encoding('UTF-8');
|
Encoding used for template files.
escape
my $cb = $mt->escape;
$mt = $mt->escape(sub {...});
|
A callback used to escape the results of escaped expressions, defaults to "xss_escape" in Mojo::Util.
$mt->escape(sub {
my $str = shift;
return reverse $str;
});
|
escape_mark
my $mark = $mt->escape_mark;
$mt = $mt->escape_mark('=');
|
Character indicating the start of an escaped expression, defaults to =.
expression_mark
my $mark = $mt->expression_mark;
$mt = $mt->expression_mark('=');
|
Character indicating the start of an expression, defaults to =.
line_start
my $start = $mt->line_start;
$mt = $mt->line_start('%');
|
Character indicating the start of a code line, defaults to %.
name
my $name = $mt->name;
$mt = $mt->name('foo.mt');
|
Name of template currently being processed, defaults to template. Note that this value should not contain quotes or newline characters, or error messages might end up being wrong.
namespace
my $namespace = $mt->namespace;
$mt = $mt->namespace('main');
|
Namespace used to compile templates, defaults to Mojo::Template::SandBox. Note that namespaces should only be shared very carefully between templates, since functions and global variables will not be cleared automatically.
prepend
my $code = $mt->prepend;
$mt = $mt->prepend('my $self = shift;');
|
Prepend Perl code to compiled template. Note that this code should not contain newline characters, or line numbers in error messages might end up being wrong.
replace_mark
my $mark = $mt->replace_mark;
$mt = $mt->replace_mark('%');
|
Character used for escaping the start of a tag or line, defaults to %.
tag_start
my $start = $mt->tag_start;
$mt = $mt->tag_start('<%');
|
Characters indicating the start of a tag, defaults to <%.
tag_end
my $end = $mt->tag_end;
$mt = $mt->tag_end('%>');
|
Characters indicating the end of a tag, defaults to %>.
tree
my $tree = $mt->tree;
$mt = $mt->tree([['text', 'foo'], ['line']]);
|
Template in parsed form. Note that this structure should only be used very carefully since it is very dynamic.
trim_mark
my $mark = $mt->trim_mark;
$mt = $mt->trim_mark('-');
|
Character activating automatic whitespace trimming, defaults to =.
unparsed
my $unparsed = $mt->unparsed;
$mt = $mt->unparsed('<%= 1 + 1 %>');
|
Raw unparsed template.
METHODS
Mojo::Template inherits all methods from Mojo::Base and implements the following new ones.
build
Build Perl "code" from "tree".
compile
my $exception = $mt->compile;
|
Compile Perl "code" for template.
interpret
my $output = $mt->interpret;
my $output = $mt->interpret(@args);
|
Interpret "compiled" template code.
say $mt->render('Hello <%= $_[0] %>!', 'Bender');
say $mt->interpret('Fry');
say $mt->interpret('Leela');
|
parse
$mt = $mt->parse('<%= 1 + 1 %>');
|
Parse template into "tree".
render
my $output = $mt->render('<%= 1 + 1 %>');
my $output = $mt->render('<%= shift() + shift() %>', @args);
|
Render template.
say $mt->render('Hello <%= $_[0] %>!', 'Bender');
|
render_file
my $output = $mt->render_file('/tmp/foo.mt');
my $output = $mt->render_file('/tmp/foo.mt', @args);
|
Render template file.
DEBUGGING
You can set the MOJO_TEMPLATE_DEBUG environment variable to get some advanced diagnostics information printed to STDERR.
SEE ALSO
Mojolicious, Mojolicious::Guides, http://mojolicio.us.