Mojo::Template(3)

NAME
Mojo::Template - Perl-ish templates!

SYNOPSIS
  use Mojo::Template;

  # Simple
  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;

  # More advanced
  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 %>
  <%# Comment, useful for debugging %>
  <%% Replaced with "<%", useful for generating templates %>
  % Perl code line, treated as "<% line =%>" (explained later)
  %= Perl expression line, treated as "<%= line %>"
  %== Perl expression line, treated as "<%== line %>"
  %# Comment line, useful for debugging
  %% 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.

  % use Mojo::ByteStream 'b';
  <%= b('<div>excluded!</div>') %>

Whitespace characters around tags can be trimmed by adding an additional equal sign to the end of a tag.

  <% for (1 .. 3) { %>
    <%= 'Trim all whitespace characters around this expression' =%>
  <% } %>

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. Just be aware that both keywords are part of the surrounding tag and not actual Perl code, so there can only be whitespace after "begin" and before "end".

  <% 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.

  comment_mark
  my $mark = $mt->comment_mark;
  $mt      = $mt->comment_mark('#');

Character indicating the start of a comment, defaults to "#".

  <%# This is a comment %>

  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 "=".

  <%== $foo %>

  expression_mark
  my $mark = $mt->expression_mark;
  $mt      = $mt->expression_mark('=');

Character indicating the start of an expression, defaults to "=".

  <%= $foo %>

  line_start
  my $start = $mt->line_start;
  $mt       = $mt->line_start('%');

Character indicating the start of a code line, defaults to "%".

  % $foo = 23;

  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 "%".

  <%% my $foo = 23; %>

  tag_start
  my $start = $mt->tag_start;
  $mt       = $mt->tag_start('<%');

Characters indicating the start of a tag, defaults to "<%".

  <% $foo = 23; %>

  tag_end
  my $end = $mt->tag_end;
  $mt     = $mt->tag_end('%>');

Characters indicating the end of a tag, defaults to "%>".

  <%= $foo %>

  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 "=".

  <%= $foo =%>

  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
  $mt = $mt->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.

  # Reuse template
  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".

  MOJO_TEMPLATE_DEBUG=1

SEE ALSO
Mojolicious, Mojolicious::Guides, <http://mojolicio.us>.