Mojolicious::Renderer

简介

use Mojolicious::Renderer;

my $renderer = Mojolicious::Renderer->new;
push @{$renderer->classes}, 'MyApp::Controller::Foo';
push @{$renderer->paths}, '/home/sri/templates';

Mojolicious::Renderer是标准的Mojolicious渲染器。

属性

Mojolicious::Renderer中实现了以下属性。

cache

my $cache = $renderer->cache;
$renderer = $renderer->cache(Mojo::Cache->new);

Renderer缓存，默认为Mojo::Cache对象。

classes

my $classes = $renderer->classes;
$renderer   = $renderer->classes(['main']);

此包的warmup方法使用Mojo::Loader在一个类的DATA段中查找模板时会用到这个属性。放在前面的值会有更高的优先级，默认值为 main。只有使用两个扩展名的文件才会被提取出来，如index.html.ep。

注意：需要自动检测的模板以及他们所在的包需要在warmup方法被调用之前已经加载完成，通常情况下这是在应用程序启动时自动完成的。

# Add another class with templates in DATA section
push @{$renderer->classes}, 'Mojolicious::Plugin::Fun';
 
# Add another class with templates in DATA section and higher precedence
unshift @{$renderer->classes}, 'Mojolicious::Plugin::MoreFun';

default_format

my $default = $renderer->default_format;
$renderer   = $renderer->default_format('html');

如果在隐藏的参数中没有设置format，则使用这个值作为默认format。默认值为html。

default_handler

my $default = $renderer->default_handler;
$renderer   = $renderer->default_handler('ep');

在自动检测失败的情况下，用于渲染的默认模板处理程序，如inline模板。

encoding

my $encoding = $renderer->encoding;
$renderer    = $renderer->encoding('koi8-r');

如果设置了这个属性，则会用它来编码生成的内容。默认值为utf-8。

注：很多渲染器（如：Mojolicious::Plugin::EPRenderer）也使用这个值来判断模板文件在被渲染器处理之前是否被解码了。

handlers

my $handlers = $renderer->handlers;
$renderer    = $renderer->handlers({epl => sub {...}});

获取或设置处理程序。
handlers属性的值其实是一个HASH对象。这个HASH对象的key对应于Controller包render方法中的handler参数，而value则是一个针对handler参数所指定渲染格式的渲染程序。方法接收的参数顺序如下：

$handler->($renderer, $controller, $output, $options);
## $renderer 是当前的渲染器 
## $controller 是当前的控制器
## $output 就是最终要输出到 response 中的内容的 引用。 
## 上面方法中option的结构如下：
$options={
    encoding => $renderer->encoding,
    handler  => $controller->stash->{handler},
    template => delete $controller->stash->{template},
    variant  => $controller->stash->{variant}
}

helpers

my $helpers = $renderer->helpers;
$renderer   = $renderer->helpers({url_for => sub {...}});

获取或设置 helpers。
helpers属性也是一个HASH对象，其key可以作为方法名在Controller或ep模板中直接调用。其value就是被调用的实际方法。

paths

my $paths = $renderer->paths;
$renderer = $renderer->paths(['/home/sri/templates']);

此包中的warmup方法会在这个属性中存储的目录中查找模板，放在前面的值具有更高的优先级。

# Add another "templates" directory
push @{$renderer->paths}, '/home/sri/templates';

# Add another "templates" directory with higher precedence
unshift @{$renderer->paths}, '/home/sri/themes/blue/templates';

方法

Mojolicious::Renderer继承了Mojo::Base中的所有方法，并实现了以下方法。

accepts

my $all  = $renderer->accepts(Mojolicious::Controller->new);
my $best = $renderer->accepts(Mojolicious::Controller->new, 'html', 'json');

从Accept请求头、隐藏的format参数、或GET/POST中的format参数为Mojolicious::Controller选择一个最优的响应类型。如果不能检测到，则默认返回第一个扩展名。由于浏览器不会真正知道他们实际想要的是什么，所以在允许多种MIME类型的非特定的请求头Accept会被忽略，除非你使用X-Requested-With请求头在XMLHttpRequest类型的请求中进行了说明。

add_handler

$renderer = $renderer->add_handler(epl => sub {...});

注册一个处理程序

$renderer->add_handler(foo => sub {
  my ($renderer, $c, $output, $options) = @_;
  ...
  $$output = 'Hello World!';
});

add_helper

$renderer = $renderer->add_helper(url_for => sub {...});

注册一个帮手

$renderer->add_helper(foo => sub {
  my ($c, @args) = @_;
  ...
});

get_data_template

my $template = $renderer->get_data_template({
  template       => 'foo/bar',
  format         => 'html',
  handler        => 'epl'
});

返回一个从classes中的DATA段中获取的模板。如果没有找到则返回undef。参数是一个hashref，可用的键名如下：template，format，variant和handler，其中handler用来指定模板的处理程序。

get_helper

my $helper = $renderer->get_helper('url_for');

用“全名”从已经注册的helpers属性中获取一个helper，或者用前缀生成一个helper，如果没有找到则返回undef。用前缀生成的helper被调用后，会返回一个包含当前调用者（也就是调用时传递的第一个参数，一般情况下应该传一个当前控制器）对象的代理对象，并且可以这个代理对象上调用“前缀”匹配到的所有helpers。

render

my ($output, $format) = $renderer->render(Mojolicious::Controller->new, {
  template => 'foo/bar',
  foo      => 'bar'
});

使用一个渲染器进行渲染输出。请参阅Mojolicious::Controller中的render方法。

template_for

my $name = $renderer->template_for(Mojolicious::Controller->new);

返回Mojolicious::Controller对象的默认模板名称，如果找不到则返回undef。

template_handler

my $handler = $renderer->template_handler({
  template => 'foo/bar',
  format   => 'html'
});

传递一个包含template、format 和 variant 键的hashref作为参数，返回一个最佳的处理器名。

template_name

my $template = $renderer->template_name({
  template => 'foo/bar',
  format   => 'html',
  handler  => 'epl'
});

传递一个包含template、format 、 variant 和 handler 键的hashref作为参数，返回一个可用的模板名。

template_path

my $path = $renderer->template_path({
  template => 'foo/bar',
  format   => 'html',
  handler  => 'epl'
});

传递一个包含template、format 、 variant 和 handler 键的hashref作为参数，返回一个可用模板的完整路径。如果找不到则返回undef。

warmup

$renderer->warmup;

从 classes 和 paths 中准备模板，以备将来使用。