Play framework模板引擎扩展对象JavaExtensions

在模板引擎中使用Java对象是必不可少的，开发者还可以为其增加一些额外的方法。这些方法并没有定义在原始的Java类中，而是模板引擎动态添加的。例如，为了使模板中的数字进行格式化，可以为java.lang.Number对象增加format()方法，这样就可以非常简单地格式化数字：

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

以上例子展示了如何在模板引擎中使用format()方法对数字进行格式化操作。同样地，也可以对日期等其他Java对象进行格式化操作。

Java扩展为在视图层的模版中调用对象提供了更加便捷的方式，并让表达式可以表示更符合特定格式的内容。本小节是对Play内置Java扩展的介绍，通过对这些扩展相应实例的讲解，可以让开发者非常容易地实现自定义扩展。

集合扩展

Play模板中的集合扩展主要有：join(separator)、pluralize()、pluralize(plural)、pluralize(singular, plural)、last()。

 (1)join(separator)扩展的作用是使用给定的分隔符连接集合中的条目，其返回类型为String。可以将给定的分隔符作为join(separator)扩展的separator参数进行传递，具体的使用方法如下：

 针对给定的集合['red', 'green', 'blue']使用join('/')扩展，采用“/”符号将red、green、blue三个集合元素连接起来，运行结果为：

red/green/blue

 (2)pluralize()扩展的作用是区别集合的单复数显示形式。pluralize()扩展首先会进行判断，当集合的数量大于1时，返回字符串+“s”（即英文语法中的复数）的形式，其返回类型为String。可以在模板中直接对某个集合使用pluralize()：

colour${['red', 'green', 'blue'].pluralize()} 

 对colour进行pluralize()扩展操作，由于集合['red', 'green', 'blue']有三个元素，因此会显示colour的复数形式，运行结果为：

colours

  (3)pluralize(plural)扩展具有plural参数，其作用是指定集合为复数时展现的形式。当集合的数量不为1时，该扩展方法将返回一个给定字符，以plural参数作为复数的后缀显示，其返回类型为String。pluralize(plural)扩展的使用方法与pluralize()类似：

box${['red', 'green', 'blue'].pluralize('es')}

对box进行pluralize('es')扩展操作，指定其复数的后缀为“es”，由于集合['red', 'green', 'blue']有三个元素，因此会显示box的复数形式，运行结果为：

boxes

 (4)pluralize(singular, plural)扩展具有singular、plural两个参数，分别用于指定集合的单数和复数的表现形式，其返回类型为String。当集合中元素的数量为1时，该扩展方法将以字符singular作为后缀，用于展现单数形式：

journ${['red'].pluralize('al', 'aux')}

对journ进行pluralize('al', 'aux')扩展操作，由于集合中只有一个元素，故采用“al”后缀的单数表现形式，运行结果为：

journal

当集合中的元素数量大于1时，该扩展方法将以字符plural作为后缀，用于展现复数形式：

journ${['red', 'green', 'blue'].pluralize('al', 'aux')}

对journ进行pluralize('al', 'aux')扩展操作，由于集合中有三个元素，故采用“aux”后缀的复数表现形式，运行结果为：

journaux

(5)last()扩展的使用方法很简单，作用是返回集合中最后一个元素。由于集合中元素的数据类型未知，故其返回值为Object。

${['red', 'green', 'blue'].last()}

给定的集合['red', 'green', 'blue']中最后的一个元素为blue，last()扩展会将其返回，运行结果为：

blue

2.日期扩展

Play模板中的日期扩展主要有：format(format)、format(format, language)、since()、since(condition)。

（1)format(format)扩展的作用是根据给定的日期格式对字符串进行格式化，最后返回格式化后的日期，其返回类型为String。

   ${new Date(1275910970000).format('dd MMMM yyyy hh:mm:ss')}

该扩展的format参数用于规定日期的格式，上例中format参数为“dd MMMM yyyy hh:mm:ss”，即将日期按照“日 月 年 时:分:秒”的格式进行处理，运行结果为：

07 June 2010 01:42:50

(2)format(format, language)扩展的作用与前面介绍的类似，不过具有format、language两个参数。其中format参数的功能相同，就不做过多的介绍了，language参数的作用是指定日期所采用的国际化语言(需要事先进行国际化配置)，其返回类型为String。

${new Date(1275910970000).format('dd MMMM yyyy hh:mm:ss', 'fr')}

该扩展按照“dd MMMM yyyy hh:mm:ss”规则格式化日期，并遵循fr法语国际化规则，运行结果为：

07 juin 2010 01:42:50

(3)since()扩展可以用于时刻的比较，即相对现在时刻将日期格式化为一个相对的时间，比如3分钟之前(3 minutes ago)、1天前(1 day ago)等等，其返回类型为String。

${new Date(new Date().getTime() - 1000000).since()}

在模板中使用new Date().getTime()获得系统的当前时间，并将其减去1000000毫秒(约等于16分钟)，运行结果为：

16 minutes ago

since()扩展还有其他功能，可以利用以下的消息自定义相对时间的输出形式：since.seconds、since.minutes、since.hours、since.days、since.months以及since.years。

(4)since(condition)扩展的作用同样是格式化日期，将日期格式化为相对现在的某个时刻，其返回类型为String。如果给定的condition参数为true，只要相对的日期是在一个月之前，返回的String为那时的日期：

${new Date(1262350000000).since(true)}

since(condition)的condition参数为true，返回的String为相对时刻的日期，其运行结果为：

Jan 1, 2010

如果给定的condition参数为false，格式化的效果就与since()相同：

${new Date(1262350000000).since(false)}

 其运行结果为：

5 months ago

 since(condition)扩展可以使用与since()相同的消息来自定义相对时间的输出形式，也可以使用since.format的方式自定义一个月之前的日期的输出形式

3.长整型扩展

Play模板中的长整型扩展主要有：asdate(format)、asdate(format, language)以及formatSize()。

(1)asdate(format)扩展的作用是将时间戳格式化为日期格式，其中format参数用于规定日期的格式，其返回类型为String。

${1275910970000.asdate('dd MMMM yyyy hh:mm:ss')}

使用asdate(format)扩展对时间戳1275910970000进行操作，运行结果为：

07 June 2010 01:42:50

(2)asdate(format, language)扩展和format()的用法类似，使用给定的语言将时间戳格式化为日期。不同的是其具有format、language两个参数，其中format参数的功能相同，就不做过多的介绍了，language参数的作用是指定日期所采用的国际化语言(需要事先进行国际化配置)，其返回类型为String。

${1275910970000.asdate('dd MMMM yyyy hh:mm:ss', 'fr')}

遵循fr法语国际化规则，运行结果为：

07 juin 2010 01:42:50

(3)formatSize()扩展的作用是将字节数格式化为文件大小，即以KB、MB、GB等单位表示长整型。

${726016L.formatSize()}

对长整型726016L进行格式化，运行结果为：

709KB

4.Map扩展

 Play模板中的Map扩展主要有：asAttr()和asAttr(condition)。

(1)Map对象是由“key/value”键值对的形式组成的，asAttr()扩展可以将Map对象中的key和value格式化为HTML中的属性，其返回类型为：play.templates.Template.ExecutableTemplate.RawData。

${[id:'42', color:'red'].asAttr()}

该Map对象中有两组元素，使用asAttr()扩展进行处理，运行结果为：

id="42" color="red"

(2)asAttr(condition)扩展用法与asAttr()类似，当参数condition为true时，将Map对象中的key和value格式化为HTML中的属性，其返回类型为：play.templates.Template.ExecutableTemplate.RawData。

${[id:'42', color:'red'].asAttr(true)}

运行结果

id="42" color="red"

当参数condition为false时则不进行转化，模板中不会输出任何内容。

5.数字扩展

Play模板中的数字扩展主要有：divisibleBy(divisor)、format(format)、formatCurrency(currencyCode)以及page(pageSize)。

(1)divisibleBy(divisor)扩展可以用于判断数字是否可以被给定的除数整除，其返回类型为boolean。divisibleBy(divisor)的divisor参数为除数，具体用法如下：

${42.divisibleBy(7)}

由于42可以被7整除，运行结果为：

true

(2)format(format)扩展的作用是根据给定的格式对字符串进行格式化，其返回类型为String。

${42.format('000.00')}

对数字42进行格式化，规定整数部分不少于3位，不足3位前面补0，保留两位小数，运行结果为：

042.00

(3)formatCurrency(currencyCode)扩展可以将数字根据给定的货币代码转化为货币表现形式，其返回类型为String。

${42.formatCurrency('EUR').raw()}

货币代码EUR表示欧元，运行结果为：

€ 42.00

 (4)page(pageSize)扩展主要用于页面的分页，可以根据给定的大小返回分页的页数，其返回类型为Integer。

${42.page(10)}

设置pageSize参数为10，规定每页10项，运行结果为：

5

6.对象扩展

Play模板中的对象扩展主要有：addSlashes()、capAll()、capFirst()、cut(substring)、escape()、nl2br()、raw()、raw(condition)以及yesNo('yes', 'no')。

(1)addSlashes()扩展的作用是为字符串对象中的单引号或双引号添加转义符，其返回类型为String。

${"single quote (')".addSlashes().raw()} ${'double quote (")'.addSlashes().raw()}

分别为单引号和双引号添加转义符，运行结果为：

single quote (\') double quote (\")

(2)capAll()扩展可以使字符串对象中每个单词的首字母变为大写，其返回类型为String。

${"lorum ipsum dolor".capAll()}

对字符串"lorum ipsum dolor"进行每个单词首字母大写操作，运行结果为：

Lorum Ipsum Dolor

(3)capFirst()扩展可以使字符串对象中第一个单词的首字母变为大写，其返回类型为String。

${"lorum ipsum dolor".capFirst()}

对字符串"lorum ipsum dolor"进行首字母大写操作，运行结果为：

Lorum ipsum dolor

 (4)cut(substring)扩展可以从对象字符串中删除给定的子字符串，并返回删除后的字符串，其返回类型为String。

${"lorum ipsum dolor".cut('um')}

如果给定的子字符串确实存在，则将其删除；如果不存在，则不做任何操作，运行结果为：

lor ips dolor

(5)escape()扩展可以将对象字符串中的HTML字符变为带转义符的形式，其返回类型为String。

${"The <blink>tag</blink> is evil".escape().raw()}

使用escape()扩展后，查看页面源代码会发现字符串已经被转义，运行结果为：

The <blink>tag</blink> is evil

(6)nl2br()扩展的作用是将字符串对象中的‘\n’替换为HTML的<br />标签，其返回类型为String。

${"one\ntwo".nl2br()}

   运行结果为：

one<br/>two

 (7)raw()扩展会直接返回对象的内容，跳过模板转义处理，其返回类型为play.templates.Template.ExecutableTemplate.RawData。如果不使用raw()扩展，直接在模板上打印小于符号：

${'<'}

 经过模板解析，运行结果为：

<

为其添加raw()扩展：

${'<'.raw()}

 在模板解析时，会自动跳过转义处理，运行结果为：

<

(8)raw(condition)扩展与raw()用法类似，其返回类型为play.templates.Template.ExecutableTemplate.RawData。当给定的condtion参数为true时，跳过模板转义处理直接返回对象的内容；当给定的condtion参数为false时，不输出内容。

${'<'.raw(true)}

 在模板解析时，会自动跳过转义处理，运行结果为：

<

(9)yesNo('yes', 'no')扩展在使用时会进行判断，如果对象为真就返回第一个参数（'yes'），反之则返回第二个参数（'no'），其返回类型为Sring。

${"not empty".yesno('yes', 'no')}

   运行结果为：

yes

7.字符串扩展

Play模板中的字符串扩展主要有：asXml()、camelCase()、capitalizeWords()、escapeHtml()、escapeJavaScript()、escapeXml()、noAccents()、pad(length)、slugify()以及urlEncode()。

(1)asXml()扩展可以解析给定的XML字符串，如果符合XML文件的树状结构，将会输出结构标记的内容，其返回类型为groovy.util.slurpersupport.GPathResult。

${"<table><tr><td>red </td><td>green </td><td>blue </td></tr></table>".asXml()}

如果XML字符串格式正确，将会成功解析，运行结果如下，反之会出现模板错误警告：

red green blue 

(2)camelCase()扩展将字符串格式化为camel形式（即骆驼命名法），这样可以使得代码更容易交流，可读性更强，其返回类型为String。

${"lorum ipsum dolor".camelCase()}

混合使用大小写字母来构成全新的字符串，运行结果为：

LorumIpsumDolor

(3)capitalizeWords()扩展可以使字符串中每个单词的首字母变为大写，其返回类型为String。

${"lorum ipsum dolor".capitalizeWords()}

对字符串"lorum ipsum dolor"进行每个单词首字母大写操作，运行结果为：

Lorum Ipsum Dolor

(4)escapeHtml()扩展会将字符串中的HTML字符变为带转义符的形式，其返回类型为String。

${"The <blink>tag</blink> is evil".escapeHtml().raw()}

运行结果为：

The <blink>tag</blink> is evil

 (5)escapeJavaScript()扩展会将字符串中的JavaScript字符变为带转义符的形式，其返回类型为String。

${"single quote (') double quote (\")".escapeJavaScript().raw()}

运行结果为：

single quote (\') double quote (\")

(6)escapeXml()扩展会将字符串中的XML字符变为带转义符的形式，其返回类型为String。

${"<>\"&".escapeXml().raw()}

运行结果为：

<>"&

(7)noAccents()扩展的作用是将字符串中带有重音符号的字母替换为不带重音符号的字母，其返回类型为String。重音符号是指标识在字母上的附加符号，最典型的具有重音符号的语言就是法语。

${"Stéphane Épardaud".noAccents()}

带有重音符号的é和É都被转换，运行结果为：

Stephane Epardaud

(8)pad(length)扩展可以在字符串后增加HTML空格转义符，其中length-1为指定HTML空格转义符个数的参数，其返回类型为String。

${"x".pad(4).raw()}${"x"}

为字符串指定了4个HTML空格转义符，运行结果为：

x   x 

    (9)slugify()扩展将字符串进行格式化，使用“-”将字符串中的每个单词连接，并将原有的标点符号丢弃，返回类型为String。该扩展主要用于生成URL，可以避免与URL的保留字符冲突。

${"The Play! framework’s manual".slugify()}

将原有字符串中的标点符号丢弃，使用“-”进行连接，运行结果为：

the-play-framework-s-manual

(10)urlEncode()扩展可以将URL查询字符串中用到的特殊符号转义输出，其返回类型为String。

${"!@#\$%^&()|".urlEncode()}

该实例中的符号为URL查询字符串中常见的特殊符号，运行结果为：

%21%40%23%24%25%5E%26%28%29%7C

8.字符串扩展

Play模板中的字符串数组扩展主要有：add(value)、contains(string)以及remove(string)。

(1)add(value)扩展可以在数组末尾增加数据，其返回类型为String[]。

${(["red", "green", "blue"] as String[]).add('pink').join(' ')}

为原有数组末尾添加“pink”元素，并使用join(' ')扩展为数组元素之间添加空格符，运行结果为：

red green blue pink

(2)contains(string)扩展可以用于判断，如果数组中存在给定的字符串就返回true，反之则返回false，其返回类型为boolean。

${(['red', 'green', 'blue'] as String[]).contains('green')}

 判断原有字符串数组中是否包含“green”元素，运行结果为：

true

(3)remove(string)扩展可以删除字符串数组中给定的元素，并返回删除后的字符串数组，其返回类型为String[]。

${(['red', 'green', 'blue'] as String[]).remove('green').join(' ')}

删除原有字符串数组中的“green”元素，并使用join(' ')扩展为其添加空格符，运行结果为：

red blue

如果需要删除的元素不存在，则不进行任何操作。