Freemarker 使用总结
FreeMarker模板文件主要由如下4个部分组成:
文本:直接输出部分
注释:<!-- …-->格式部分,不输出
插值:即${}或者#{}部分,使用数据模型中的部分替代输出.
FTL指令:freemarker指定,和html标记类似,名字前加#予以区分,不会输出.
一. Freemarker指令规则
前面的#可以变为@, ,如果该指令是一个用户指令而不是系统内建指令时,应将#符号改成@符号. FreeMarker会忽略FTL标签中的空白字符,值得注意的是< , /> 和指令之间不允许有空白字符.
a) 开始标签<#directivename parameter>
b) 结束标签</#directivename>
c) 空标签:<#directivename parameter/>
二. Freemarker插值规则
a) 通用插值${expr};
i. 插值结果为字符串值:直接输出表达式结果
ii. 插值结果为数字值:根据默认格式(由#setting指令设置)将表达式结果转换成文本输出.可以使用内建的字符串函数格式化单个插值
iii. 插值结果为日期值:根据默认格式(由#setting指令设置)将表达式结果转换成文本输出.可以使用内建的字符串函数格式化单个插值
iv. 插值结果为布尔值:根据默认格式(由#setting指令设置)将表达式结果转换成文本输出.可以使用内建的字符串函数格式化单个插值.
v. 字符串格式化例子: ${lastUpdated?string("yyyy-MM-dd HH:mm:ss zzzz")}
b) 数字格式化插值:#{expr}或#{expr;format}
i. 数字格式化插值可采用#{expr;format}形式来格式化数字,其中format可以是:
mX:小数部分最小X位
MX:小数部分最大X位
ii. 数字格式化例子:#{x; m1M2} <#-- 输出2.58 -->
三. 表达式
表达式是FreeMarker模板的核心功能,表达式放置在插值语法${}之中时,表明需要输出表达式的值;表达式语法也可与FreeMarker标签结合,用于控制输出.实际上FreeMarker的表达式功能非常强大,它不仅支持直接指定值,输出变量值,也支持字符串格式化输出和集合访问等功能.
a) 直接指定值, 使用直接指定值语法让FreeMarker直接输出插值中的值,而不是输出变量值.直接指定值可以是字符串,数值,布尔值,集合和MAP对象.
i. 字符串:直接指定字符串值使用单引号或双引号限定,如果字符串值中包含特殊字符需要转义.
ii. 数值: 表达式中的数值直接输出,不需要引号.小数点使用"."分隔,不能使用分组","符号.FreeMarker目前还不支持科学计数法
iii. 布尔值: 直接使用true和false,不使用引号.
iv. 集合: 集合以方括号包括,各集合元素之间以英文逗号","分隔.
<#list ["星期一", "星期二", "星期三", "星期四", "星期五", "星期六", "星期天"] as x>
${x}
</#list>
1. 集合: 可以使用数字范围定义数字集合,如2..5等同于[2, 3, 4, 5]
v. Map对象: Map对象使用花括号包括,Map中的key-value对之间以英文冒号":"分隔,多组key-value对之间以英文逗号","分隔
b) 输出变量值: FreeMarker的表达式输出变量时,这些变量可以是顶层变量,也可以是Map对象中的变量,还可以是集合中的变量,并可以使用点(.)语法来访问Java对象的属性
i. 顶层变量: 直接放在数据模型中的值直接使用${variableName}来输出变量值
ii. 输出集合元素: 如果需要输出集合元素,则可以根据集合元素的索引来输出集合元素,集合元素的索引以方括号指定.FreeMarker还支持返回集合的子集合,如果需要返回集合的子集合
iii. 输出Map元素: Map对象可以是直接HashMap的实例,甚至包括JavaBean实例,对于JavaBean实例而言,我们一样可以把其当成属性为key,属性值为value的Map实例.为了输出Map元素的值,可以使用点语法或方括号语法
c) 字符串操作: 操作非常灵活,可以将字符串常量和变量连接起来,也可以返回字符串的子串
i. 使用${..}或#{..}在字符串常量部分插入表达式的值,从而完成字符串连接.
ii. 直接使用连接运算符+来连接字符串
d) 集合连接运算符: 集合运算符是将两个集合连接成一个新的集合,连接集合的运算符是+
i. <#list ["星期一","星期二","星期三"] + ["星期四","星期五","星期六","星期天"] as x>
${x}
</#list>
e) Map对象的连接运算符也是将两个Map对象连接成一个新的Map对象,Map对象的连接运算符是+
f) 算术运算符:FreeMarker表达式中完全支持算术运算,FreeMarker支持的算术运算符包括:+, - , * , / , %
i. 运算符两边的运算数字必须是数字
ii. 使用+运算符时,如果一边是数字,一边是字符串,就会自动将数字转换为字符串再连接
iii. 使用内建的int函数可对数值取整
g) 比较运算符:
i. =或者==:判断两个值是否相等.
ii. !=:判断两个值是否不等. =和!=两边必须是相同类型的值
iii. >或者gt:判断左边值是否大于右边值
iv. >=或者gte:判断左边值是否大于等于右边值
v. <或者lt:判断左边值是否小于右边值
vi. <=或者lte:判断左边值是否小于等于右边值
h) 逻辑运算符
i. 逻辑与:&&
ii. 逻辑或:||
iii. 逻辑非:!
iv. 逻辑运算符只能作用于布尔值,否则将产生错误
i) 内建函数FreeMarker还提供了一些内建函数来转换输出,可以在任何变量后紧跟?,?后紧跟内建函数,就可以通过内建函数来轮换输出变量
i. html:对字符串进行HTML编码
ii. cap_first:使字符串第一个字母大写
iii. lower_case:将字符串转换成小写
iv. upper_case:将字符串转换成大写
v. trim:去掉字符串前后的空白字符
j) 空值处理运算符FreeMarker对空值的处理非常严格,FreeMarker的变量必须有值,没有被赋值的变量就会抛出异常,因为FreeMarker未赋值的变量强制出错可以杜绝很多潜在的错误,如缺失潜在的变量命名,或者其他变量错误.这里所说的空值,实际上也包括那些并不存在的变量,对于一个Java的null值而言,我们认为这个变量是存在的,只是它的值为null,但对于FreeMarker模板而言,它无法理解null值,null值和不存在的变量完全相同.
i. !:指定缺失变量的默认值
ii. ??:判断某个变量是否存在
四. FreeMarker的常用指令
FreeMarker的FTL指令也是模板的重要组成部分,这些指令可实现对数据模型所包含数据的抚今迭代,分支控制.除此之外,还有一些重要的功能,也是通过FTL指令来实现的.
a) if指令
b) switch , case , default , break指令
c) list, break指令
d) include指令
e) import指令
f) noparse指令noparse指令指定FreeMarker不处理该指定里包含的内容,
g) escape , noescape指令escape指令导致body区的插值都会被自动加上escape表达式,但不会影响字符串内的插值,只会影响到body内出现的插值
h) assign指令用于为该模板页面创建或替换一个顶层变量
i) setting指令该指令用于设置FreeMarker的运行环境
j) macro , nested , return指令macro可以用于实现自定义指令,通过使用自定义指令,可以将一段模板片段定义成一个用户指令.
来源：oschina
链接：https://my.oschina.net/u/2615530/blog/779406