创建和使用模板 - Symfony开源 - Symfony中国

link管理

链接快照平台

输入网页链接，自动生成快照
标签化管理网页链接

模板 ¶

模板就是生成基于文本格式（html,xml,csv,LaTex…）的任何文本文件。我们最熟悉的模板类型就是 PHP 模板——包含文字和PHP代码的被PHP引擎解析的文本文件：

<!DOCTYPE html>
        <title>Welcome to Symfony!</title>
    </head>
        <h1><?php echo $page_title ?></h1>
        <ul id="navigation">
            <?php foreach ($navigation as $item); ?>
                    <a href="<?php echo $item->getHref(); ?>">
                        <?php echo $item->getCaption(); ?>
            <?php endforeach; ?>
    </body>
</html>

但是，symfony 框架中有一个更强大的模板语言叫作Twig。Twig可令你写出简明易读且对设计师友好的模板，在几个方面比PHP模板强大许多。

<!DOCTYPE html>
        <title>Welcome to Symfony!</title>
    </head>
        <h1>{{ page_title }}</h1>
        <ul id="navigation">
            {% for item in navigation %}
                <li><a href="{{ item.href }}">{{ item.caption }}</a></li>
            {% endfor %}
    </body>
</html>

Twig定义了三种特殊的语法：


    {{ ... }}

“说些什么”：输出一个变量值或者一个表达式的结果到模板。


    {% ... %}

“做些什么”：控制模板逻辑的*tag（标签）*，用于执行声明，如for循环语句等。


    {# ... #}

“进行注释”：它相当于PHP的


    /* comment */

语法。它用于注释单行和多行。注释的内容不作为页面输出。

Twig也包含 filters ，它可以在模板输出之前改变输出内容。下例让title变量在被输出之前全部大写：

{{ title|upper }}

Twig内置了大量的标签( tags )和变量调节器（ filters )，默认就可以使用。你甚至可以利用 Twig扩展来添加你自己的 自定义 调节器和函数（乃至更多）。

Twig代码很像PHP代码，两者有微妙的区别。下例使用了一个标准的 for 标签和 cycle 函数来输出10个div 标签，用 odd 、 even css类交替显示。

{% for i in 0..10 %}
    <div class="{{ cycle(['odd', 'even'], i) }}">
      <!-- some HTML here -->
{% endfor %}

本章的模板例程，将同时使用Twig和PHP来展示。

为什么使用Twig？

Twig模板就是为了简单而不去处理PHP标签。设计上即是如此：Twig模板只负责呈现，而不去考虑逻辑。你用Twig越多，你就越会欣赏它，并从它的特性中受益。当然，你也会被普天下的网页设计者喜欢。

还有很多Twig可以做但是PHP不可以的事，如空格控制、沙盒、自动html转义、手动上下文输出转义，以及包容“只会影响模板”的自定义函数和调节器。Twig包含一些小功能，使得写模板时更加方便快捷。请看下例，它结合了逻辑循环和 if 语句：

{ % for user in users if user .active % } <li> { { user .username } } </li> { % else % } <li>No users found</li> { % endfor % }

Twig模板缓存 ¶

Twig超快的原因是，Twig模板被编译成原生PHP类并且缓存起来。不用担心，这一切自动完成，毋须你做任何事。而且在开发时，当你做出任何改变时，Twig足够智能地重新编译你的模板。这意味着，Twig在产品环境下极快，在开发环境却极易使用。

模板继承和布局 ¶

大多数的时候，模板在项目中都有通用的元素，比如header，footer，sidebar等等。在Symfony中，我们将采用不同的思考角度来对待这个问题。一个模板可以被另外的模板装饰。这个的工作原理跟PHP类非常像，模板继承让你可以创建一个基础“layout”模板，它包含你的站点所有通用元素，并被定义成 blocks （如同一个“包含基础方法的PHP基类”）。一个子模板可以继承layout基础模板并覆写它的任何一个block（就像“PHP子类覆写父类中的特定方法”）。

首先创建一个layout基础文件：

Twig
PHP

该模板定义了一个简单的两列式html页面。在本例中，三处 {% block %} 区域被定义了（即 title ， sidebar 和 body ）。每个block都可以被继承它的子模板覆写，或者保留现在这种默认实现。该模板也能被直接输出。只不过此时只是显示基础模板所定义的内容， title , sidebar 和 body 都将保持默认值。

一个子模板看起来是这样的：

Twig
PHP

{ % extends 'base.html.twig' % } { % block title % } My cool blog posts { % endblock % } { % block body % } { % for entry in blog_entries % } <h2> { { entry . title } } </h2> <p> { { entry .body } } </p> { % endfor % } { % endblock % }

<!-- app/Resources/views/blog/index.html.php -->
<?php $view->extend('base.html.php') ?>
<?php $view['slots']->set('title', 'My cool blog posts') ?>
<?php $view['slots']->start('body') ?>
    <?php foreach ($blog_entries as $entry): ?>
        <h2><?php echo $entry->getTitle() ?></h2>
        <p><?php echo $entry->getBody() ?></p>
    <?php endforeach ?>
<?php $view['slots']->stop() ?>

模板继承的关键字是 {% extends %} 标签。该标签告诉模板引擎首先评估父模板，它设置了布局并定义了若干blocks。然后子模板被输出，上例中父模板中定义的 title 和 body 两个blocks将会被子模板中的同名区块内容所取代。根据 blog_entries 的取值，输出的内容可能像下面这样：

<!DOCTYPE html>
        <meta charset="UTF-8">
        <title>My cool blog posts</title>
    </head>
        <div id="sidebar">
                <li><a href="/">Home</a></li>
                <li><a href="/blog">Blog</a></li>
        </div>
        <div id="content">
            <h2>My first post</h2>
            <p>The body of the first post.</p>
            <h2>Another post</h2>
            <p>The body of the second post.</p>
        </div>
    </body>
</html>

注意，由于子模板中没有定义 sidebar 这个block，来自父模板的内容将被显示出来。父模板中的 {% block %} 标签内的内容，始终作为默认值来用。

你可以进行任意多个层级的模板继承。Symfony项目中一般使用“三级继承”模式，来组织模板和页面，参考如何使用继承来组织你的Twig模板。

使用模板继承时，需要注意：

如果在模板中使用 {% extends %} ，它必须是模板中的第一个标签。

你的基础（布局）模板中的 {% block %} 标签越多越好，记得，子模板不必定义父模板中的所有block。基础模板中的block定义得愈多，你的布局就愈灵活。

如果你发现在多个模板中有重复的内容，这可能意味着你需要为该内容在父模板中定义一个 {% block %} 了。某些情况下，更好的解决方案可能是把这些内容放到一个新模板中，然后在该模板中 include 它。(查看下文的：包容其他模板 )

如果你需要从父模板中获取一个block的内容，可以使用 {{ parent() }} 函数。如果你只是想在父级块上添加新内容，而不是完全覆盖它，这很有用：

{% block sidebar %}
    <h3>Table of Contents</h3>
    {# ... #}
    {{ parent() }}
{% endblock %}

模板的命名和存放位置 ¶

默认情况下，模板可以存放在两个不同的位置：

app/Resources/views

程序级的views目录可以存放整个程序的基础模板（程序布局和bundle模板），以及那些“用于覆写第三方bundle的模板”的模板（如何覆写三方bundle的模板）。

path/to/bundle/Resources/views

每个第三方bundle的模板都会存放于它自己的 Resources/views/ 目录（或者子目录）下。当你打算共享你的bundle时，你应该把它放在bundle中，而不是 app/ 目录。

更多时候你要用到的模板是在 app/Resources/views/ 目录下。你需要的模板路径是相对于这个目录的。例如，去输出/继承 app/Resources/views/base.html.twig ，你需要使用 base.html.twig 的路径，而要输出 app/Resources/views/blog/index.html.twig 时，你需要使用 blog/index.html.twig 路径。

从Bundle中引入模板 ¶

如果你需要引入一个位于bundle中的模板，Symfony使用Twig命名空间之语法（ @BundleName/directory/filename.html.twig ）来表示。这可以表示多种类型的模板，每种都存放在一个特定路径下：


    @AcmeBlog/Blog/index.html.twig

：用于指定一个特定页面的模板。字符串分为三个部分，每个部分由冒号（

）隔开，含义如下：


    @AcmeBlog

: 这是去掉了


    Bundle

后缀的bundle名称。这个模板位于 AcmeBlogBundle (即


    src/Acme/BlogBundle

) 中;


    Blog

: ( 目录 ) 指示了模板位于


    Resources/views/

的


    Blog

子目录中;


    index.html.twig

: ( 文件名 ) 文件的真实名称是


    index.html.twig

。

假设AcmeBlogBundle位于 src/Acme/BlogBundle , 最终的路径将是： src/Acme/BlogBundle/Resources/views/Blog/index.html.twig 。


    @AcmeBlog/layout.html.twig

：这种语法指向了 AcmeBlogBundle 的父模板。由于没有了中间的“目录”部分（即


    blog

），模板应该位于 AcmeBlogBundle 的


    Resources/views/layout.html.twig

。

在如何覆写第三方bundle的模板一文中，你将了解到位于 AcmeBlogBundle 中的模板，是如何被 app/Resources/AcmeBlogBundle/views/ 目录下的同名模板所覆写的，这种方式给了我们一个有力的途径来覆写任何第三方bundle所提供的模板。

模版后缀 ¶

每个模版都有两个扩展名，用来指定格式（format）和模版引擎（engine）。

默认情况下，Symfony的任何模板都可以被写成Twig或者PHP引擎的，它由后缀( .twig 或 .php )来决定使用哪个引擎。其中后缀的前一部分( .html , .css ）表示最终生成的格式。不像引擎，它是决定symfony如何解析模板，这是一个很简单的使用策略，你可以使用HTML( index.html.twig ),XML( index.xml.twig )或任何其他格式作为输出的资源。参考如何在模版中使用不同的输出格式以了解更多。

Tags和Helpers ¶

你已经了解了模板基础，它们是如何命名的，以及如何使用模板继承等基础知识。最难的部分已经过去。接下来，我们将了解大量的可用工具，来帮我们完成常见的模板任务，比如包容其他模板，链接到一个页面或者引入图片。

Symfony框架中内置了几个特殊的Twig标签和功能函数，来帮助模板设计者简化工作。在PHP中，模板系统提供了一个可扩展的 helper 系统用于在模板上下文中提供有用的功能。

你已经看到了一些内置的Twig标签，比如( {% block %} 和 {% extends %} )等，还有PHP helper $view[‘slots’] 。现在，你将会学到更多。

引入其他模版 ¶

你经常需要在多个不同的页面中包含同一个模板或者代码片段。比如在一个“新闻文章”程序中，用于显示文章的模板代码可能会被用到正文页，或者用到一个显示“人气文章”的页面，乃至一个“最新文章”的列表页等。

当你需要复用一些PHP代码时，通常都是把这些代码放到一个PHP类或者函数中。同样在模板中你也可以这么做。通过把可复用的代码放到一个它自己的模板中，然后从其他模板中包容这个模板。首先，创建一个可复用模板如下：

Twig
PHP

{# app/Resources/views/article/article_details.html.twig #}
<h2>{{ article.title }}</h2>
<h3 class="byline">by {{ article.authorName }}</h3>
    {{ article.body }}

<!-- app/Resources/views/article/article_details.html.php -->
<h2><?php echo $article->getTitle() ?></h2>
<h3 class="byline">by <?php echo $article->getAuthorName() ?></h3>
    <?php echo $article->getBody() ?>
    {% for article in articles %}
        {{ include('article/article_details.html.twig', { 'article': article }) }}
    {% endfor %}
{% endblock %}

<!-- app/Resources/article/list.html.php -->
<?php $view->extend('layout.html.php') ?>
<?php $view['slots']->start('body') ?>
    <h1>Recent Articles</h1>
    <?php foreach ($articles as $article): ?>
        <?php echo $view->render(
            'Article/article_details.html.php',
            array('article' => $article)
    <?php endforeach ?>
<?php $view['slots']->stop() ?>

这个模板被包容时，使用了 {{ include() }} 标签。注意，模板命名要遵循相同的典型约定。在 article_details.html.twig 模板中使用 article 变量，这是我们传入模板的。本例中，你也可以完全不这样做，因为在 list.html.twig 模板中所有可用的变量也都可以在 article_details.html.twig 中使用（除非你设置 with_context 为false）。


   {'article':article}

语法是标准Twig哈希映射（hash maps）的写法（即是一个键值对数组）。如果你需要传递多个元素，可以写成


   {'foo': foo, 'bar': bar}

。

链接到页面 ¶

在你的程序中创建一个链接到其他页面，对于模板来说是再普通不过的事情了。使用 path Twig函数（或者PHP中的 router helper）基于路由配置来生成URL而非在模板中写死URL。以后，如果你想修改一个特定页面的链接，你只需要改变路由配置即可；模板将自动生成新的URL。

比如我们打算链接到“_welcome”页面，首先定义其路由配置：

use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route ; class WelcomeController extends Controller * @Route("/", name="_welcome") public function indexAction ( ) // ...

<!-- app/config/routing.yml -->
<?xml version="1.0" encoding="UTF-8" ?>
<routes xmlns="http://symfony.com/schema/routing"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/routing
        http://symfony.com/schema/routing/routing-1.0.xsd">
    <route id="_welcome" path="/">
        <default key="_controller">AppBundle:Welcome:index</default>
    </route>
</routes>

// app/config/routing.php
use Symfony\Component\Routing\Route;
use Symfony\Component\Routing\RouteCollection;
$collection = new RouteCollection();
$collection->add('_welcome', new Route('/', array(
    '_controller' => 'AppBundle:Welcome:index',
)));
return $collection;

use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route ; class ArticleController extends Controller * @Route("/article/{slug}", name="article_show") public function showAction ( $slug ) // ...

<!-- app/config/routing.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<routes xmlns="http://symfony.com/schema/routing"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/routing
        http://symfony.com/schema/routing/routing-1.0.xsd">
    <route id="article_show" path="/article/{slug}">
        <default key="_controller">AppBundle:Article:show</default>
    </route>
</routes>

// app/config/routing.php
use Symfony\Component\Routing\Route;
use Symfony\Component\Routing\RouteCollection;
$collection = new RouteCollection();
$collection->add('article_show', new Route('/article/{slug}', array(
    '_controller' => 'AppBundle:Article:show',
)));
return $collection;

这种情况下，你需要指定路由名称( article_show )以及一个 {slug} 参数。使用这个路由重新访问前面提到的 recent_list.html.twig 模板，即可正确地链接到文章。

Twig
PHP

{# app/Resources/views/article/recent_list.html.twig #}
{% for article in articles %}
    <a href="{{ path('article_show', {'slug': article.slug}) }}">
        {{ article.title }}
{% endfor %}

<!-- app/Resources/views/Article/recent_list.html.php -->
<?php foreach ($articles in $article): ?>
    <a href="<?php echo $view['router']->path('article_show', array(
        'slug' => $article->getSlug(),
    )) ?>">
        <?php echo $article->getTitle() ?>
<?php endforeach ?>

链接到Assets ¶

模板通常也需要一些图片，Javascript，样式文件和其他web资源。当然你可以写死它们的路径。比如 /images/logo.png 。但是Symfony通过Twig函数 asset() ，提供了一个更加动态的选择，。

Twig
PHP

<img src="<?php echo $view['assets']->getUrl('images/logo.png') ?>" alt="Symfony!" />
<link href="<?php echo $view['assets']->getUrl('css/blog.css') ?>" rel="stylesheet" />

asset 函数的主要目的，是让你的程序更加portable（可移动）。如果你的程序在主机根目录下(如 http://example.com )，生成的路径应该是 /images/logo.png 。但是如果你的程序位于一个子目录中(如 http://example.com/my_app ），asset路径在生成时应该带有子目录（如 /my_app/images/logo.png ）。 asset 函数负责打点这些，它根据你的程序 “是如何使用的” 而生成相应的正确路径。

asset() 函数通过 version , version_format , 以及 json_manifest_path 配置选项支持不同的“缓存击破”（cache busting）策略。

如果你需要assets资源的绝对URL，可以使用 absolute_url() Twig函数：

<img src="{{ absolute_url(asset('images/logo.png')) }}" alt="Symfony!" />

在Twig中包容样式表和Javascript ¶

每个网站中都不能完全没有样式表和javascript文件。在Symfony中，这些内容可以利用模板继承来优雅地处理。

本节教给你包容stylesheet和javaScript资源时的背后思想。Symfony支持另外一个类库叫Assetic, 它允许你在遵循这一思想时，对这些资源做更多有趣事情。参考如何使用Assetic 进行资产管理以了解更多细节。

首先在你的基础布局模板中添加两个blocks来保存你的资源，一个叫 stylesheets ，放在 head 标签里，另一个叫 javascript ，放在 body 结束标签上面一行。这些blocks将包含你整个站点所需的全部stylesheets和Javascripts。

Twig
PHP

{ % block stylesheets % } <link href=" { { asset ( 'css/main.css' ) } } " rel="stylesheet" /> { % endblock % } </head> {# ... #} { % block javascripts % } <script src=" { { asset ( 'js/main.js' ) } } "></script> { % endblock % } </body> </html> <?php $view [ 'slots' ] -> start ( 'stylesheets' ) ?> <link href=" <?php echo $view [ 'assets' ] -> getUrl ( 'css/main.css' ) ?> " rel="stylesheet" /> <?php $view [ 'slots' ] -> stop ( ) ?> </head> <?php ... ?> <?php $view [ 'slots' ] -> start ( 'javascripts' ) ?> <script src=" <?php echo $view [ 'assets' ] -> getUrl ( 'js/main.js' ) ?> "></script> <?php $view [ 'slots' ] -> stop ( ) ?> </body> </html>

这也太简单了！但如果你想从子模板中包容一个额外的stylesheet或者javascript进来该怎么办呢？比如，假设你有一个联系页面需要包容一个 contact.css 样式表，仅用在该页面上。在联系人页面的模板中，你可以这样实现:

Twig
PHP

{ { parent ( ) } } <link href=" { { asset ( 'css/contact.css' ) } } " rel="stylesheet" /> { % endblock % } {# ... #}

// app/Resources/views/contact/contact.html.twig
<?php $view->extend('base.html.php') ?>
<?php $view['slots']->start('stylesheets') ?>
    <link href="<?php echo $view['assets']->getUrl('css/contact.css') ?>" rel="stylesheet" />
<?php $view['slots']->stop() ?>

在子模板中，你只需要覆写 stylesheets block并把你新的样式表标签放到该区块里。当然，由于你只是想把它添加到父块儿的内容中（而不是真的替代它们），所以你需要先用 parent() 函数来获取基础模板中的所有 stylesheets 区块中的内容。

你也可以包容位于你bundle的 Resources/public 文件夹下的assets资源。你需要运行 php bin/console assets:install target [–symlink] 命令，它会把文件移动到（或symlink到）正确的位置（默认目标位置是“web”文件夹）。

<link href="{{ asset('bundles/acmedemo/css/contact.css') }}" rel="stylesheet" />

最终结果是，页面中同时包容了 main.css 和 contact.css 两个样式表。

引用Request,User或Session对象 ¶

Symfony在Twig中给了你一个全局的 app 变量，可以用于访问当前用户、请求以及更多对象。

参考如何在Twig中通过app变量访问到User, Request, Session和更多对象以了解细节。

输出转义 ¶

在输出任意内容时，Twig自动进行“输出转义（output escaping）”，为的是保护你免受 Cross Site Scripting (XSS)跨站攻击。

假设 description 是 I <3 this product ：

<!-- output escaping is on automatically / 自动开启了输出转义 -->
{{ description }} <!-- I &lt3 this product -->
<!-- disable output escaping with the raw filter / 使用raw调节器关闭了输出转义 -->
{{ description|raw }} <!-- I <3 this product -->

Caution

PHP模板不对内容进行自动转义。

更多细节，参考如何对模板输出进行转义。

总结 ¶

模板系统仅仅是Symfony诸多工具中的一个。它的工作很简单：让我们渲染动态的、复杂的HTML输出，它们最终被返回给用户，发送到一封邮件或其他什么东西之中。

Keep Going！ ¶

深入Symfony其余部分之前，先看一下 configuration配置系统 。