1Mojolicious::Guides::ReUnsdeerriCnogn(t3r)ibuted Perl DoMcoujmoelnitcaitoiuosn::Guides::Rendering(3)
2
6 Mojolicious::Guides::Rendering - Rendering content
7
9 This document explains content generation with the Mojolicious
10 renderer.
11
13 Essentials every Mojolicious developer should know.
14 Renderer
16 The renderer is a tiny black box turning stash data into actual
17 responses utilizing multiple template systems and data encoding
18 modules.
19 {text => 'Hello.'} -> 200 OK, text/html, 'Hello.'
21 {json => {x => 3}} -> 200 OK, application/json, '{"x":3}'
22 {text => 'Oops.', status => '410'} -> 410 Gone, text/html, 'Oops.'
23 Templates can be automatically detected if enough information is
25 provided by the developer or routes. Template names are expected to
26 follow the "template.format.handler" scheme, with "template" defaulting
27 to "controller/action" or the route name, "format" defaulting to "html"
28 and "handler" to "ep".
29 {controller => 'users', action => 'list'} -> 'users/list.html.ep'
31 {template => 'foo', format => 'txt'} -> 'foo.txt.ep'
32 {template => 'foo', handler => 'epl'} -> 'foo.html.epl'
33 The "controller" value gets converted from "CamelCase" to "snake_case"
35 using "decamelize" in Mojo::Util and "-" characters replaced with "/".
36 {controller => 'My::Users', action => 'add'} -> 'my/users/add.html.ep'
38 {controller => 'my-users', action => 'show'} -> 'my/users/show.html.ep'
39 All templates should be in the "templates" directories of the
41 application, which can be customized with "paths" in
42 Mojolicious::Renderer, or one of the the "DATA" sections from "classes"
43 in Mojolicious::Renderer.
44 __DATA__
46 @@ time.html.ep
48 % use Time::Piece;
49 % my $now = localtime;
50 <!DOCTYPE html>
51 <html>
52 <head><title>Time</title></head>
53 <body>The time is <%= $now->hms %>.</body>
54 </html>
55 @@ hello.txt.ep
57 ...
58 The renderer can be easily extended to support additional template
60 systems with plugins, but more about that later.
61 Embedded Perl
63 Mojolicious includes a minimalistic but very powerful template system
64 out of the box called Embedded Perl or "ep" for short. It is based on
65 Mojo::Template and allows the embedding of Perl code right into actual
66 content using a small set of special tags and line start characters.
67 For all templates strict, warnings, utf8 and Perl 5.10 features are
68 automatically enabled.
69 <% Perl code %>
71 <%= Perl expression, replaced with XML escaped result %>
72 <%== Perl expression, replaced with result %>
73 <%# Comment, useful for debugging %>
74 <%% Replaced with "<%", useful for generating templates %>
75 % Perl code line, treated as "<% line =%>" (explained later)
76 %= Perl expression line, treated as "<%= line %>"
77 %== Perl expression line, treated as "<%== line %>"
78 %# Comment line, useful for debugging
79 %% Replaced with "%", useful for generating templates
80 Tags and lines work pretty much the same, but depending on context one
82 will usually look a bit better. Semicolons get automatically appended
83 to all expressions.
84 <% my $i = 10; %>
86 <ul>
87 <% for my $j (1 .. $i) { %>
88 <li>
89 <%= $j %>
90 </li>
91 <% } %>
92 </ul>
93 % my $i = 10;
95 <ul>
96 % for my $j (1 .. $i) {
97 <li>
98 %= $j
99 </li>
100 % }
101 </ul>
102 Aside from differences in whitespace handling, both examples generate
104 similar Perl code, a naive translation could look like this.
105 my $output = '';
107 my $i = 10;
108 $output .= '<ul>';
109 for my $j (1 .. $i) {
110 $output .= '<li>';
111 $output .= xml_escape scalar + $j;
112 $output .= '</li>';
113 }
114 $output .= '</ul>';
115 return $output;
116 An additional equal sign can be used to disable escaping of the
118 characters "<", ">", "&", "'" and """ in results from Perl expressions,
119 which is the default to prevent XSS attacks against your application.
120 <%= 'I ♥ Mojolicious!' %>
122 <%== '<p>I ♥ Mojolicious!</p>' %>
123 Only Mojo::ByteStream objects are excluded from automatic escaping.
125 <%= b('<p>I ♥ Mojolicious!</p>') %>
127 Whitespace characters around tags can be trimmed by adding an
129 additional equal sign to the end of a tag.
130 <% for (1 .. 3) { %>
132 <%= 'Trim all whitespace characters around this expression' =%>
133 <% } %>
134 Newline characters can be escaped with a backslash.
136 This is <%= 1 + 1 %> a\
138 single line
139 And a backslash in front of a newline character can be escaped with
141 another backslash.
142 This will <%= 1 + 1 %> result\\
144 in multiple\\
145 lines
146 A newline character gets appended automatically to every template,
148 unless the last character is a backslash. And empty lines at the end of
149 a template are ignored.
150 There is <%= 1 + 1 %> no newline at the end here\
152 At the beginning of the template, stash values that don't have invalid
154 characters in their name get automatically initialized as normal
155 variables, and the controller object as both $self and $c.
156 $c->stash(name => 'tester');
158 Hello <%= $name %> from <%= $c->tx->remote_address %>.
160 A prefix like "myapp.*" is commonly used for stash values that you
162 don't want to expose in templates.
163 $c->stash('myapp.name' => 'tester');
165 There are also many helper functions available, but more about that
167 later.
168 <%= dumper {foo => 'bar'} %>
170
172 Most commonly used features every Mojolicious developer should know
173 about.
174 Automatic rendering
176 The renderer can be manually started by calling the method "render" in
177 Mojolicious::Controller, but that's usually not necessary, because it
178 will get automatically called if nothing has been rendered after the
179 router finished its work. This also means you can have routes pointing
180 only to templates without actual actions.
181 $c->render;
183 There is one big difference though, by calling it manually you can make
185 sure that templates use the current controller object, and not the
186 default controller specified with the attribute "controller_class" in
187 Mojolicious.
188 $c->render_later;
190 You can also disable automatic rendering with the method "render_later"
192 in Mojolicious::Controller, which can be very useful to delay rendering
193 when a non-blocking operation has to be performed first.
194 Rendering templates
196 The renderer will always try to detect the right template, but you can
197 also use the "template" stash value to render a specific one.
198 Everything before the last slash will be interpreted as the
199 subdirectory path in which to find the template.
200 # foo/bar/baz.*.*
202 $c->render(template => 'foo/bar/baz');
203 Choosing a specific "format" and "handler" is just as easy.
205 # foo/bar/baz.txt.epl
207 $c->render(template => 'foo/bar/baz', format => 'txt', handler => 'epl');
208 Because rendering a specific template is the most common task it also
210 has a shortcut.
211 $c->render('foo/bar/baz');
213 If you're not sure in advance if a template actually exists, you can
215 also use the method "render_maybe" in Mojolicious::Controller to try
216 multiple alternatives.
217 $c->render_maybe('localized/baz') or $c->render('foo/bar/baz');
219 Rendering to strings
221 Sometimes you might want to use the rendered result directly instead of
222 generating a response, for example, to send emails, this can be done
223 with "render_to_string" in Mojolicious::Controller.
224 my $html = $c->render_to_string('mail');
226 No encoding will be performed, making it easy to reuse the result in
228 other templates or to generate binary data.
229 my $pdf = $c->render_to_string('invoice', format => 'pdf');
231 $c->render(data => $pdf, format => 'pdf');
232 All arguments passed will get localized automatically and are only
234 available during this render operation.
235 Template variants
237 To make your application look great on many different devices you can
238 also use the "variant" stash value to choose between different variants
239 of your templates.
240 # foo/bar/baz.html+phone.ep
242 # foo/bar/baz.html.ep
243 $c->render('foo/bar/baz', variant => 'phone');
244 This can be done very liberally since it only applies when a template
246 with the correct name actually exists and falls back to the generic one
247 otherwise.
248 Rendering inline templates
250 Some renderers such as "ep" allow templates to be passed "inline".
251 $c->render(inline => 'The result is <%= 1 + 1 %>.');
253 Since auto-detection depends on a path you might have to supply a
255 "handler" too.
256 $c->render(inline => "<%= shift->param('foo') %>", handler => 'epl');
258 Rendering text
260 Characters can be rendered to bytes with the "text" stash value, the
261 given content will be automatically encoded with "encoding" in
262 Mojolicious::Renderer.
263 $c->render(text => 'I ♥ Mojolicious!');
265 Rendering data
267 Bytes can be rendered with the "data" stash value, no encoding will be
268 performed.
269 $c->render(data => $bytes);
271 Rendering JSON
273 The "json" stash value allows you to pass Perl data structures to the
274 renderer which get directly encoded to JSON with Mojo::JSON.
275 $c->render(json => {foo => [1, 'test', 3]});
277 Status code
279 Response status codes can be changed with the "status" stash value.
280 $c->render(text => 'Oops.', status => 500);
282 Content type
284 The "Content-Type" header of the response is actually based on the MIME
285 type mapping of the "format" stash value.
286 # Content-Type: text/plain
288 $c->render(text => 'Hello.', format => 'txt');
289 # Content-Type: image/png
291 $c->render(data => $bytes, format => 'png');
292 These mappings can be easily extended or changed with "types" in
294 Mojolicious.
295 # Add new MIME type
297 $app->types->type(md => 'text/markdown');
298 Stash data
300 Any of the native Perl data types can be passed to templates as
301 references through the "stash" in Mojolicious::Controller.
302 $c->stash(description => 'web framework');
304 $c->stash(frameworks => ['Catalyst', 'Mojolicious']);
305 $c->stash(spinoffs => {minion => 'job queue'});
306 %= $description
308 %= $frameworks->[1]
309 %= $spinoffs->{minion}
310 Since everything is just Perl normal control structures just work.
312 % for my $framework (@$frameworks) {
314 <%= $framework %> is a <%= $description %>.
315 % }
316 % if (my $description = $spinoffs->{minion}) {
318 Minion is a <%= $description %>.
319 % }
320 For templates that might get rendered in different ways and where
322 you're not sure if a stash value will actually be set, you can just use
323 the helper "stash" in Mojolicious::Plugin::DefaultHelpers.
324 % if (my $spinoffs = stash 'spinoffs') {
326 Minion is a <%= $spinoffs->{minion} %>.
327 % }
328 Helpers
330 Helpers are little functions you can use in templates as well as
331 application and controller code.
332 # Template
334 %= dumper [1, 2, 3]
335 # Application
337 my $serialized = $app->dumper([1, 2, 3]);
338 # Controller
340 my $serialized = $c->dumper([1, 2, 3]);
341 We differentiate between default helpers, which are more general
343 purpose like "dumper" in Mojolicious::Plugin::DefaultHelpers, and tag
344 helpers like "link_to" in Mojolicious::Plugin::TagHelpers, which are
345 template specific and mostly used to generate HTML tags.
346 %= link_to Mojolicious => 'https://mojolicious.org'
348 In controllers you can also use the method "helpers" in
350 Mojolicious::Controller to fully qualify helper calls and ensure that
351 they don't conflict with existing methods you may already have.
352 my $serialized = $c->helpers->dumper([1, 2, 3]);
354 A list of all built-in helpers can be found in
356 Mojolicious::Plugin::DefaultHelpers and
357 Mojolicious::Plugin::TagHelpers.
358 Content negotiation
360 For resources with different representations and that require truly
361 RESTful content negotiation you can also use "respond_to" in
362 Mojolicious::Plugin::DefaultHelpers instead of "render" in
363 Mojolicious::Controller.
364 # /hello (Accept: application/json) -> "json"
366 # /hello (Accept: application/xml) -> "xml"
367 # /hello.json -> "json"
368 # /hello.xml -> "xml"
369 # /hello?format=json -> "json"
370 # /hello?format=xml -> "xml"
371 $c->respond_to(
372 json => {json => {hello => 'world'}},
373 xml => {text => '<hello>world</hello>'}
374 );
375 The best possible representation will be automatically selected from
377 the "format" "GET"/"POST" parameter, "format" stash value or "Accept"
378 request header and stored in the "format" stash value. To change MIME
379 type mappings for the "Accept" request header or the "Content-Type"
380 response header you can use "types" in Mojolicious.
381 $c->respond_to(
383 json => {json => {hello => 'world'}},
384 html => sub {
385 $c->content_for(head => '<meta name="author" content="sri">');
386 $c->render(template => 'hello', message => 'world')
387 }
388 );
389 Callbacks can be used for representations that are too complex to fit
391 into a single render call.
392 # /hello (Accept: application/json) -> "json"
394 # /hello (Accept: text/html) -> "html"
395 # /hello (Accept: image/png) -> "any"
396 # /hello.json -> "json"
397 # /hello.html -> "html"
398 # /hello.png -> "any"
399 # /hello?format=json -> "json"
400 # /hello?format=html -> "html"
401 # /hello?format=png -> "any"
402 $c->respond_to(
403 json => {json => {hello => 'world'}},
404 html => {template => 'hello', message => 'world'},
405 any => {text => '', status => 204}
406 );
407 And if no viable representation could be found, the "any" fallback will
409 be used or an empty 204 response rendered automatically.
410 # /hello -> "html"
412 # /hello (Accept: text/html) -> "html"
413 # /hello (Accept: text/xml) -> "xml"
414 # /hello (Accept: text/plain) -> undef
415 # /hello.html -> "html"
416 # /hello.xml -> "xml"
417 # /hello.txt -> undef
418 # /hello?format=html -> "html"
419 # /hello?format=xml -> "xml"
420 # /hello?format=txt -> undef
421 if (my $format = $c->accepts('html', 'xml')) {
422 ...
423 }
424 For even more advanced negotiation logic you can also use the helper
426 "accepts" in Mojolicious::Plugin::DefaultHelpers.
427 Rendering "exception" and "not_found" pages
429 By now you've probably already encountered the built-in 404 (Not Found)
430 and 500 (Server Error) pages, that get rendered automatically when you
431 make a mistake. Those are fallbacks for when your own exception
432 handling fails, which can be especially helpful during development. You
433 can also render them manually with the helpers "reply->exception" in
434 Mojolicious::Plugin::DefaultHelpers and "reply->not_found" in
435 Mojolicious::Plugin::DefaultHelpers.
436 use Mojolicious::Lite;
438 use Scalar::Util 'looks_like_number';
439 get '/divide/:dividend/by/:divisor' => sub {
441 my $c = shift;
442 my $dividend = $c->param('dividend');
444 my $divisor = $c->param('divisor');
445 # 404
447 return $c->reply->not_found
448 unless looks_like_number $dividend && looks_like_number $divisor;
449 # 500
451 return $c->reply->exception('Division by zero!') if $divisor == 0;
452 # 200
454 $c->render(text => $dividend / $divisor);
455 };
456 app->start;
458 You can also change the templates of those pages, since you most likely
460 want to show your users something more closely related to your
461 application in production. The renderer will always try to find
462 "exception.$mode.$format.*" or "not_found.$mode.$format.*" before
463 falling back to the built-in default templates.
464 use Mojolicious::Lite;
466 get '/dies' => sub { die 'Intentional error' };
468 app->start;
470 __DATA__
471 @@ exception.production.html.ep
473 <!DOCTYPE html>
474 <html>
475 <head><title>Server error</title></head>
476 <body>
477 <h1>Exception</h1>
478 <p><%= $exception->message %></p>
479 <h1>Stash</h1>
480 <pre><%= dumper $snapshot %></pre>
481 </body>
482 </html>
483 The hook "before_render" in Mojolicious makes even more advanced
485 customizations possible by allowing you to intercept and modify the
486 arguments passed to the renderer.
487 use Mojolicious::Lite;
489 hook before_render => sub {
491 my ($c, $args) = @_;
492 # Make sure we are rendering the exception template
494 return unless my $template = $args->{template};
495 return unless $template eq 'exception';
496 # Switch to JSON rendering if content negotiation allows it
498 $args->{json} = {exception => $args->{exception}} if $c->accepts('json');
499 };
500 get '/' => sub { die "This sho...ALL GLORY TO THE HYPNOTOAD!\n" };
502 app->start;
504 Layouts
506 Most of the time when using "ep" templates you will want to wrap your
507 generated content in an HTML skeleton, thanks to layouts that's
508 absolutely trivial.
509 use Mojolicious::Lite;
511 get '/' => {template => 'foo/bar'};
513 app->start;
515 __DATA__
516 @@ foo/bar.html.ep
518 % layout 'mylayout';
519 Hello World!
520 @@ layouts/mylayout.html.ep
522 <!DOCTYPE html>
523 <html>
524 <head><title>MyApp</title></head>
525 <body><%= content %></body>
526 </html>
527 You just select the right layout template with the helper "layout" in
529 Mojolicious::Plugin::DefaultHelpers and place the result of the current
530 template with the helper "content" in
531 Mojolicious::Plugin::DefaultHelpers. You can also pass along normal
532 stash values to the "layout" helper.
533 use Mojolicious::Lite;
535 get '/' => {template => 'foo/bar'};
537 app->start;
539 __DATA__
540 @@ foo/bar.html.ep
542 % layout 'mylayout', title => 'Hi there';
543 Hello World!
544 @@ layouts/mylayout.html.ep
546 <!DOCTYPE html>
547 <html>
548 <head><title><%= $title %></title></head>
549 <body><%= content %></body>
550 </html>
551 Instead of the "layout" helper you could also just use the "layout"
553 stash value, or call "render" in Mojolicious::Controller with the
554 "layout" argument.
555 $c->render(template => 'mytemplate', layout => 'mylayout');
557 To set a "layout" stash value application-wide you can use "defaults"
559 in Mojolicious.
560 $app->defaults(layout => 'mylayout');
562 Layouts can also be used with "render_to_string" in
564 Mojolicious::Controller, but the "layout" value needs to be passed as a
565 render argument (not a stash value).
566 my $html = $c->render_to_string('reminder', layout => 'mail');
568 Partial templates
570 You can break up bigger templates into smaller, more manageable chunks.
571 These partial templates can also be shared with other templates. Just
572 use the helper "include" in Mojolicious::Plugin::DefaultHelpers to
573 include one template into another.
574 use Mojolicious::Lite;
576 get '/' => {template => 'foo/bar'};
578 app->start;
580 __DATA__
581 @@ foo/bar.html.ep
583 <!DOCTYPE html>
584 <html>
585 %= include '_header', title => 'Howdy'
586 <body>Bar</body>
587 </html>
588 @@ _header.html.ep
590 <head><title><%= $title %></title></head>
591 You can name partial templates however you like, but a leading
593 underscore is a commonly used naming convention.
594 Reusable template blocks
596 It's never fun to repeat yourself, that's why you can build reusable
597 template blocks in "ep" that work very similar to normal Perl
598 functions, with the "begin" and "end" keywords. Just be aware that both
599 keywords are part of the surrounding tag and not actual Perl code, so
600 there can only be whitespace after "begin" and before "end".
601 use Mojolicious::Lite;
603 get '/' => 'welcome';
605 app->start;
607 __DATA__
608 @@ welcome.html.ep
610 <% my $block = begin %>
611 % my $name = shift;
612 Hello <%= $name %>.
613 <% end %>
614 <%= $block->('Wolfgang') %>
615 <%= $block->('Baerbel') %>
616 A naive translation of the template to Perl code could look like this.
618 my $output = '';
620 my $block = sub {
621 my $name = shift;
622 my $output = '';
623 $output .= 'Hello ';
624 $output .= xml_escape scalar + $name;
625 $output .= '.';
626 return Mojo::ByteStream->new($output);
627 };
628 $output .= xml_escape scalar + $block->('Wolfgang');
629 $output .= xml_escape scalar + $block->('Baerbel');
630 return $output;
631 While template blocks cannot be shared between templates, they are most
633 commonly used to pass parts of a template to helpers.
634 Adding helpers
636 You should always try to keep your actions small and reuse as much code
637 as possible. Helpers make this very easy, they get passed the current
638 controller object as first argument, and you can use them to do pretty
639 much anything an action could do.
640 use Mojolicious::Lite;
642 helper debug => sub {
644 my ($c, $str) = @_;
645 $c->app->log->debug($str);
646 };
647 get '/' => sub {
649 my $c = shift;
650 $c->debug('Hello from an action!');
651 } => 'index';
652 app->start;
654 __DATA__
655 @@ index.html.ep
657 % debug 'Hello from a template!';
658 Helpers can also accept template blocks as last argument, this for
660 example, allows very pleasant to use tag helpers and filters. Wrapping
661 the helper result into a Mojo::ByteStream object can prevent accidental
662 double escaping.
663 use Mojolicious::Lite;
665 use Mojo::ByteStream;
666 helper trim_newline => sub {
668 my ($c, $block) = @_;
669 my $result = $block->();
670 $result =~ s/\n//g;
671 return Mojo::ByteStream->new($result);
672 };
673 get '/' => 'index';
675 app->start;
677 __DATA__
678 @@ index.html.ep
680 %= trim_newline begin
681 Some text.
682 %= 1 + 1
683 More text.
684 % end
685 Similar to stash values, you can use a prefix like "myapp.*" to keep
687 helpers from getting exposed in templates as functions, and to organize
688 them into namespaces as your application grows. Every prefix
689 automatically becomes a helper that returns a proxy object containing
690 the current controller object and on which you can call the nested
691 helpers.
692 use Mojolicious::Lite;
694 helper 'cache_control.no_caching' => sub {
696 my $c = shift;
697 $c->res->headers->cache_control('private, max-age=0, no-cache');
698 };
699 helper 'cache_control.five_minutes' => sub {
701 my $c = shift;
702 $c->res->headers->cache_control('public, max-age=300');
703 };
704 get '/news' => sub {
706 my $c = shift;
707 $c->cache_control->no_caching;
708 $c->render(text => 'Always up to date.');
709 };
710 get '/some_older_story' => sub {
712 my $c = shift;
713 $c->cache_control->five_minutes;
714 $c->render(text => 'This one can be cached for a bit.');
715 };
716 app->start;
718 While helpers can also be redefined, this should only be done very
720 carefully to avoid conflicts.
721 Content blocks
723 The helper "content_for" in Mojolicious::Plugin::DefaultHelpers allows
724 you to pass whole blocks of content from one template to another. This
725 can be very useful when your layout has distinct sections, such as
726 sidebars, where content should be inserted by the template.
727 use Mojolicious::Lite;
729 get '/' => 'foo';
731 app->start;
733 __DATA__
734 @@ foo.html.ep
736 % layout 'mylayout';
737 % content_for header => begin
738 <meta http-equiv="Content-Type" content="text/html">
739 % end
740 <div>Hello World!</div>
741 % content_for header => begin
742 <meta http-equiv="Pragma" content="no-cache">
743 % end
744 @@ layouts/mylayout.html.ep
746 <!DOCTYPE html>
747 <html>
748 <head><%= content 'header' %></head>
749 <body><%= content %></body>
750 </html>
751 Forms
753 To build HTML forms more efficiently you can use tag helpers like
754 "form_for" in Mojolicious::Plugin::TagHelpers, which can automatically
755 select a request method for you if a route name is provided. And since
756 most browsers only allow forms to be submitted with "GET" and "POST",
757 but not request methods like "PUT" or "DELETE", they are spoofed with
758 an "_method" query parameter.
759 use Mojolicious::Lite;
761 get '/' => 'form';
763 # PUT /nothing
765 # POST /nothing?_method=PUT
766 put '/nothing' => sub {
767 my $c = shift;
768 # Prevent double form submission with redirect
770 my $value = $c->param('whatever');
771 $c->flash(confirmation => "We did nothing with your value ($value).");
772 $c->redirect_to('form');
773 };
774 app->start;
776 __DATA__
777 @@ form.html.ep
779 <!DOCTYPE html>
780 <html>
781 <body>
782 % if (my $confirmation = flash 'confirmation') {
783 <p><%= $confirmation %></p>
784 % }
785 %= form_for nothing => begin
786 %= text_field whatever => 'I ♥ Mojolicious!'
787 %= submit_button
788 % end
789 </body>
790 </html>
791 The helpers "flash" in Mojolicious::Plugin::DefaultHelpers and
793 "redirect_to" in Mojolicious::Plugin::DefaultHelpers are often used
794 together to prevent double form submission, allowing users to receive a
795 confirmation message that will vanish if they decide to reload the page
796 they've been redirected to.
797 Form validation
799 You can use "validation" in Mojolicious::Plugin::DefaultHelpers to
800 validate "GET" and "POST" parameters submitted to your application. All
801 unknown fields will be ignored by default, so you have to decide which
802 should be required or optional before you can perform checks on their
803 values. Every check is performed right away, so you can use the results
804 immediately to build more advanced validation logic with methods like
805 "is_valid" in Mojolicious::Validator::Validation.
806 use Mojolicious::Lite;
808 get '/' => sub {
810 my $c = shift;
811 # Check if parameters have been submitted
813 my $v = $c->validation;
814 return $c->render unless $v->has_data;
815 # Validate parameters ("pass_again" depends on "pass")
817 $v->required('user')->size(1, 20)->like(qr/^[a-z0-9]+$/);
818 $v->required('pass_again')->equal_to('pass')
819 if $v->optional('pass')->size(7, 500)->is_valid;
820 # Render confirmation if validation was successful
822 $c->render('thanks') unless $v->has_error;
823 } => 'index';
824 app->start;
826 __DATA__
827 @@ index.html.ep
829 <!DOCTYPE html>
830 <html>
831 <head>
832 <style>
833 label.field-with-error { color: #dd7e5e }
834 input.field-with-error { background-color: #fd9e7e }
835 </style>
836 </head>
837 <body>
838 %= form_for index => begin
839 %= label_for user => 'Username (required, 1-20 characters, a-z/0-9)'
840 <br>
841 %= text_field 'user', id => 'user'
842 %= submit_button
843 <br>
844 %= label_for pass => 'Password (optional, 7-500 characters)'
845 <br>
846 %= password_field 'pass', id => 'pass'
847 <br>
848 %= label_for pass_again => 'Password again (equal to the value above)'
849 <br>
850 %= password_field 'pass_again', id => 'pass_again'
851 % end
852 </body>
853 </html>
854 @@ thanks.html.ep
856 <!DOCTYPE html>
857 <html><body>Thank you <%= validation->param('user') %>.</body></html>
858 Form elements generated with tag helpers from
860 Mojolicious::Plugin::TagHelpers will automatically remember their
861 previous values and add the class "field-with-error" for fields that
862 failed validation to make styling with CSS easier.
863 <label class="field-with-error" for="user">
865 Username (required, only characters e-t)
866 </label>
867 <input class="field-with-error" type="text" name="user" value="sri">
868 For a full list of available checks see also "CHECKS" in
870 Mojolicious::Validator.
871 Adding form validation checks
873 Validation checks can be registered with "add_check" in
874 Mojolicious::Validator and return a false value if they were
875 successful. A true value may be used to pass along additional
876 information which can then be retrieved with "error" in
877 Mojolicious::Validator::Validation.
878 use Mojolicious::Lite;
880 # Add "range" check
882 app->validator->add_check(range => sub {
883 my ($v, $name, $value, $min, $max) = @_;
884 return $value < $min || $value > $max;
885 });
886 get '/' => 'form';
888 post '/test' => sub {
890 my $c = shift;
891 # Validate parameters with custom check
893 my $v = $c->validation;
894 $v->required('number')->range(3, 23);
895 # Render form again if validation failed
897 return $c->render('form') if $v->has_error;
898 # Prevent double form submission with redirect
900 $c->flash(number => $v->param('number'));
901 $c->redirect_to('form');
902 };
903 app->start;
905 __DATA__
906 @@ form.html.ep
908 <!DOCTYPE html>
909 <html>
910 <body>
911 % if (my $number = flash 'number') {
912 <p>Thanks, the number <%= $number %> was valid.</p>
913 % }
914 %= form_for test => begin
915 % if (my $err = validation->error('number')) {
916 <p>
917 %= 'Value is required.' if $err->[0] eq 'required'
918 %= 'Value needs to be between 3 and 23.' if $err->[0] eq 'range'
919 </p>
920 % }
921 %= text_field 'number'
922 %= submit_button
923 % end
924 </body>
925 </html>
926 Cross-site request forgery
928 CSRF is a very common attack on web applications that trick your logged
929 in users to submit forms they did not intend to send, with something as
930 mundane as a link. All you have to do, to protect your users from this,
931 is to add an additional hidden field to your forms with "csrf_field" in
932 Mojolicious::Plugin::TagHelpers, and validate it with "csrf_protect" in
933 Mojolicious::Validator::Validation.
934 use Mojolicious::Lite;
936 get '/' => {template => 'target'};
938 post '/' => sub {
940 my $c = shift;
941 # Check CSRF token
943 my $v = $c->validation;
944 return $c->render(text => 'Bad CSRF token!', status => 403)
945 if $v->csrf_protect->has_error('csrf_token');
946 my $city = $v->required('city')->param('city');
948 $c->render(text => "Low orbit ion cannon pointed at $city!")
949 unless $v->has_error;
950 } => 'target';
951 app->start;
953 __DATA__
954 @@ target.html.ep
956 <!DOCTYPE html>
957 <html>
958 <body>
959 %= form_for target => begin
960 %= csrf_field
961 %= label_for city => 'Which city to point low orbit ion cannon at?'
962 %= text_field 'city', id => 'city'
963 %= submit_button
964 %= end
965 </body>
966 </html>
967 For Ajax requests and the like, you can also generate a token directly
969 with the helper "csrf_token" in Mojolicious::Plugin::DefaultHelpers,
970 and then pass it along with the "X-CSRF-Token" request header.
971
973 Less commonly used and more powerful features.
974 Template inheritance
976 Inheritance takes the layout concept above one step further, the
977 helpers "content" in Mojolicious::Plugin::DefaultHelpers and "extends"
978 in Mojolicious::Plugin::DefaultHelpers allow you to build skeleton
979 templates with named blocks that child templates can override.
980 use Mojolicious::Lite;
982 # first > mylayout
984 get '/first' => {template => 'first', layout => 'mylayout'};
985 # third > second > first > mylayout
987 get '/third' => {template => 'third', layout => 'mylayout'};
988 app->start;
990 __DATA__
991 @@ layouts/mylayout.html.ep
993 <!DOCTYPE html>
994 <html>
995 <head><title>Hello</title></head>
996 <body><%= content %></body>
997 </html>
998 @@ first.html.ep
1000 %= content header => begin
1001 Default header
1002 % end
1003 <div>Hello World!</div>
1004 %= content footer => begin
1005 Default footer
1006 % end
1007 @@ second.html.ep
1009 % extends 'first';
1010 % content header => begin
1011 New header
1012 % end
1013 @@ third.html.ep
1015 % extends 'second';
1016 % content footer => begin
1017 New footer
1018 % end
1019 This chain could go on and on to allow a very high level of template
1021 reuse.
1022 Serving static files
1024 Static files are automatically served from the "public" directories of
1025 the application, which can be customized with "paths" in
1026 Mojolicious::Static, or one of the "DATA" sections from "classes" in
1027 Mojolicious::Static. And if that's not enough you can also serve them
1028 manually with "reply->static" in Mojolicious::Plugin::DefaultHelpers
1029 and "reply->file" in Mojolicious::Plugin::DefaultHelpers.
1030 use Mojolicious::Lite;
1032 get '/' => sub {
1034 my $c = shift;
1035 $c->reply->static('index.html');
1036 };
1037 get '/some_download' => sub {
1039 my $c = shift;
1040 $c->res->headers->content_disposition('attachment; filename=bar.png;');
1041 $c->reply->static('foo/bar.png');
1042 };
1043 get '/leak' => sub {
1045 my $c = shift;
1046 $c->reply->file('/etc/passwd');
1047 };
1048 app->start;
1050 Custom responses
1052 Most response content, static as well as dynamic, gets served through
1053 Mojo::Asset::File and Mojo::Asset::Memory objects. For somewhat static
1054 content, like cached JSON data or temporary files, you can create your
1055 own and use the helper "reply->asset" in
1056 Mojolicious::Plugin::DefaultHelpers to serve them while allowing
1057 content negotiation to be performed with "Range", "If-Modified-Since"
1058 and "If-None-Match" headers.
1059 use Mojolicious::Lite;
1061 use Mojo::Asset::File;
1062 get '/leak' => sub {
1064 my $c = shift;
1065 $c->res->headers->content_type('text/plain');
1066 $c->reply->asset(Mojo::Asset::File->new(path => '/etc/passwd'));
1067 };
1068 app->start;
1070 For even more control you can also just skip the helper and use
1072 "rendered" in Mojolicious::Controller to tell the renderer when you're
1073 done generating a response.
1074 use Mojolicious::Lite;
1076 use Mojo::Asset::File;
1077 get '/leak' => sub {
1079 my $c = shift;
1080 $c->res->headers->content_type('text/plain');
1081 $c->res->content->asset(Mojo::Asset::File->new(path => '/etc/passwd'));
1082 $c->rendered(200);
1083 };
1084 app->start;
1086 Helper plugins
1088 Some helpers might be useful enough for you to share them between
1089 multiple applications, plugins make that very simple.
1090 package Mojolicious::Plugin::DebugHelper;
1092 use Mojo::Base 'Mojolicious::Plugin';
1093 sub register {
1095 my ($self, $app) = @_;
1096 $app->helper(debug => sub {
1097 my ($c, $str) = @_;
1098 $c->app->log->debug($str);
1099 });
1100 }
1101 1;
1103 The "register" method will be called when you load the plugin. And to
1105 add your helper to the application, you can use "helper" in
1106 Mojolicious.
1107 use Mojolicious::Lite;
1109 plugin 'DebugHelper';
1111 get '/' => sub {
1113 my $c = shift;
1114 $c->debug('It works!');
1115 $c->render(text => 'Hello!');
1116 };
1117 app->start;
1119 A skeleton for a full CPAN compatible plugin distribution can be
1121 automatically generated.
1122 $ mojo generate plugin DebugHelper
1124 And if you have a "PAUSE" account (which can be requested at
1126 <http://pause.perl.org>), you are only a few commands away from
1127 releasing it to CPAN.
1128 $ perl Makefile.PL
1130 $ make test
1131 $ make manifest
1132 $ make dist
1133 $ mojo cpanify -u USER -p PASS Mojolicious-Plugin-DebugHelper-0.01.tar.gz
1134 Bundling assets with plugins
1136 Assets such as templates and static files can be easily bundled with
1137 your plugins, even if you plan to release them to CPAN.
1138 $ mojo generate plugin AlertAssets
1140 $ mkdir Mojolicious-Plugin-AlertAssets/lib/Mojolicious/Plugin/AlertAssets
1141 $ cd Mojolicious-Plugin-AlertAssets/lib/Mojolicious/Plugin/AlertAssets
1142 $ mkdir public
1143 $ echo 'alert("Hello World!");' > public/alertassets.js
1144 $ mkdir templates
1145 $ echo '%= javascript "/alertassets.js"' > templates/alertassets.html.ep
1146 Just give them reasonably unique names, ideally based on the name of
1148 your plugin, and append their respective directories to the list of
1149 search paths when "register" is called.
1150 package Mojolicious::Plugin::AlertAssets;
1152 use Mojo::Base 'Mojolicious::Plugin';
1153 use Mojo::File 'path';
1155 sub register {
1157 my ($self, $app) = @_;
1158 # Append "templates" and "public" directories
1160 my $base = path(__FILE__)->sibling('AlertAssets');
1161 push @{$app->renderer->paths}, $base->child('templates')->to_string;
1162 push @{$app->static->paths}, $base->child('public')->to_string;
1163 }
1164 1;
1166 Both will work just like normal "templates" and "public" directories
1168 once you've installed and loaded the plugin, with slightly lower
1169 precedence.
1170 use Mojolicious::Lite;
1172 plugin 'AlertAssets';
1174 get '/alert_me';
1176 app->start;
1178 __DATA__
1179 @@ alert_me.html.ep
1181 <!DOCTYPE html>
1182 <html>
1183 <head>
1184 <title>Alert me!</title>
1185 %= include 'alertassets'
1186 </head>
1187 <body>You've been alerted.</body>
1188 </html>
1189 And it works just the same for assets bundled in the "DATA" section of
1191 your plugin.
1192 package Mojolicious::Plugin::AlertAssets;
1194 use Mojo::Base 'Mojolicious::Plugin';
1195 sub register {
1197 my ($self, $app) = @_;
1198 # Append class
1200 push @{$app->renderer->classes}, __PACKAGE__;
1201 push @{$app->static->classes}, __PACKAGE__;
1202 }
1203 1;
1205 __DATA__
1206 @@ alertassets.js
1208 alert("Hello World!");
1209 @@ alertassets.html.ep
1211 %= javascript "/alertassets.js"
1212 Post-processing dynamic content
1214 While post-processing tasks are generally very easy with the hook
1215 "after_dispatch" in Mojolicious, for content generated by the renderer
1216 it is a lot more efficient to use "after_render" in Mojolicious.
1217 use Mojolicious::Lite;
1219 use IO::Compress::Gzip 'gzip';
1220 hook after_render => sub {
1222 my ($c, $output, $format) = @_;
1223 # Check if "gzip => 1" has been set in the stash
1225 return unless $c->stash->{gzip};
1226 # Check if user agent accepts gzip compression
1228 return unless ($c->req->headers->accept_encoding // '') =~ /gzip/i;
1229 $c->res->headers->append(Vary => 'Accept-Encoding');
1230 # Compress content with gzip
1232 $c->res->headers->content_encoding('gzip');
1233 gzip $output, \my $compressed;
1234 $$output = $compressed;
1235 };
1236 get '/' => {template => 'hello', title => 'Hello', gzip => 1};
1238 app->start;
1240 __DATA__
1241 @@ hello.html.ep
1243 <!DOCTYPE html>
1244 <html>
1245 <head><title><%= title %></title></head>
1246 <body>Compressed content.</body>
1247 </html>
1248 If you want to compress all dynamically generated content you can also
1250 activate "compress" in Mojolicious::Renderer.
1251 Streaming
1253 You don't have to render all content at once, the method "write" in
1254 Mojolicious::Controller can also be used to stream a series of smaller
1255 chunks.
1256 use Mojolicious::Lite;
1258 get '/' => sub {
1260 my $c = shift;
1261 # Prepare body
1263 my $body = 'Hello World!';
1264 $c->res->headers->content_length(length $body);
1265 # Start writing directly with a drain callback
1267 my $drain;
1268 $drain = sub {
1269 my $c = shift;
1270 my $chunk = substr $body, 0, 1, '';
1271 $drain = undef unless length $body;
1272 $c->write($chunk, $drain);
1273 };
1274 $c->$drain;
1275 };
1276 app->start;
1278 The drain callback will be executed whenever the entire previous chunk
1280 of data has actually been written.
1281 HTTP/1.1 200 OK
1283 Date: Sat, 13 Sep 2014 16:48:29 GMT
1284 Content-Length: 12
1285 Server: Mojolicious (Perl)
1286 Hello World!
1288 Instead of providing a "Content-Length" header you can also call
1290 "finish" in Mojolicious::Controller and close the connection manually
1291 once you are done.
1292 use Mojolicious::Lite;
1294 get '/' => sub {
1296 my $c = shift;
1297 # Prepare body
1299 my $body = 'Hello World!';
1300 # Start writing directly with a drain callback
1302 my $drain;
1303 $drain = sub {
1304 my $c = shift;
1305 my $chunk = substr $body, 0, 1, '';
1306 length $chunk ? $c->write($chunk, $drain) : $c->finish;
1307 };
1308 $c->$drain;
1309 };
1310 app->start;
1312 While this is rather inefficient, as it prevents keep-alive, it is
1314 sometimes necessary for EventSource and similar applications.
1315 HTTP/1.1 200 OK
1317 Date: Sat, 13 Sep 2014 16:48:29 GMT
1318 Connection: close
1319 Server: Mojolicious (Perl)
1320 Hello World!
1322 Chunked transfer encoding
1324 For very dynamic content you might not know the response content length
1325 in advance, that's where the chunked transfer encoding and
1326 "write_chunk" in Mojolicious::Controller come in handy. A common use
1327 would be to send the "head" section of an HTML document to the browser
1328 in advance and speed up preloading of referenced images and
1329 stylesheets.
1330 use Mojolicious::Lite;
1332 get '/' => sub {
1334 my $c = shift;
1335 $c->write_chunk('<html><head><title>Example</title></head>' => sub {
1336 my $c = shift;
1337 $c->finish('<body>Example</body></html>');
1338 });
1339 };
1340 app->start;
1342 The optional drain callback ensures that all previous chunks have been
1344 written before processing continues. To end the stream you can call
1345 "finish" in Mojolicious::Controller or write an empty chunk of data.
1346 HTTP/1.1 200 OK
1348 Date: Sat, 13 Sep 2014 16:48:29 GMT
1349 Transfer-Encoding: chunked
1350 Server: Mojolicious (Perl)
1351 29
1353 <html><head><title>Example</title></head>
1354 1b
1355 <body>Example</body></html>
1356 0
1357 Especially in combination with long inactivity timeouts this can be
1359 very useful for Comet (long polling). Due to limitations in some web
1360 servers this might not work perfectly in all deployment environments.
1361 Encoding
1363 Templates stored in files are expected to be "UTF-8" by default, but
1364 that can be easily changed with "encoding" in Mojolicious::Renderer.
1365 $app->renderer->encoding('koi8-r');
1367 All templates from the "DATA" section are bound to the encoding of the
1369 Perl script.
1370 use Mojolicious::Lite;
1372 get '/heart';
1374 app->start;
1376 __DATA__
1377 @@ heart.html.ep
1379 I ♥ Mojolicious!
1380 Base64 encoded DATA files
1382 Base64 encoded static files such as images can be easily stored in the
1383 "DATA" section of your application, similar to templates.
1384 use Mojolicious::Lite;
1386 get '/' => {text => 'I ♥ Mojolicious!'};
1388 app->start;
1390 __DATA__
1391 @@ favicon.ico (base64)
1393 ...base64 encoded image...
1394 Inflating DATA templates
1396 Templates stored in files get preferred over files from the "DATA"
1397 section, this allows you to include a default set of templates in your
1398 application that the user can later customize. The command
1399 Mojolicious::Command::Author::inflate will write all templates and
1400 static files from the "DATA" section into actual files in the
1401 "templates" and "public" directories.
1402 $ ./myapp.pl inflate
1404 Customizing the template syntax
1406 You can easily change the whole template syntax by loading
1407 Mojolicious::Plugin::EPRenderer with a custom configuration.
1408 use Mojolicious::Lite;
1410 plugin EPRenderer => {
1412 name => 'mustache',
1413 template => {
1414 tag_start => '{{',
1415 tag_end => '}}'
1416 }
1417 };
1418 get '/:name' => {name => 'Anonymous'} => 'index';
1420 app->start;
1422 __DATA__
1423 @@ index.html.mustache
1425 Hello {{= $name }}.
1426 Mojo::Template contains the whole list of available options.
1428 Adding your favorite template system
1430 Maybe you would prefer a different template system than "ep", which is
1431 provided by Mojolicious::Plugin::EPRenderer, and there is not already a
1432 plugin on CPAN for your favorite one. All you have to do, is to add a
1433 new "handler" with "add_handler" in Mojolicious::Renderer when
1434 "register" is called.
1435 package Mojolicious::Plugin::MyRenderer;
1437 use Mojo::Base 'Mojolicious::Plugin';
1438 sub register {
1440 my ($self, $app) = @_;
1441 # Add "mine" handler
1443 $app->renderer->add_handler(mine => sub {
1444 my ($renderer, $c, $output, $options) = @_;
1445 # Check for one-time use inline template
1447 my $inline_template = $options->{inline};
1448 # Check for appropriate template in "templates" directories
1450 my $template_path = $renderer->template_path($options);
1451 # Check for appropriate template in DATA sections
1453 my $data_template = $renderer->get_data_template($options);
1454 # This part is up to you and your template system :)
1456 ...
1457 # Pass the rendered result back to the renderer
1459 $$output = 'Hello World!';
1460 # Or just die if an error occurs
1462 die 'Something went wrong with the template';
1463 });
1464 }
1465 1;
1467 An "inline" template, if provided by the user, will be passed along
1469 with the options. You can use "template_path" in Mojolicious::Renderer
1470 to search the "templates" directories of the application, and
1471 "get_data_template" in Mojolicious::Renderer to search the "DATA"
1472 sections.
1473 use Mojolicious::Lite;
1475 plugin 'MyRenderer';
1477 # Render an inline template
1479 get '/inline' => {inline => '...', handler => 'mine'};
1480 # Render a template from the DATA section
1482 get '/data' => {template => 'test'};
1483 app->start;
1485 __DATA__
1486 @@ test.html.mine
1488 ...
1489 Adding a handler to generate binary data
1491 By default the renderer assumes that every "handler" generates
1492 characters that need to be automatically encoded, but this can be
1493 easily disabled if you're generating bytes instead.
1494 use Mojolicious::Lite;
1496 use Storable 'nfreeze';
1497 # Add "storable" handler
1499 app->renderer->add_handler(storable => sub {
1500 my ($renderer, $c, $output, $options) = @_;
1501 # Disable automatic encoding
1503 delete $options->{encoding};
1504 # Encode data from stash value
1506 $$output = nfreeze delete $c->stash->{storable};
1507 });
1508 # Set "handler" value automatically if "storable" value is set already
1510 app->hook(before_render => sub {
1511 my ($c, $args) = @_;
1512 $args->{handler} = 'storable'
1513 if exists $args->{storable} || exists $c->stash->{storable};
1514 });
1515 get '/' => {storable => {i => '♥ mojolicious'}};
1517 app->start;
1519 The hook "before_render" in Mojolicious can be used to make stash
1521 values like "storable" special, so that they no longer require a
1522 "handler" value to be set explicitly.
1523 # Explicit "handler" value
1525 $c->render(storable => {i => '♥ mojolicious'}, handler => 'storable');
1526 # Implicit "handler" value (with "before_render" hook)
1528 $c->render(storable => {i => '♥ mojolicious'});
1529
1531 You can continue with Mojolicious::Guides now or take a look at the
1532 Mojolicious wiki <http://github.com/mojolicious/mojo/wiki>, which
1533 contains a lot more documentation and examples by many different
1534 authors.
1535
1537 If you have any questions the documentation might not yet answer, don't
1538 hesitate to ask on the mailing list
1539 <http://groups.google.com/group/mojolicious> or the official IRC
1540 channel "#mojo" on "irc.freenode.net" (chat now!
1541 <https://kiwiirc.com/nextclient/#irc://irc.freenode.net/mojo?nick=guest-?>).
1542perl v5.28.0 2018-11-01 Mojolicious::Guides::Rendering(3)