The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Mojo-0.9002
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', \$output);
    <html>
      <head></head>
      <body>
        Time: <%= localtime(time) %>
      </body>
    </html>
    EOF
    print $output;

    # More complicated
    my $output;
    $mt->render(<<'EOF', \$output, 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. For bigger tasks you might want to use HTML::Mason or Template.

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

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->render(<<'EOF', \$output, 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 by setting the MOJO_TEMPLATE_DEBUG environment variable to 1, you can tell Mojo::Template to trace all errors that might occur and present them in a very convenient way with context.

    Template 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(\$output, @arguments);

ATTRIBUTES

code

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

comment_mark

    my $comment_mark = $mt->comment_mark;
    $mt              = $mt->comment_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('%');

template

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

tree

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

tag_start

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

tag_end

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

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

    $mt = $mt->compile;

interpret

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

parse

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

render

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

render_file

    my $success = $mt->render_file($template_file);
    my $success = $mt->render_file($template_file, \$result, @arguments);

render_file_to_file

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

render_to_file

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