Templating组件

3.3 version
维护中的版本

Templating组件提供了构建任何类型模板系统所需之工具。

它提供了基础架构以加载模板文件,并可选地对模板改变进行监控。它还提供了基于PHP的具体模板引擎实现,并附带诸如转义、将模板分离成区块以及布局文件等工具。

安装 

你可以通过下述两种方式安装:

然后,包容vendor/autoload.php文件,以开启Composer提供的自动加载机制。否则,你的程序将无法找到这个Symfony组件的类。

用法 

PhpEngine 类是组件的入口点。它需要一个模板名称解析器 (TemplateNameParserInterface) 来把一个模板名称转换为对模板本身的引用 (TemplateReferenceInterface)。它还需要一个模板加载器 (LoaderInterface),loader使用“模板引用”来真正找到并加载模板:

1
2
3
4
5
6
7
8
9
use Symfony\Component\Templating\PhpEngine;
use Symfony\Component\Templating\TemplateNameParser;
use Symfony\Component\Templating\Loader\FilesystemLoader;
 
$loader = new FilesystemLoader(__DIR__.'/views/%name%');
 
$templating = new PhpEngine(new TemplateNameParser(), $loader);
 
echo $templating->render('hello.php', array('firstname' => 'Fabien'));

render() 方法解析了 views/hello.php 文件并且返回文本输出。 render 的第二个参数是模板要用到的一个变量数组。本例的结果将是 Hello, Fabien!

1
2
<!-- views/hello.php -->
Hello, <?php echo $firstname ?>!

模板将被缓存在引擎的内存中。这意味着如果你在相同请求下多次渲染相同模板,模板仅从文件系统中被加载一次。

$view变量 

所有通过 PhpEngine 解析的模板,你都可以访问到一个被称为 $view 的神秘变量。这个变量持有当前的 PhpEngine 实例,这意味着你可以访问到大量“可令开发变轻松”的方法。

包容模板 

共享模板码段的最佳方式,就是创建一个“能被其他模板包容”的模板。由于 $view 变量是 PhpEngine 的实例,你可以在模板中使用 render 方法 (原生用于渲染模板) 来渲染其他模板:

1
2
3
4
<?php $names = array('Fabien', ...) ?>
<?php foreach ($names as $name) : ?>
    <?php echo $view->render('hello.php', array('firstname' => $name)) ?>
<?php endforeach ?>

全局变量 

有时,你需要创建一个变量,并希望它能在引擎所渲染的所有模板中都可使用(就像Symfony框架中的 $app 变量)。 这类变量可以通过 addGlobal() 方法来设置,然后它们可以在模板中作为普通变量而被访问:

1
$templating->addGlobal('ga_tracking', 'UA-xxxxx-x');

在模板中:

1
<p>The google tracking code is: <?php echo $ga_tracking ?></p>

全局模板变量不可以命名为 thisview,因为它们已被PHP引擎用到。

全局模板变量可以在模板中被同名变量覆写。

输出转义 

当你输出变量时,可能会将其转义,以便HTML或JavaScript不被写到页面中。这可以防止像是XSS攻击这种事情。要这样做,使用 escape() 方法:

1
<?php echo $view->escape($firstname) ?>

默认时,escape() 方法假设变量被输出到HTML上下文中。第二个参数允许你改变上下文关系。例如,在JavaScript中对某些输出进行转义,使用 js 上下文。

1
<?php echo $view->escape($var, 'js') ?>

模板组件内置了HTML和JS转义器。你可以注册你自己escaper,使用 setEscaper() 方法即可:

1
2
3
4
5
$templating->setEscaper('css', function ($value) {
    // ... all CSS escaping / 所有的CSS转义内容
 
    return $escapedValue;
});

Helpers 

模板组件可以通过helpers来轻松扩展。Helpers是一个PHP对象,可在模板中提供对上下文有用的功能。本组件有一个内置的helper:

使用这些helper之前,你需要使用 set()来注册它们:

1
2
3
4
use Symfony\Component\Templating\Helper\SlotsHelper;
// ...
 
$templating->set(new SlotsHelper());

自定义Helper 

通过创建一个实现 HelperInterface 接口的类,你可以创建自己的helpers。然而,多数时候你只需继承 Helper 即可。

Helper 有一个必须的方法: getName()。这是通过 $view 对象取得helper时所要用到的名称。

创建自定义引擎 

本组件除了提供一个PHP模板引擎之外,你也可以利用组件创建自己的引擎。要实现这个,创建一个新类去实现 EngineInterface 接口。有三个必须填实的方法:

使用多个引擎 

使用 DelegatingEngine 类可令同时使用多个引擎成为可能。这个类接收一个引擎列表,像普通引擎那样运作。唯一的区别是,它把调用委托给其中的一个引擎。要选择将哪个引擎用于模板,会用到 EngineInterface::supports() 方法:

1
2
3
4
5
6
7
8
use Acme\Templating\CustomEngine;
use Symfony\Component\Templating\PhpEngine;
use Symfony\Component\Templating\DelegatingEngine;
 
$templating = new DelegatingEngine(array(
    new PhpEngine(...),
    new CustomEngine(...),
));

本文,包括例程代码在内,采用的是 Creative Commons BY-SA 3.0 创作共用授权。

登录symfonychina 发表评论或留下问题(我们会尽量回复)