015_插值

1. 插值的使用格式是: ${expression}, 这里的expression可以是所有种类的表达式(比如: ${100 + x})。

2. 插值是用来给表达式插入具体值然后转换为文本(字符串)。插值仅仅可以在两种位置使用: 在文本区(比如: <h1>Hello ${name}!</h1>)和字符串表达式(比如: <#include "/footer/${company}.html">)中。

3. ${expression}表达式的结果必须是字符串, 数字或者日期、时间、日期-时间值, 因为(默认是这样)仅仅这些值可以被插值自动转换为字符串。其它类型的值(比如布尔值, 序列)必须"手动地"转换成字符串, 否则就会发生错误, 中止模板执行。

4. 一个常犯的错误是在不能使用插值的地方使用了它。仅仅在文本区和字符串中起作用。典型的错误使用是<#if ${big}>...</#if>, 这会导致语法错误。简单写为<#if big>...</#if>即可。

5. escape, noescape指令

5.1. 概要

<#escape identifier as expression>

...

   <#noescape>...</#noescape>

   ...

</#escape>

5.2. 当你使用escape指令包围模板中的一部分时, 在块中出现的插值(${...})会和转义表达式自动结合。

5.3. 例如:

<#escape x as x?html>

First name: ${firstName}

   Last name: ${lastName}

</#escape>

5.4. 上例等同于:

First name: ${firstName?html}

Last name: ${lastName?html}

5.5. 有时需要暂时为一个在转义区块中的插值关闭转义。你可以使用非转义指令<#noescape></#noescape>包含关闭转义的部分。

<#escape x as x?html>

   From: ${mailMessage.From}

   Subject: ${mailMessage.Subject}

   <#noescape>Message: ${mailMessage.htmlFormattedBody}</#noescape>

   ...

</#escape>

5.6. 上例等同于:

From: ${mailMessage.From?html}

Subject: ${mailMessage.Subject?html}

Message: ${mailMessage.htmlFormattedBody}

...

6. 字符串类型的插入: 不要忘了转义!

6.1. 如果插值表达式是字符串类型, 强烈建议你使用escape指令和html内建函数来阻止跨站脚本攻击和非格式良好的html页面。

7. 数字类型的插入

7.1. 如果插值表达式是数字类型, 那么根据数字的默认格式(number), 数值将会转换成字符串。这也许会包含最大的小数, 数字分组和相似处理的问题。通常程序员应该设置默认的数字格式(cfg.setNumberFormat("computer");), 而模板设计者不需要处理它(但可以使用内建函数string 为一个插值来重写默认数值格式或者使用setting指令的number_format来设置)。

8. 日期、时间、日期-时间类型插入

8.1. 如果插值表达式是日期、时间、日期-时间类型, 那么日期中的数字将会按照默认格式来转换成文本。通常程序员应该设置默认格式(cfg.setDateFormat("yyyy-MM-dd"); cfg.setTimeFormat("HH:mm:ss.SSS"); cfg.setDateTimeFormat("yyyy-MM-dd HH:mm:ss.SSS");), 而页面设计者无需处理这一点(当然也可以使用内建函数string 来覆盖单独插值的默认格式或者使用setting指令的date_format、time_format和datetime_format来设置)。

8.2. 为了将日期显示成文本, FreeMarker必须知道日期中的哪一部分在使用, 也就是说, 如果仅仅日期部分(年, 月, 日)使用或仅仅时间部分(时, 分, 秒, 毫秒)使用或两部分都用。不幸的是, 由于Java平台技术的限制, 自动探测一些变量是不现实的。这时可以找程序员对数据模型中可能出问题的变量进行处理。如果找出时间日期变量的哪部分在使用是不太可能的话, 就必须使用FreeMarker内建函数date, time和datetime来识别(比如: ${lastUpdated?datetime}), 否则就会出现错误停止执行。

9. 布尔类型插入

9.1. 若要使用插值方式来打印布尔值会引起错误, 中止模板的执行。

9.2. 可以使用setting指令设置参数boolean_format来为FreeMarker配置默认的布尔值格式。那么, 直接编写${married}这样的代码就不会有问题了。但在很多应用程序中,  这样的做法是不推荐使用的, 因为布尔值在不同的地方就应该呈现出不同的格式, 同时将格式留作默认值也可以认为是疏忽, 因为这可能导致错误产生。

9.3. 程序员也可以进行默认格式设置(cfg.setBooleanFormat("c");), 但是也不推荐, 原因同上。

9.4. 当想生成JavaScript或其它计算机语言代码部分时, 那么可以考虑使用${someBoolean?c}("c"代表计算机)来输出布尔值true/false。请记住?c也可以用来输出给计算机看的数字。