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

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

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