Mojo::Template.3pm

Langue: en

Version: 2010-08-12 (fedora - 01/12/10)

Section: 3 (Bibliothèques de fonctions)

Sommaire

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

Automatic 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 %>
     %= Perl expression line, replaced with XML escaped result
     %== Perl expression line, replaced with result

Mojo::ByteStream objects are always 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 whole template blocks for reuse later.

     <% my $block = {%>
         <% my $name = shift; =%>
         Hello <%= $name %>.
     <%}%>
     <%= $block->('Sebastian') %>
     <%= $block->('Sara') %>
 
     %{ my $block =
     % my $name = shift;
     Hello <%= $name %>.
     %}
     %= $block->('Baerbel')
     %= $block->('Wolfgang')

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

     %{ $block =
         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 $block = {%>
         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>.