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

Play有一个高效的用来动态生成HTML, XML, JSON, 任何文本格式文档的[url=http://www.playframework.org/documentation/1.0/templates]模板系统[/url]。模板引擎使用[url=http://groovy.codehaus.org/]Groovy[/url]（一种JVM平台上的动态语言）作为表达式语言。包含一个可以用来创建可重用函数的标签系统。
模板保存在app/views目录下。

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

[b]表达式：${…}[/b]，声明其是一个动态的表达式。表达式的执行结果会被插入到${…} 占位符所在的位置中。
[b]标签：#{tagName /}[/b]，标签式一个模板片段，被使用是通常需要传入一些参数。如果标签只有一个参数，那么根据约定，叫它为“arg”同时, 同时参数名可以省略。
例子:
我们使用用script 标签来加载javascript文件。[color=red]标签必须被关闭[/color]，要嘛直接关闭，要嘛用关闭标签关闭，如下。
#{script 'jquery.js' /}
#{script 'jquery.js'}#{/script}
如果含有多个参数的标签名，参数名不能省略，如下的list标签。

<h1>Client ${client.name}</h1>
<ul>
    #{list items:client.accounts, as:'account' }
        <li>${account}</li>
    #{/list}
</ul>

[b]动作：@{…} 或者 @@{…}[/b]
我们可以使用Router来根据一个特殊的路由规则反向生成一个URL。[color=red]而在模板中，我们使用@{…}来生成URL[/color]。
例子：

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

@@{…}动作做和@{…}一样的事情，[color=red]不同之处在于它生成的是相对URL[/color]（对于email的处理尤其有用。）

[b]多语言消息：&{…}用来做国际化[/b]
譬如在conf/messages文件中设置下面的值
clientName=The client name is %s
在模板中如下使用：
<h1>&{'clientName', client.name}</h1>

[b]注释：*{…}* 注释语法，会被模板引擎自动忽略。[/b]
*{**** Display the user name ****}*
<div class="name">
${user.name}
</div>

[b]Java脚本：%{…}%[/b]
脚本比表达式复杂很多。脚本能声明一些变量和使用一些语句。使用%{…}%来插入脚本。
%{
fullName = client.name.toUpperCase()+' '+client.forname;
}%

<h1>Client ${fullName}</h1>

脚本也能直接使用out来输出内容
%{
fullName = client.name.toUpperCase()+' '+client.forname;
out.print('<h1>'+fullName+'</h1>');
}%

同时脚本也能用来做循环遍历等操作
<h1>Client ${client.name}</h1>
<ul>
%{
for(account in client.accounts) {
}%
<li>${account}</li>
%{
}
}%
</ul>
[color=red]需要特别强调的是，模板并不是一个用来做复杂操作的地方。所以更加推荐使用标签，或者把复杂计算移动到控制器、模型中区。[/color]

[b]模板继承：[/b]
模板能继承其他模板，譬如能被作为其他模板的一部分包含进来。
要继承其他模板，使用extends语法，如下：
#{extends 'main.html' /}

<h1>Some code</h1>
main.html模板是一个单独的模板，它使用#{doLayout /}
来包含其他内容。
<h1>Main template</h1>

<div id="content">
#{doLayout /}
</div>

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

[b]接收标签参数：[/b]
标签参数是曝露的模板变量，变量名以下划线开始。如
Hello ${_name} !
使用的时候就可以如下传递标签参数
#{hello name:'Bob' /}

[color=red]如果你的标签只有一个参数，你可以直接使用_arg作为默认参数，它的名字是隐含的。[/color]
Hello ${_arg}!
调用的时候，也可以同时省略参数名
#{hello 'Bob' /}

[b]使用标签体（即标签内部的内容，而不是标签的属性）：[/b]
如果你的标签支持body，那么你可以使用doBody来引用传递进来的标签体内容
Hello #{doBody /}!
使用的使用，如下传递标签体内容
#{hello}
Bob
#{/hello}

[b]在模板中使用扩张的java对象方法：[/b]
在模板引擎中使用java对象时，这些对象已经被增加了一些新的方法。这些方法在标准的java类中并不存在，它们是被模板引擎动态加进来的。
如为了在模板中对数字进行格式化，format方法被加到java.lang.Number中。
然后我们就可以再模板中如下进行数字格式化操作。
<ul>
#{list items:products, as:'product'}
<li>${product.name}. Price : ${product.price.format('## ###,00')} €</li>
#{/list}
</ul>

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

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);
  }

}

自定义格式化方法[color=red]必须是静态的，并且返回值应该是字符串（被写回到画面上）。第一个参数就是被传递进来的对象。[/color]
然后你就可以如下使用：
<em>Price: ${123456.324234.ccyAmount()}</em>

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

[b]模板中的隐含变量：[/b]
[color=red]所有被加到renderArgs中的变量都直接变成模板中的变量，在模板中直接使用。[/color]
譬如，你可以如下把控制器中把一个“user”bean注入到模板中。
renderArgs.put("user", user );
当从action中渲染模板时，[color=red]框架同时会把下面的对象中加到模板中
即模板中可以直接使用的变量：[/color]
[list]
[*]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
[/list]