2016 March 20

freemarker相关

保留关键字

true：布尔值”true”
false：布尔值”false”
gt：比较运算符”大于”
gte：比较运算符”大于或等于”
lt：比较运算符”小于”
lte：比较运算符”小于或等于”
as：由少数指令使用
in：由少数指令使用
using：由少数指令使用
如果你的变量名包含一些符号时，比如 foo-bar，你编写${foo-bar},FreeMarker 可能会认为是从 foo 中减去 bar,这时可以使用${.vars[“foo-bar”]}

特殊变量

特殊变量是由 FreeMarker 引擎自己定义的变量。要访问它们，你可以使用.variable_name 语法。比如，你不能仅仅写 version，而必须写.version。支持的特殊变量有：
data_model：你可以使用来直接访问数据模型的哈希表。也就是，你使用global 指令定义在这里不可见的的变量。
vars：表达式.vars.foo 返回和表达式 foo 相同的变量。出于某些原因你不得不使用方括号语法时这是有用的，因为它只对哈希表子变量有用，所以你需要一个人工的父哈希表。
version：返回 FreeMarker 版本号的字符串形式。
now ：返回当前的时间日期。示例： ${.now}。
globals：你可以使用来访问全局可访问的变量的哈希表：数据模型和由global 指令创建的变量。注意用 assign 或 macro 创建的变量不是全局的。因此当你使用 globals 时你不能隐藏变量。
locales：你可以访问本地化变量的哈希表。
language：返回当前本地设置的语言部分的值。比如.locale 是 en_US，那么.lang 是 en。
locale：返回当前本地设置的值。这是一个字符串，比如 en_US。
main：你可以用来访问主命名空间的哈希表。
namespace：你可以用来访问当前命名空间的哈希表。
current_node ：当前节点，处理xml过程中用到。
output_encoding（从 FreeMarker 2.3.1 版本开始可用）：返回当前输出字符集的名称。
current_template_name：当前模板的名称（从 FreeMarker 2.3.23 版本开始可用）。
main_template_name：顶级模板的名称 (从 FreeMarker 2.3.23 版本开始可用)。
url_escaping_charset（从 FreeMarker 2.3.1 版本开始可用）： URL 转义的字符集的名称。
error（从 FreeMarker 2.3.1 版本开始可用）：这个变量在 recover 指令体中可以访问，它存储了我们恢复错的错误信息。

非空判断

检测不存在的值：使用name?? 或者(user.name)??
处理不存在的值：name!”unknown” 或者(user.name)!”unknown” 或者 name! 或者 (user.name)!
检测空值：使用name?has_content
${user!”Anonymous”}相当于<#if user??>${user}<#else>Anonymous</#if>
${user!}则什么都不输出相当于<#if user??>${user}</#if>

循环变量内建函数

counter 从1开始的索引
has_next 是否还有下一项
index 从0开始的索引
is_even_item 是否是奇数项
is_first 是否是第一项
is_last 是否是最后一项与has_next相反
is_odd_item 是否是偶数项
item_parity 返回字符串值 ”odd” 或 ”even”
item_parity_cap 返回字符串值 ”Odd” 或 ”Even”
item_cycle 可以指定何值来代替 ”odd” 和 ”even”，允许多余两个值来循环

常用指令

include指令

<#include filename>
<#include filename options>
说明:options包括parse 和encoding
parse ：为true时，被包含的文件作用FTL模板处理,否则作为普通文本处理，默认为true。
encoding ：编码
<#include “*/footer.ftl”>
*代表本目录或任一上级目录。
如有”/foo/bar/template.ftl”，则上例按如下顺序查找/foo/bar/footer.ftl 、 /foo/footer.ftl、 /footer.ftl 。如有<#include “*/commons/footer.ftl”> ，会按/foo/bar/commons/footer.ftl、/foo/commons/footer.ftl 、/commons/footer.ftl顺序查找。

import指令

<#import path as hash>
例：
mylib.ftl:

<#macro copyright date><br>
 <p>Copyright (C) ${date} Julia Smith. All rights reserved.</p><br>
</#macro><br>

在另一个文件中：
<#import “/libs/mylib.ftl” as my>
<@my.copyright date=”1999-2002”/>

noparse指令

<#noparse>
 <#list animals as being>
 <tr><td>${being.name}<td>${being.price} Euros
 </#list>
</#noparse>

输出

<#list animals as being>
 <tr><td>${being.name}<td>${being.price} Euros
 </#list>

assign指令

<#assign name=value>
<#assign name1=value1 name2=value2 ... nameN=valueN> 
<#assign name=value in namespacehash>
<#assign name> capture this </#assign>
<#assign name in namespacehash> capture this</#assign>

在当前或指定命名空间内定义或替换已存在的顶级变量。如：some_hash.subvar不行，而 some_hash则可以。 Assign指令中包含的内容不会被输出，而是被存入指定的变量中。
<#assign var=”你好”>
${var}
输出：你好。

global指令

<#global name=value>
<#global name1=value1 name2=value2 ... nameN=valueN> 
<#global name> capture this </#global>

在所有命名空间内定义或替换已存在的顶级变量。规则与assign一致。

local 指令

<#local name=value> 
<#local name1=value1 name2=value2 ... nameN=valueN> 
<#local name> capture this</#local>

规则与assign一致，只在宏和方法的内部定义才会有作用。

springmvc 配置参数

locale

作用
设置默认地区，主要影响数字、日期输出格式，request中没有指定地区时模板查找值
例如：eh_US，zh_CN

classic_compatible

作用
兼容旧版freemarker习惯，不建议使用，会导致一些问题，比如include必须用绝对路径值
“true”, ”false” 或者 “yes”, ”no” 或者 “t”, ”f” 或者 ”y”, ”n”

template_exception_handler

作用
模板异常处理器
值
rethrow，debug，html_debug，ignore
也可以是类名
默认是debug

arithmetic_engine

作用
数学运算引擎
值
bigdecimal,conservative
默认值bigdecimal

object_wrapper

作用
对象包装器
值
default, default_2_3_0，simple，beans，jython

number_format

作用
设置默认数字输出格式
值
number，currency，percent，computer
也可以 DecimalFormat 类型(比如”0.##”)
具体使用参考
http://docs.oracle.com/javase/8/docs/api/java/text/DecimalFormat.html?is-external=true

boolean_format

作用
设置默认布尔值输出格式
值
true时输出的值和false时输出的值使用英文逗号分隔
比如true,false或者是,否

date_format,time_format,datetime_format

作用
设置默认时间、日期输出格式
值
short, medium, long, full
也可以是表达式比如yyyy-MM-dd hh:mm:ss a或者yyyy-MM-dd HH:mm:ss

time_zone

作用
设置时区
值
GMT+8:00，Asia/Shanghai
默认为系统时区和设置的locale无关

sql_date_and_time_time_zone

作用
设置java.sql.Date的时区
值
GMT+8:00，Asia/Shanghai

output_encoding

作用
设置FreeMarker输出的字符集
值
utf-8，gb2312

url_escaping_charset

作用
设置URL转义字符集
值
UTF-8，GB2312,ISO-8859-1
默认为output_encoding中的值

auto_flush

作用
设置模板处理后自动刷新
值
true,false
默认值true

new_builtin_class_resolver

作用
设置?new内建函数使用范围?new()
值
unrestricted，safer，allows_nothing
如果值包含冒号则使用OptInTemplateClassResolver.此时可使用allowed_classes:和trusted_templates:
默认是safer
如果值包含点则当作类名使用

show_error_tips

作用
控制是否显示错误提示
值
true,false
默认值true

api_builtin_enabled

作用
控制?api内建函数是否可用
值
true,false
默认值false

auto_import

作用
在所有模板中自动引入模板
值
规范：模板文件 as 命名空间
多个引入用逗号隔开
/lib/form.ftl as f, /lib/widget as w, “/lib/odd name.ftl” as odd

auto_include

作用
在所有模板中自动包含模板
值
规范：模板文件
多个引入用逗号隔开
/include/common.ftl, “/include/evil name.ftl”

default_encoding

作用
设置默认编码，如果不设置，可能会导致切换到不同环境时产生乱码问题
值
UTF-8,ISO-8859-1,GB2312
默认值为操作系统的编码

localized_lookup

作用
控制模板本地化查找是否可用，比如locale设置为zh_CN加载模板foo.ftl时，freemarker自动查找foo_zh_CN.ftl,foo_zh.ftl,foo.ftl并返回找到的第一个
值
true,false
默认值为true

whitespace_stripping

作用
控制是否删除多余空格
值
true,false
默认值为true

template_update_delay

作用
设置模板缓存时间，没有设置单位时，单位是秒
值
正整数，或者带单位的正整数（单位可以是s,ms,m,h;分别表示秒，毫秒，分钟，小时）
默认值为5秒

tag_syntax

作用
设置标签风格<#tag> 或者[#tag]
值
auto_detect，angle_bracket，square_bracket
默认值为angle_bracket

template_loader

作用
设置自定义的模板加载器
值
default,类名
默认值 default

宏定义

格式：
<#macro name param1 param2 … paramN>
…
</#macro>
name：宏变量的名称。
param1，param2 等：局部变量的名称，存储参数的值，在= 号后面的默认值（表达式）可选。默认值也可以是另外一个参数，比如：<#macro section title label=title>。

例子：
<#macro test>
Test text
</#macro>

调用方式：
<@test/>

输出：
Test text

<#macro test foo bar baaz>
Test text, and the params: ${foo}, ${bar}, ${baaz}
</#macro>

调用方式：
<@test “a” “b” 55-2/>
<@test bar=”b” foo=”a” baaz=55-2/>

输出都是：
Test text, and the params: a, b, 23

nested 指令执行自定义指令开始和结束标签中间的模板片段。
<#macro do_twice>

<#nested>
<#nested>
</#macro>

调用方式：
<@do_twice>something</@do_twice>

输出：

something
something