Play Framework template engine模板引擎&模板隐含变量

Play有一个高效的用来动态生成HTML, XML, JSON, 任何文本格式文档的模板系统。模板引擎使用Groovy(一种JVM平台上的动态语言)作为表达式语言。包含一个可以用来创建可重用函数的标签系统。
模板保存在app/views目录下。

模板语法:
模板文件是一个包含用来动态生成内容的占位符的文本文件。模板中的动态元素是使用Groovy语言编写的。Groovy的语法和Java很类似。
动态元素在模板执行阶段被处理。渲染后的结果被作为http响应的一部分而输出到客户端。

1
表达式:${…}

声明其是一个动态的表达式。表达式的执行结果会被插入到${…} 占位符所在的位置中。

1
标签:#{tagName /}

标签式一个模板片段,被使用是通常需要传入一些参数。如果标签只有一个参数,那么根据约定,叫它为“arg”同时, 同时参数名可以省略。

例子:
我们使用用script 标签来加载javascript文件。标签必须被关闭,要嘛直接关闭,要嘛用关闭标签关闭,如下。

1
2
#{script 'jquery.js' /}
#{script 'jquery.js'}#{/script}

如果含有多个参数的标签名,参数名不能省略,如下的list标签。

1
2
3
4
5
6
<h1>Client ${client.name}</h1>
<ul>
#{list items:client.accounts, as:'account' }
<li>${account}</li>
#{/list}
</ul>

动作:@{…} 或者 @@{…}
我们可以使用Router来根据一个特殊的路由规则反向生成一个URL。而在模板中,我们使用@{…}来生成URL。
例子:

1
2
3
4
5
6
<h1>Client ${client.name}</h1>
<p>
<a href="@{Clients.showAccounts(client.id)}">All accounts</a>
</p>
<hr />
<a href="@{Clients.index()}">Back</a>

@@{…}动作做和@{…}一样的事情,不同之处在于它生成的是相对URL(对于email的处理尤其有用。)

多语言消息:&{…}用来做国际化
譬如在conf/messages文件中设置下面的值
clientName=The client name is %s
在模板中如下使用:

1
2
3
4
5
6
<h1>&{'clientName', client.name}</h1>
注释:*{…}* 注释语法,会被模板引擎自动忽略。
*{**** Display the user name ****}*
<div class="name">
${user.name}
</div>

1
2
3
4
5
6
7
Java脚本:%{…}%
脚本比表达式复杂很多。脚本能声明一些变量和使用一些语句。使用%{…}%来插入脚本。
%{
fullName = client.name.toUpperCase()+' '+client.forname;
}%
<h1>Client ${fullName}</h1>

脚本也能直接使用out来输出内容

1
2
3
4
%{
fullName = client.name.toUpperCase()+' '+client.forname;
out.print('<h1>'+fullName+'</h1>');
}%

同时脚本也能用来做循环遍历等操作

1
2
3
4
5
6
7
8
9
10
<h1>Client ${client.name}</h1>
<ul>
%{
for(account in client.accounts) {
}%
<li>${account}</li>
%{
}
}%
</ul>

需要特别强调的是,模板并不是一个用来做复杂操作的地方。所以更加推荐使用标签,或者把复杂计算移动到控制器、模型中区。

模板继承:
模板能继承其他模板,譬如能被作为其他模板的一部分包含进来。
要继承其他模板,使用extends语法,如下:

1
2
3
4
5
6
7
8
9
10
#{extends 'main.html' /}
<h1>Some code</h1>
main.html模板是一个单独的模板,它使用#{doLayout /}
来包含其他内容。
<h1>Main template</h1>
<div id="content">
#{doLayout /}
</div>

自定义标签:
你能很容易地为你的应用程序创建标签。标签式一个存储在app/views/tags目录下的模板文件,模板名就是标签名。
如创建一个hello标签,只需要创建包含如下内容的文件app/views/tags/hello.html
Hello from tag!
不需要做任何配置,你可以使用如下使用标签。

1
#{hello /}

接收标签参数:
标签参数是曝露的模板变量,变量名以下划线开始。如

1
Hello ${_name} !

使用的时候就可以如下传递标签参数

1
#{hello name:'Bob' /}

如果你的标签只有一个参数,你可以直接使用_arg作为默认参数,它的名字是隐含的。

1
Hello ${_arg}!

调用的时候,也可以同时省略参数名

1
#{hello 'Bob' /}

使用标签体(即标签内部的内容,而不是标签的属性):
如果你的标签支持body,那么你可以使用doBody来引用传递进来的标签体内容

1
Hello #{doBody /}!

使用的使用,如下传递标签体内容

1
2
3
#{hello}
Bob
#{/hello}

在模板中使用扩张的java对象方法:
在模板引擎中使用java对象时,这些对象已经被增加了一些新的方法。这些方法在标准的java类中并不存在,它们是被模板引擎动态加进来的。
如为了在模板中对数字进行格式化,format方法被加到java.lang.Number中。
然后我们就可以再模板中如下进行数字格式化操作。

1
2
3
4
5
<ul>
#{list items:products, as:'product'}
<li>${product.name}. Price : ${product.price.format('## ###,00')}</li>
#{/list}
</ul>

自定义格式化:
你可能需要一些比较特殊的格式化操作。
你只需简单地继承play.templates.JavaExtensions类,然后增加自定义的格式化方法,如下

1
2
3
4
5
6
7
8
9
10
11
12
package ext;
import play.templates.JavaExtensions;
public class CurrencyExtensions extends JavaExtensions {
public static String ccyAmount(Number number, String currencySymbol) {
String format = "'"+currencySymbol + "'#####.##";
return new DecimalFormat(format).format(number);
}
}

自定义格式化方法必须是静态的,并且返回值应该是字符串(被写回到画面上)。第一个参数就是被传递进来的对象。
然后你就可以如下使用:

1
<em>Price: ${123456.324234.ccyAmount()}</em>

模板引擎在play启动是会自动检测到这个自定义的扩张。你只需要重启下服务器以使得扩张方法生效。

模板中的隐含变量:
所有被加到renderArgs中的变量都直接变成模板中的变量,在模板中直接使用。
譬如,你可以如下把控制器中把一个“user”bean注入到模板中。
renderArgs.put(“user”, user );
当从action中渲染模板时,框架同时会把下面的对象中加到模板中
即模板中可以直接使用的变量:
session, the Session object
flash, the Flash scope
request, the current Request
params, HTTP params
play, a reference to play.Play
lang, the current language
messages, the messages map
out, the Writer