The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Mojo-0.999912
River stage zero No dependents
++
/ Mojo::Template

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 or XML escaped result
        (depending on auto_escape attribute) %>
    <%== Perl expression, replaced with result or XML escaped result
         (depending on auto_escape attribute) %>
    <%# Comment, useful for debugging %>
    % Perl line
    %= Perl expression line, replaced with result or XML escaped result
       (depending on auto_escape attribute)
    %== Perl expression line,    replaced with result or XML escaped result
        (depending on auto_escape attribute)
    %# Comment line, useful for debugging

Whitespace characters around tags can be trimmed with a special tag ending.

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

Mojo::ByteStream objects are excluded from automatic escaping. 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::Template::Exception objects that stringify to error messages with context.

    Error around line 4.
    2: </head>
    3: <body>
    4: % my $i = 2; xx
    5: %= $i * 2
    6: </body>
    Bareword "xx" not allowed while "strict subs" in use at (eval 13)
    line 4.

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);

append

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

capture_end

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

capture_start

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

code

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

comment_mark

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

encoding

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

escape_mark

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

expression_mark

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

line_start

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

namespace

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

prepend

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

tag_start

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

tag_end

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

template

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

tree

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

trim_mark

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

METHODS

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

new

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

build

    $mt = $mt->build;

compile

    my $exception = $mt->compile;

interpret

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

parse

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

render

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

render_file

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

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_to_file

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