FreeMarker使用手册
一、数据模型
(1) 树形结构
(2) 标量: 存储单一的值，如字符串、数字、日期/时间、布尔值
(3) 哈希表: 存储变量及其相关且有唯一标识名称的容器
(4) 存储有序变量的容器
二、FreeMarker模板组成部分
(1)文本
(2)注释: <
(3)插值: ${...}或
(4)FTL指令: 和HTML标记类似，名字前面加
三、基本指令
(1)if指令: <#if condition>
(2)list指令: <#list animals as animal></#list>
1.animal?index: 索引值、animal?counter: 从1开始的索引值、animal?item_parity: 当前计数的奇偶 性odd/even、animal?has_next: 是否是最后一项
2. 跳出循环: <#break>
3.排序
升序排序: <#list list?sort as item>..., 要求序列中变量必须是字符串(按首字母排序)、数字、日 期值
sort_by函数: <#list userList?sort_by("age") as user>, 指定要排序的变量
reverse降序排序: <#list list?reverse as item>, <#list userList?sort_by("age")?reverse as user>
(3)内建函数:
1.html转义: user?html
2.转大写: user?upper_case
3.首字母大写: user?cap_first
4.字符数量: user?length
5.个数： users?size
6.布尔转字符串: animal.protected?string("Y", "N")
7.连接: fruits?join(", ")
8.首字母判断: user?starts_with("J")
9.根据奇偶性赋值: animal?item_cycle('lightRow','darkRow')
(4)处理不存在变量
1.!后默认值: user!"visitor"
2.??判断不存在则会忽略整个代码: <#if user??><#if>
四、表达式
(1)直接指定值
1.字符串: "some text"、"It is \"A\""(\转义)、${r"${foo}"}(r表示原生字符串);
2.数字: 不带引号，不支持科学计数法、小数点前不能不写0
3.布尔值: true、false
4.序列: ["foo", [1,2,3], 2+2]
5.值域:
start..end 包含结尾
start..<end或start..!end 不包含结尾
start..*length 限定长度
start.. 无右边界
6.哈希表: { "name": "Mon", "price": "150" }
(2)检索变量
1.顶层变量: ${user}
2.哈希表中检索: ${user.name}
3.序列中检索: ${user[0].name}
4.特殊变量: .variable_name
(3)字符串操作
1.插值(或连接): 仅在文本区有效, Hello ${user}!
2.获取字符: ${user[0]} 获取字符串中第一个字符
3.字符串切分(子串): <#assign s = "ABCDEF"> ${s[2..3]}
(4)序列操作
1.连接: +号连接，如:<#list ["Joe", "Fred"] + ["Julia", "Kate"] as user>
2.切分: <#assert seq = ["A", "B", "C", "D", "E"]> <#list seq[1..3] as i>${i}</#list>
(5)哈希表操作
1.连接: +号连接
(6)算数运算
1.运算符: 加(+)、减(-)、乘(*)、除(/)、求余(%),
2.获取除法结果整数部分: ${(x/2)?int}
(7)比较运算
1.==、!=、>=、>、<=、<
2.比较符与结束符冲突时，使用 lt 代替 <， lte 代替 <=， gt 代替 > 还有 gte 代替 >=；或者写在括号中<#if (x > y)>
(8)逻辑操作
1.|| 、&& 、!
(9)内建函数
${testString?upper_case}
(10)方法调用
${repeat("Foo", 3)}
五、自定义指令
(1)宏
1.宏是和某个变量关联的模板片段,以便在模板中通过用户定义的指令使用该变量，而该变量表示模板片段
(2)用法:
<
<font size="+2">Hello World!</font>
</
调用时: <@greet></@greet>
(3)宏变量定义参数: 可以定义时指定缺省值，否则调用时必须给所有参数赋值
<
<font size="+2" color="${color}">Hello ${person}!</font>
</
调用时: <@greet person="Fred" color="black"/>
(4)宏的嵌套内容
<
<div>
<
</div>
</
使用1: <@border>Hello World</@border>, 输出结果如下:
<div>
Hello World!
</div>
使用2：<
<
<
<
<
</
<@do_thrice>
Anything.
</@do_thrice>
输出结果: Anything.Anything.Anything.
六、模板中定义变量
(1)简单变量:可以从模板中任意位置访问，或从使用include指令引入的模板访问; assign创建或替换
1.创建: <
2.替换: <
(2)局部变量:只能设置在宏定义体内，只在宏内可见, local指令创建或替换
(3)循环变量:list指令自动创建，只在指令开始和结束标记内有效
(4)全局变量:所有模块共享,global指令定义
七、命名空间
(1)由assign和macro指令创建的变量的集合被称为命名空间
(2)创建A、B两个库
1.import在命名空间B中引入命名空间A, <#import "/lib/my_test.ftl" as my>, ${my.name}
2.在引入的命名空间中编写变量: <#assign mail="jsmith@other.com" in my>
3.数据模型中的变量在任何命名空间中都可见
4.import重复引入相同命名空间时，后面的引入仅创建哈希表来访问
八、空白处理
(1)忽略某些模板文件的空白的工具(在解析阶段移除)
1.剥离空白: 自动忽略FTL标签周边空白，该特性可以通过ftl指令在模板来启用/禁用
2.微调指令
<#t>: 整体消减，忽略本行中首和尾的所有空白
<#rt>: 左侧削减，忽略本行中首部所有的空白
<#lt>: 右侧削减，忽略本行中尾部所有的空白
3.<#ftl>: 移除宏定义和其他顶级指令中的换行符
(2)从输出中移除空白的工具(移除临近空白)
1.<#compress>: 动态监测内容，移除缩进、空行和重复的空格/制表符
九、替换语法
(1)在指令和注释中用[和] 替换<和>，例如:
1.调用预定义指令: [#list animals as animal]...[/#list]
2.调用自定义指令: [@myMacro /]
3.注释: [#-- the comment --]
十、数字格式化
FreeMarker在解析数据格式时，会自动默认将数字按3位分割(如1,000),解决方法如下:
(1)在模板中加.toString()将数字转为字符串,如: ${data.id.toString()}
(2)在FreeMarker配置文件FreeMarker.properties加number_format=#或number_format=0
(3)在模板中直接加<#setting number_format="#">或者<#setting number_format="0">
预定义的数字格式: number(默认格式)、currency(货币)、percent(百分比)
<#assign tempNum=20>
${tempNum}
${tempNum?string.number}或${tempNum?string("number")}
${tempNum?string.currency}或${tempNum?string("currency")}
${tempNum?string. percent}或${tempNum?string("percent")}
