Руководство по рендерингу в Perl-фреймворке Mojolicious |
- Statistics
- Participants
- Translate into Russian
- Translation result
- Translation complete.
# Copyright (C) 2008—2010, Sebastian Riedel.
=encoding utf8
=head1 НАЗВАНИЕ
Mojolicious::Guides::Rendering — Рендеринг
=head1 ОБЗОР
Генерация контента, используя механизм рендеринга L<Mojolicious>
=head1 ОСНОВНЫЕ ИДЕИ
Основное, что должен знать каждый разработчик на L<Mojolicious>.
=head2 Рендерер
Рендерер - это крошечный черный ящик, преобразующий данные приложения
в реальный ответ. При этом используются различные системы шаблонов и модули кодирования данных.
{text => 'Привет!'} -> 200 OK, text/plain, 'Привет!'
{json => {x => 3}} -> 200 OK, application/json, '{"x":3}'
{text => 'Ой!', status => '410'} -> 410 Gone, text/plain, 'Ой!'
Шаблон может быть выбран автоматически, если для этого разрабочиком либо маршрутом предоставлено достаточно информации.
Наименование шаблона должно соответствовать следующему формату C<имя_шаблона.формат.обработчик> (C<name.format.handler>), где C<name> по умолчанию соответствует C<controller/action> или имени маршрута, C<format> по умолчанию соответствует C<html>,
C<handler> по умолчанию соответствует C<ep>.
{controller => 'users', action => 'list'} -> 'users/list.html.ep'
{route => 'foo', format => 'txt'} -> 'foo.txt.ep'
{route => 'foo', handler => 'epl'} -> 'foo.html.epl'
Все шаблоны должны быть размещены в директории C<templates> приложения или в секции C<DATA> класса C<main>.
__DATA__
@@ time.html.ep
<!doctype html><html>
<head><title>Время</title></head>
<body><%= localtime time %></body>
</html>
@@ hello.txt.ep
Рендерер может быть легко расширен для поддержки дополнительных шаблонизаторов,
с помощью расширений, но об этом позже.
=head2 Embedded Perl
L<Mojolicious> изначально включает простую, но очень мощную систему шаблонов, называемую Embedded Perl или C<ep> для краткости.
Это позволяет встраивать код на Perl прямо в содержимое, используя небольшой набор специальных меток и символов начала строки.
<% Строчный Perl %>
<%= Выражение Perl, заменяемое результатом с XML экранированием %>
<%== Выражение Perl, заменяемое результатом без какой-либо обработки %>
<%# Комментарий, полезно для отладки %>
% Строка Perl
%= Строка выражения Perl, заменяемое результатом с XML экранированием
%== Строка выражения Perl, заменяемое результатом без какой-либо обработки
%# Строка комментария, полезно для отладки
Для вставки Perl кода используется простейший способ.
Теги и строки работают одинаково, но в зависимости от контекста что-то будет выглядеть лучше.
<% my $i = 10; %>
Текст до цикла
<% for (1 .. $i) { %>
Вставить этот текст 10 раз!
<% } %>
Текст после цикла
% my $i = 10;
Текст до цикла
% for (1 .. $i) {
Вставить этот текст 10 раз!
% }
Текст после цикла
Вы также можете вставлять результаты выполнения Perl-кода, используя выражения. По умолчанию символы C<E<lt>>, C<E<gt>>, C<&>, C<'> и C<"> будут экранированы, чтобы предотвратить XSS-атаки на ваше приложение. Ко всем выражениям автоматически будут добавлены точки с запятой.
<%= 'lalala' %>
<%== '<p>test</p>' %>
Только объекты L<Mojo::ByteStream> не экранируются автоматически.
<%= Mojo::ByteStream->new('<p>Тест!</p>') %>
Вы также можете добавить дополнительный знак '=' в конец тега, чтобы автоматически удалить все лишние пробелы в начале и конце, это позволяет делать отступы, не портя результат.
<% for (1 .. 3) { %>
<%= $foo =%>
<% } %>
Теги комментариев очень полезны для исключения некоторого кода в целях отладки.
% my $foo = 'lalala';
<%# if ($foo) { %>
<%= $foo =%>
<%# } %>
Значения stash, которые не содержат недопустимых символов в своих именах, автоматически инициализируются как обычные переменные в шаблоне, а экземпляр контроллера как C<$self>.
$r->route('/foo/:name')
->to(controller => 'foo', action => 'bar', name => 'tester');
Привет <%= $name %>.
Есть также множество встроенных вспомогательных функций, таких как C<url_for>, которые позволяют создавать URL определенного маршрута по его имени.
$r->route('/foo/:name')->to('foo#bar')->name('some_route');
<%= url_for 'some_route' %>
=head1 ОСНОВЫ
Самые часто используемые возможности, которые каждый L<Mojolicious>-разработчик должен знать.
=head2 Автоматический рендеринг
Рендеринг может быть инициирован "вручную", вызовом метода C<render> контроллера, но обычно в этом нет необходимости, потому что рендеринг произойдет автоматически если ничего не будет отображено после того как диспетчер роутов завершит свою работу. Это так же означает, что можно создать маршрут, указывающий только на шаблон, минуя действие контроллера.
$self->render;
Однако есть одна большая разница: вызывая C<render> вручную, можно быть уверенным, что будет использоваться текущий экземпляр контроллера, а не контроллер по умолчанию, определенный атрибутом C<controller_class> в классе приложения.
=head2 Рендеринг Шаблонов (C<template>)
Рендерер всегда будет пытаться автоматически определить нужный шаблон, но вы можете определить в stash значение C<template> чтобы обработать указанный вами шаблон.
$self->render(template => 'foo');
Выбор соответствующего формата C<format> и обработчика C<handler> очень прост.
$self->render(template => 'foo', format => 'txt', handler => 'epl');
Поскольку обработка шаблона - часто используемая задача, она так же имеет сокращенную запись.
$self->render('foo');
Все значения, переданные при вызове C<render>, пишутся в stash временно и сбрасываются после окончания обработки.
=head2 Рендеринг Текста (C<text>)
Обычный текст можно обработать с помощью stash значения C<text>, символы будут автоматически перекодированы в байты.
$self->render(text => 'Hello Wörld!');
=head2 Рендеринг Данных (C<data>)
Бинарные данные можно обрабтаывать с помощью stash значения C<data>, перекодирование в этом случае не производится.
$self->render(data => $octets);
=head2 Формирование JSON (C<json>)
Значение stash C<json> позволяет передавать рендереру структуры данных Perl, которые будут преобразованы непосредственно в JSON.
$self->render(json => {foo => [1, 'test', 3]});
=head2 Частичный рендеринг (C<partial>)
Иногда вам может понадобиться получить результат рендеринга, например для создания сообщений электронной почты. Это можно сделать с помощью значения stash C<partial>.
my $html = $self->render('mail', partial => 1);
=head2 Код Ответа (C<status>)
Возвращаемые коды ответа могут быть изменены посредством stash-ключа C<status>
$self->render(text => 'Oops!', status => 500);
=head2 Тип содержимого (Content Type) (C<format>)
Заголовок C<Content-Type> в ответе создается на основе соответствия MIME-типа, указанного в stash значении C<format>.
$self->render(text => 'Hello!', format => 'txt');
Эти соответствия могут быть расширены или изменены.
# Application
package MyApp;
use base 'Mojolicious';
sub startup {
my $self = shift;
# Добавляем новый MIME-тип
$self->types->type(txt => 'text/plain; charset=utf-8');
}
1;
=head2 Вспомогательные функции
Вспомогательные функции - это небольшие функции, хранящиеся в рендерере, не все из них непосредственно относятся к шаблонам, поэтому вы можете использовать контроллер C<helper> для их вызова.
<%= dumper [1, 2, 3] %>
my $serialized = $self->helper(dumper => [1, 2, 3]);
Вспомогательная функция C<dumper> будет использовать L<Data::Dumper> для сериализации переданной структуры данных, это может очень пригодиться при отладке.
Мы разделяем C<default helpers>, имеющих более общее назначение, как C<dumper> и специфичных для шаблонов C<tag helpers> в основном использующихся для генерации C<HTML> тэгов.
<%= script '/script.js' %>
<%= script {%>
var a = 'b';
<%}%>
Все эти вспомогательные функции содержатся в плагинах L<Mojolicious::Plugin::DefaultHelpers> и
L<Mojolicious::Plugin::TagHelpers>.
=head2 Макеты разметки
В большинстве случаев при использовании C<ep> шаблонов вы захотите поместить ваш генерируемый контент в HTML-"обертку", благодаря макетам разметки это делается очень просто.
@@ foo/bar.html.ep
% layout 'mylayout';
Mojolicious is cool!
@@ layouts/mylayout.html.ep
<!doctype html><html>
<head><title>Hello Best Perl Framework!</title></head>
<body><%= content %></body>
</html>
Выбираем шаблон макета разметки используя вспомогательную функцию C<layout> и просто размещаем содержимое текущего шаблона используя вспомогательную функцию C<content>.
Вы можете также передавать вспомогательной функции C<layout> обычные stash значения.
@@ foo/bar.html.ep
% layout 'mylayout', title => 'Привет!';
Hello World!
@@ layouts/mylayout.html.ep
<!doctype html><html>
<head><title><%= $title %></title></head>
<body><%= content %></body>
</html>
=head2 Включение составных шаблонов
Как и большинство вспомогательных функций C<include> это просто сокращение, которое сделает вашу жизнь немного проще.
@@ foo/bar.html.ep
<!doctype html><html>
<%= include 'header' %>
<body>Bar!</body>
</html>
@@ header.html.ep
<head><title>Здорово!</title></head>
Вместо C<include> можно также вызывать C<render> с аргументом C<partial>.
@@ foo/bar.html.ep
<!doctype html><html>
<%= $self->render('header', partial => 1) %>
<body>Bar!</body>
</html>
@@ header.html.ep
<head><title>Здорово!</title></head>
Конечно, можно передавать также и значения stash.
@@ foo/bar.html.ep
<!doctype html><html>
<%= include 'header', title => 'Привет!' %>
<body>Бар!</body>
</html>
@@ header.html.ep
<head><title><%= $title %></title></head>
=head2 Повторно используемые блоки шаблонов
