=encoding utf8 =head1 NAME Mojolicious::Guides::Rendering - Rendering =head1 OVERVIEW This document explains content generation with the L renderer. =head1 CONCEPTS Essentials every L developer should know. =head2 Renderer The renderer is a tiny black box turning stash data into actual responses utilizing multiple template systems and data encoding modules. {text => 'Hello.'} -> 200 OK, text/html, 'Hello.' {json => {x => 3}} -> 200 OK, application/json, '{"x":3}' {text => 'Oops.', status => '410'} -> 410 Gone, text/html, 'Oops.' Templates can be automatically detected if enough information is provided by the developer or routes. Template names are expected to follow the C scheme, with C defaulting to C or the route name, C defaulting to C and C to C. {controller => 'users', action => 'list'} -> 'users/list.html.ep' {name => 'foo', format => 'txt'} -> 'foo.txt.ep' {name => 'foo', handler => 'epl'} -> 'foo.html.epl' All templates should be in the C directories of the application or the C section of the class C
. __DATA__ @@ time.html.ep % use Time::Piece; % my $now = localtime; Time The time is <%= $now->hms %>. @@ hello.txt.ep ... The renderer can be easily extended to support additional template systems with plugins, but more about that later. =head2 Embedded Perl L includes a minimalistic but very powerful template system out of the box called Embedded Perl or C for short. It allows the embedding of Perl code right into actual content using a small set of special tags and line start characters. <% Perl code %> <%= Perl expression, replaced with XML escaped result %> <%== Perl expression, replaced with 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 Tags and lines work pretty much the same, but depending on context one will usually look a bit better. Semicolons get automatically appended to all expressions. <% my $i = 10; %>
    <% for my $j (1 .. $i) { %>
  • <%= $j %>
    • <% } %>
% my $i = 10;
    % for my $j (1 .. $i) {
  • %= $j
    • % }
Aside from differences in whitespace handling, both examples generate similar Perl code, a naive translation could look like this. my $output = ''; my $i = 10; $output .= '
    '; for my $j (1 .. $i) { $output .= '
  • '; $output .= xml_escape scalar $j; $output .= '
    • '; } $output .= '
'; return $output; An additional equal sign can be used to disable escaping of the characters C>, C>, C<&>, C<'> and C<"> in results from Perl expressions, which is the default to prevent XSS attacks against your application. <%= 'lalala' %> <%== '

test

' %> Only L objects are excluded from automatic escaping. % use Mojo::ByteStream 'b'; <%= b('

test

') %> 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 also add an additional equal sign to the end of a tag to have it automatically remove all surrounding whitespace, this allows free indenting without ruining the result. <% for (1 .. 3) { %> <%= $foo =%> <% } %> Stash values that don't have invalid characters in their name get automatically initialized as normal variables in the template, and the controller object as C<$self>. $self->stash(name => 'tester'); Hello <%= $name %> from <%= $self->tx->remote_address %>. There are also many helper functions available, but more about that later. <%= dumper {foo => 'bar'} %> =head1 BASICS Most commonly used features every L developer should know about. =head2 Automatic rendering The renderer can be manually started by calling the method L, but that's usually not necessary, because it will get automatically called if nothing has been rendered after the router finished its work. This also means you can have routes pointing only to templates without actual actions. $self->render; There is one big difference though, by calling it manually you can make sure that templates use the current controller object, and not the default controller specified with the attribute L. $self->render_later; You can also disable automatic rendering with the method L, which can be very useful to delay rendering when a non-blocking operation has to be performed first. =head2 Rendering templates The renderer will always try to detect the right template, but you can also use the C