NAME

Mojo::Template - Perlish Templates!

SYNOPSIS

    use Mojo::Template;
    my $mt = Mojo::Template->new;

    # Simple
    my $output = $mt->render(<<'EOF');
    <!doctype html><html>
        <head><title>Simple</title></head>
        <body>Time: <%= localtime(time) %></body>
    </html>
    EOF
    print $output;

    # More complicated
    my $output = $mt->render(<<'EOF', 23, 'foo bar');
    %= 5 * 5
    % my ($number, $text) = @_;
    test 123
    foo <% my $i = $number + 2; %>
    % for (1 .. 23) {
    * some text <%= $i++ %>
    % }
    EOF
    print $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 config file, generating text from heredocs and stuff like that.

    <% Inline Perl %>
    <%= Perl expression, replaced with result %>
    <%== Perl expression, replaced with XML escaped result %>
    <%# Comment, useful for debugging %>
    % Perl line
    %= Perl expression line, replaced with result
    %== Perl expression line, replaced with XML escaped result
    %# Comment line, useful for debugging

Mojo::ByteStream objects are excluded from automatic escaping. Whitespace characters around tags can be trimmed with a special tag ending.

    <%= All whitespace characters around this expression will be trimmed =%>

You can capture the result of a whole template block for reuse later.

    <%{ my $result = %>
    This will be assigned.
    <%}%>
    <%{= my $result = %>
    This will be assigned and passed through.
    <%}%>
    %{ my $result =
    This will be assigned.
    %}
    %{= my $result =
    This will be assigned and passed through.
    %}

Mojo::Template templates work just like Perl subs (actually they get compiled to a Perl sub internally). That means you can access arguments simply via @_.

    % my ($foo, $bar) = @_;
    % my $x = shift;
    test 123 <%= $foo %>

Note that you can't escape Mojo::Template tags, instead we just replace them if necessary.

    my $mt = Mojo::Template->new;
    $mt->line_start('@@');
    $mt->tag_start('[@@');
    $mt->tag_end('@@]');
    $mt->expression_mark('&');
    $mt->escape_mark('&');
    my $output = $mt->render(<<'EOF', 23);
    @@ my $i = shift;
    <% no code just text [@@&& $i @@]
    EOF

There is only one case that we can escape with a backslash, and thats a newline at the end of a template line.

   This is <%= 23 * 3 %> a\
   single line

If for some strange reason you absolutely need a backslash in front of a newline you can escape the backslash with another backslash.

    % use Data::Dumper;
    This will\\
    result <%=  Dumper {foo => 'bar'} %>\\
    in multiple lines

Templates get compiled to Perl code internally, this 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>

Mojo::Template does not support caching by itself, but you can easily build a wrapper around it.

    # Compile and store code somewhere
    my $mt = Mojo::Template->new;
    $mt->parse($template);
    $mt->build;
    my $code = $mt->code;

    # Load code and template (template for debug trace only)
    $mt->template($template);
    $mt->code($code);
    $mt->compile;
    my $output = $mt->interpret(@arguments);

ATTRIBUTES

Mojo::Template implements the following attributes.

auto_escape

    my $auto_escape = $mt->auto_escape;
    $mt             = $mt->auto_escape(1);

Activate automatic XML escaping.

append

    my $code = $mt->append;
    $mt      = $mt->append('warn "Processed template"');

Append Perl code to compiled template.

capture_end

    my $capture_end = $mt->capture_end;
    $mt             = $mt->capture_end('}');

Character indicating the end of a capture block, defaults to }.

    %{ $foo =
        Some data!
    %}

capture_start

    my $capture_start = $mt->capture_start;
    $mt               = $mt->capture_start('{');

Character indicating the start of a capture block, defaults to {.

    <%{ my $foo = %>
        Some data!
    <%}%>

code

    my $code = $mt->code;
    $mt      = $mt->code($code);

Compiled template code.

comment_mark

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

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

    <%# This is a comment %>

encoding

    my $encoding = $mt->encoding;
    $mt          = $mt->encoding('UTF-8');

Encoding used for template files.

escape_mark

    my $escape_mark = $mt->escape_mark;
    $mt             = $mt->escape_mark('=');

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

    <%== $foo %>

expression_mark

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

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

    <%= $foo %>

line_start

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

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

    % $foo = 23;

namespace

    my $namespace = $mt->namespace;
    $mt           = $mt->namespace('main');

Namespace used to compile templates.

prepend

    my $code = $mt->prepend;
    $mt      = $mt->prepend('my $self = shift;');

Prepend Perl code to compiled template.

tag_start

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

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

    <% $foo = 23; %>

tag_end

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

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

    <%= $foo %>

template

    my $template = $mt->template;
    $mt          = $mt->template($template);

Raw template.

tree

    my $tree = $mt->tree;
    $mt      = $mt->tree($tree);

Parsed tree.

trim_mark

    my $trim_mark = $mt->trim_mark;
    $mt           = $mt->trim_mark('-');

Character activating automatic whitespace trimming, defaults to =.

    <%= $foo =%>

METHODS

Mojo::Template inherits all methods from Mojo::Base and implements the following new ones.

new

    my $mt = Mojo::Template->new;

Construct a new Mojo::Template object.

build

    $mt = $mt->build;

Build template.

compile

    my $exception = $mt->compile;

Compile template.

interpret

    my $output = $mt->interpret;
    my $output = $mt->interpret(@arguments);

Interpret template.

parse

    $mt = $mt->parse($template);

Parse template.

render

    my $output = $mt->render($template);
    my $output = $mt->render($template, @arguments);

Render template.

render_file

    my $output = $mt->render_file($template_file);
    my $output = $mt->render_file($template_file, @arguments);

Render template file.

render_file_to_file

    my $exception = $mt->render_file_to_file($template_file, $output_file);
    my $exception = $mt->render_file_to_file(
        $template_file, $output_file, @arguments
    );

Render template file to a specific file.

render_to_file

    my $exception = $mt->render_to_file($template, $output_file);
    my $exception = $mt->render_to_file(
        $template, $output_file, @arguments
    );

Render template to a specific file.

SEE ALSO

Mojolicious, Mojolicious::Guides, http://mojolicious.org.