freemarker 笔记

Freemarker是java的模板引擎,主要用于MVC中的view层,生成html展示数据给客户端.可以完全替代jsp.
freemarker模板中没有业务逻辑,外部java程序通过数据库操作等生成数据传入template中,
template + data-model = output

1.template
变量替换 ${...}

常用FTL tags:
(1).
<#if condition>
<#elseif condition>
<#else>
</#if>
其中condition是boolean值,可以进行返回boolean的表达式
如<#if (user.age > 23)></#if>
  <#if user.name == "mimi"></#if>
如果condition的包含的字符没有双引号引起来,就表示这是个变量${},
不用在condition里使用${}来表示变量
<#if x > 3></#if>这种方式是错误的,因为freemarker会先解释前面那个">",
可以使用<#if (x > 3)></#if>或<#if x &gt; 1><?#if>
(2).
<#list sequence as item>...</#list>
有两个有用的变量在这个<#list>循环里面,
一个是item_index(item要根据list中那个item改变),从0开始计数,记录当前是第几个元素.
另外一个是item_has_next,测试当前的item是不是最后一个元素
在<#list>中可以使用<#break>跳出循环
(3).
<#include>
可以使用它导入共用的的东西,比如footer,head
各种ftl tags可以嵌套使用

2.处理template中不存在的变量,
如果在template中引用的变量并不在module里，当变量的值为null，也当是不存在变量.那么freemarker会报错
可以使用
<#if user??>${user}</#if>如果user存在才显示
<h1>Welcome ${user!"Anonymous"}!</h1>如果不存在使用变量"!"后面的默认值
对于多级对象属性的情况使用()来防止中间的变量为null
<#if (user.name)??>${user.name}</#if>
${(user.name)!"Anonymous"}

3.表达式
可以在${...} <#if>的condition中进行各种表达式计算
比如 +,-,*,/,%
产生boolean值的表达式
>, <, ==, !=, >=, <=, &&, ||, !
当然>,>=比较特殊,因为它包括tags的结束符
所以应该转义 &gt;, &gte;
也可以使用()包裹着

4.build-ins
build-ins是修饰各种变量的有用funtion,比如要使用string变成大写,使用string的upper_case build-in,使用方法是在变量后加?
如 user?upper_case
freemarker提供了各种变量类型的许多build-ins
常用的有
str?html :将str中包含的html特殊字符转义,比如<被转义成为&lt;
str?cap_first : 第一个字符大写
str?lower_case: 字符串转小写
str?upper_case: 字符串转大写
str?trim : 删除字符串两边空格

列表有个size build-in显示列表的长度
sequence?size

可以将浮点数修改为int
-1.9?int 結果是1,只取int部分，不做各种舍取操作

5.在模板里定义变量
比如<#assign user="pp">
他会隐藏module里面的user变量,如果有的话

6.命名空间
默认的各种变量都是定义在main namespace中，虽然我们没有注意到
当我们写各种模板时,我们希望各个模板的变量不要被隐藏，这时这要到命名空间了.
当我们在主模板中引入其他模板时,这时不要使用<#include>了，而使用<#import>
<#import "/lib/my_test.ftl" as my>
这样我们要调用my_test.ftl中的变量时就用my.var调用了

7.空格处理
freemarker默认是不会压缩template中的空格,也就是你写了什么就是什么
这在一些应用可能有用,但在web应用无疑是浪费带宽,所以应该压缩一下freemarker
的output,可以在template中用<#compress>包裹内容.
但是如果每个文件都使用<#compress>会有点麻烦,
也可以configuration那个freemarker的主要配置类对象中设置
config.setWhitespaceTrip(true); (但我测试是无效)

二.java程序员相关freemarker的内容
1.freemarker.template.Configuration
这是freemarker设置的中心地方,他还负责创建新的template,缓存预编译的template. Configuration的生命周期一般是应用级的,所以一般是在应用的开始时创建Configuration.
Configuration config = new Configuration();
//get the template
Template template = config.getTemplate("test.ftl");
//build module
Map root = new HashMap();
root.put("user","bigfan");
//Merge data-model with template
Writer out = new OutputStreamWriter(System.out);
template.process(root, out);
out.flush();

2.freemarker的有效变量
在freemarker内部,有效的变量必须是实现了freemarker.template.TemplateModel接口的java对象,但是我们之前用的String,List等并没有实现这个接口，其实这是因为freemarker使用了一种叫做object wrapping的方式将java标准类转换为相应的实现了这个接口的类.

3.freemarker内部有两大数据类型: Scalar, Container
其中Scalar包括
Boolean, Number, String, Date
基中Container包括
Hashes, sequences, Collections

4.设置Shared variables
这些变量在所有的template中都是有效的.
config.setSharedVariable("company", "Foo Inc.");

5.settings是影响freemarker行为的值
比如locale, number_format
可以有三个层次的settings:
(1).在Configuration中设置的setting，使用setter方法
比如
myCfg.setLocale(java.util.Locale.ITALY);
myCfg.setNumberFormat("0.####");
也可以在.properties文件中定义name-value,再使用myCfg.setSetting()方法
(2).Template层也可以设置setting,但是template是可缓存的,所以必须在template第一次创建时就设置setting,而这比较难控制
(3).Environment层,
template对象可以得到freemarker.core.Environment这个对象,
再使用这个对象的setter进行设置,应该在执行template.process()之前就设置好
(4).还可以在template文件中进行设置,使用directive
<#setting locale="it_IT">
<#setting number_format="0.####"> 

6.Template loaders
freemarker有三种loader：文件方式,classpath,servletContext
void setDirectoryForTemplateLoading(File dir);
void setClassForTemplateLoading(Class cl, String prefix); 
void setServletContextForTemplateLoading(Object servletContext, String path);

7.Template caching
当从configuration中getTemplate()时, configuration会缓存template,所以下次再拿相同的template就不会重新创建template和解释这个template. 如果修改template文件后,freemarker会重新读取和解释这个template,默认时间是5秒钟去判断文件是否修改.有一个"update delay"相关的设置可以修改这个值.
但是如果是使用classpath方式load模板的话,并不会提示说你已经修改了模板文件.因为在classpath的文件的默认是被认为不会被修改的.

8.freemarker会用本地locale格式化数字
比如10000会被输出10,000
这有时对后端程序是有害的.
我们可以使用
cfg.setNumberFormat("0.######");
也可以使用数字的build-in "c" 比如 ${userId?c}
也可以试试在模板文件中使用<#number_format "0.######">

9.freemarker的properties配置文件
可以在classpath中定义freemarker.properties配置文件
配置模板:
template_update_delay = 30 #in seconds
default_encoding = utf-8
locale = utf-8
whitespace_stripping = true
auto_import="/WEB-INF/content/index.ftl" as p, "/WEB-INF/content2/index.ftl" as cms
tag_syntax=auto_detect
url_escaping_charset=UTF-8
datetime_format=yyyy-MM-dd HH:mm:ss
date_format=yyyy-MM-dd
time_format=HH:mm:ss
number_format=0.######;
boolean_format=true,false