1. 概要
模板是一个简单的文本文件。它可以生成任何基于文本的格式(HTML、XML、CSV等)。它不具有特定扩展名,html或xml都OK。 模板中包含的变量或表达式,用来控制模板的逻辑。当模版被预处理时,它们会被替换为变量值。
下面是说明了一些基本要素的最小模板。稍后我们将介绍更多细节:
<!DOCTYPE html> <html> <head> <title>My Webpage</title> </head> <body> <ul id="navigation"> {% for item in navigation %} <li><a href="{{ item.href }}">{{ item.caption }}</a></li> {% endfor %} </ul> <h1>My Webpage</h1> {{ a_variable }} </body> </html>
Twig有两种类型的分隔符:{%...%} 和 {{...}} 。第一个是用于执行诸如for循环的控制语句,后者则在模板中打印一个表达式的结果。
2. IDEs 集成
许多IDE支持Twig语法高亮和自动完成标签:
※ TextMate 通过 Twig Bundle
※ Vim 通过 Jinja syntax 插件 或 vim-twig 插件
※ NetBeans 通过 Twig syntax 插件(7.2+)
※ PhpStorm(原生2.1+)
※ Eclipse 通过 Twig plugin
※ Sublime 通过 Twig bundle
※ GtkSourceView 通过 Twig language definition
※ Coda and SubEthaEdit 通过 Twig syntax mode
※ Coda 2 通过 other Twig syntax mode
※ Komodo and Komodo Edit 通过 Twig highlight/syntax check mode
※ Notepad++ 通过 Notepad++ Twig Highlighter
※ Emacs 通过 web-mode.el
3. 变量
应用程序将变量传递到操作的模板中。你也可以访问变量的属性或元素。一个变量的可视化表示在很大程度上依赖于应用程序提供的值。你可以使用点(.)或所谓的下标语法([])来访问变量的属性(PHP对象的方法或属性,PHP数组的元素)。
{{ foo.bar }} {{ foo[‘bar‘] }}
当属性中包含特殊字符(如 - 这会被解释为减号操作符),使用attribute()函数来替代使用点(.)访问变量属性:
{# equivalent to the non-working foo.data-foo #} {{ attribute(foo, ‘data-foo‘) }}
重要提示:要知道,大括号不是变量的一部分,print语句除外。当访问标签内的变量,不要把大括号加在变量上。
如果一个变量或属性不存在,strict_variables选项设置为false时,您将收到一个空值;另外,如果strict_variables设置为true,Twig将会抛出一个错误(参照见 environment options)
变量调用机制
为了方便起见,在PHP表现层调用foo.bar时,会进行以下操作:
a.1 检查foo是否是个数组,并检查bar是否是有效的元素 a.2 如果不是,foo是个对象,并检查bar是否是有效的属性 a.3 如果不是,foo是个对象,并检查bar是否是有效方法。(即使bar是一个构造器。那么请使用__construct()方法替代 a.4 如果不是,foo是个对象,会检查getBar()是否是有效的方法 a.5 如果不是,foo是个对象,会检查isBar()是否是有效的方法 a.6 如果不是,返回空值(null) a.7 检查foo是一个数组和bar是一个有效的元素; a.8 如果没有,则返回null值。
4. 全局变量
下面的变量在模板中总是可用:
_self: 引用当前模版;
_context: 引用当前的上下文;
_charset: 引用当前的字符集。
5. 设置变量
您可以将值赋给内部代码块中的变量。赋值使用 set 标签:
{% set foo = ‘foo‘ %} {% set foo = [1, 2] %} {% set foo = {‘foo‘: ‘bar‘} %}
6. 过滤器
变量可以通过过滤器进行修改。过滤器和变量之间使用管道符号(也就是竖线 | )分隔开,过滤器括号中可能有可选的参数。多个过滤器可以串连使用,滤波器的输出会被应用于下一个过滤器。
下面的示例是从名称中删除所有的HTML标签并应用title-cases格式化:
{{ name|striptags|title }}
过滤器接受括号中的参数。 这个例子将用逗号连接一个列表:
{{ list|join(‘, ‘) }}
要对一段代码应用过滤器,只要使用 filter 标签把它包起来:
{% filter upper %} This text becomes uppercase {% endfilter %}
访问 Filters 页面,以了解更多关于内置过滤器。
7. 函数
函数可以被调用来生成内容。函数是通过它们的[函数名+()]进行调用的,可能还带有参数。
例如,range()函数返回一个包含一个整数等差数列的列表:
{% for i in range(0, 3) %} {{ i }}, {% endfor %}
访问 Functions 页面,以了解更多关于内置函数。
8. 命名参数
1.12版本新特性:对命名参数的支持被添加到Twig 1.12版。
{% for i in range(low=1, high=10, step=2) %} {{ i }}, {% endfor %}
使用命名参数,让你的模板更明确的了解,您作为参数传递的值的含义:
{{ data|convert_encoding(‘UTF-8‘, ‘iso-2022-jp‘) }} {# versus (对比) #} {{ data|convert_encoding(from=‘iso-2022-jp‘, to=‘UTF-8‘) }}
命名参数还允许您跳过一些你不希望更改默认值的参数:
{# the first argument is the date format, which defaults to the global date format if null is passed #} {{ "now"|date(null, "Europe/Paris") }} {# or skip the format value by using a named argument for the time zone #} {{ "now"|date(timezone="Europe/Paris") }}
您也可以在一个调用中使用占位参数和命名参数,在这种情况下,占位参数必须在命名参数之前:
{{ "now"|date(‘d/m/Y H:i‘, timezone="Europe/Paris") }}
提示:每个函数和过滤器的文档页面,都有一段内容,列出它们支持的所有参数名称。
9. 控制结构
控制结构指的是所有这些控制程序流程的代码:条件语句(如:if/elseif/else)、for循环以及类似的代码块。控制结构出现在{%...%}块内。
例如,要显示一个由变量(users)提供的用户列表,使用 for 标签:
<h1>Members</h1> <ul> {% for user in users %} <li>{{ user.username|e }}</li> {% endfor %} </ul>
if 标签可以用于测试表达式:
{% if users|length > 0 %} <ul> {% for user in users %} <li>{{ user.username|e }}</li> {% endfor %} </ul> {% endif %}
访问 tags 页面,以了解更多关于内置标签。
10. 注释
要在模板中注释掉一部分,使用注释语法{#...#}。这对于调试或添加信息给其他模板设计者或自己看会很有用:
{# note: disabled template because we no longer use this {% for user in users %} ... {% endfor %} #}
11. 包含其他模板
包含一个模板时,include标签很有用,它会返回该模板(子模版)的内容呈现到当前模版(父模版):
{% include ‘sidebar.html‘ %}
默认情况下每个被包含的模板都会传递当前上下文(context)。传递给父模板的上下文,还包括在子模板中定义的变量:
{% for box in boxes %} {% include "render_box.html" %} {% endfor %}
被包含的模板 render_box.html 能够访问变量 box。
模板的文件名取决于模板加载器。例如,Twig_Loader_Filesystem 允许你通过给文件名来访问其他模板。您可以访问以斜线分隔的子目录中的模板:
{% include "sections/articles/sidebar.html" %}
此行为取决于应用程序中嵌入Twig。