模版制作03：FreeMarker快速入门

FreeMarker是一款基于java的模版引擎，用于生成文本（比如HTML）。它的语法和作用和JSP类似，JSP需要依赖Servlet容器（如Tomcat），而FreeMarker只需要Java运行环境。

官方网站上的这张图很形象的说明了FreeMarker的用途和工作原理：模版+数据=文本（HTML）

FreeMarker工作原理

在Jspxcms中，模版就是/template/1/default/目录下的模版文件（后缀也是.html），数据来自SpringMVC Controller的Model.addAttribute(String name, Object value)或者Jspxcms自定义标签（如：[@InfoList node='news';list]...[/@InfoList]）。

更多资料可以参考FreeMarker官方网站的文档，FreeMarker官方还提供了FreeMarker中文文档。

表达式

和JSP的EL表达式基本是一样的：${myname}，${user.username}。

获取Map值。${customs['abc']}
获取数组值。${arr[0]}
算术运算。+ - * / %。如：${100 – x*x} ${x/2} ${12%10}
比较运算。< <= >= > == = != 或者 lt lte gt gte
逻辑运算。|| && !

内建函数（Built-in）

内建函数是FreeMarker的一大优势，很多在JSP里面需要通过复杂处理才能实现的功能，这里只需要用简单的内建函数就搞定了。

null值处理。${mouse!"No mouse"} ${username!"匿名用户"}。FreeMarker中输出null值会报错，如果希望对象为null时，什么都不显示且不报错，可以这样处理 ${mouse!} ${user.username!} ${(user.username)!}（最后一种方式可以避免user对象为null导致的错误）。
布尔值处理。${foo?string("yes", "no")}
日期处理。${lastUpdated?string("yyyy-MM-dd HH:mm:ss")}
HTML转义。${username?html}。为避免直接输出< >等值，导致XSS攻击，通常会对输出的值进行转义。
JS转义。${foo?js_string}。对js中的引号等字符进行处理，给js变量赋值是非常有用，比如var s = "${foo?js_string}"。
获取子串。${'abc'?substring(2)} ${username?substring(0,3)}
获取字符串长度。${'abc'?length} ${username?length}
获取列表大小。${list?size}
小写转换。${"GrEeN MoUsE"?lower_case}
大写转换。${"GrEeN MoUsE"?upper_case}

标签（Directive）

FreeMarker标签类似JSP标签。标签默认使用尖括号< >，在Jspxcms中为了避免和HTML标签混淆，便于在Dreamweaver中编辑，使用中括号[ ]作为标签符号。以下示例一律使用中括号。

标签有两种，一种是系统自带标签，以[#开头；一种是自定义标签，以[@开头。

注释标签：[#-- 这是需要注释的代码 --]

自定义标签

以InfoList标签为例说明。

[@InfoList node='news';infos]
    [#list infos as info]
        <a href="${info.url}">${info.title}</a>
    [/#list]
[/@InfoList]

[@InfoList node='news';list]
    [#list list as bean]
        <a href="${bean.url}">${bean.title}</a>
    [/#list]
[/@InfoList]

[@InfoList;list]
    [#list list as bean]
        <a href="${bean.url}">${bean.title}</a>
    [/#list]
[/@InfoList]

标签名称InfoList。用于获取文档列表的标签。
参数node='news'。node是参数名，'news'是参数值。意为获取栏目代码为news的文档。有时候参数不是必须的。
返回值;infos。分号;后面的是返回值。infos是标签返回的对象。标签获取的文档列表就存放在这个对象里，这个对象的名称可以随意定义。

if（判断标签）

[#if 2>1]
  ...
[#elseif username=="abc"]
  ...
[#elseif username?starts_with("red")]
  ...
[#else]
  ...
[/#if]

判断是否为null：[#if username??]...[/#if]

list（列表标签）

[#list sequence as item]
    ...
[/#list]

[#list 1..10 as i]
    ...
[/#list]

获取循环的序号${item_index} ${item_index + 1}。
判断是否还有下一个对象[#if item_has_next]...[/#if]
sequence as item和item_index、item_has_next中的item必须一致，如果sequence as info，则用${info_index}、${info_has_next}。

break（跳出标签）

[#list seq as x]
    ${x}
    [#if x = "spring"][#break][/#if]
[/#list]

include（包含标签）

[#include "/common/copyright.ftl"]
[#include "/common/navbar.html" parse=false /]

parse。布尔值，默认true。是否解析包含的模版。如果想包含一个纯文本的文件，不解析里面的内容，可以设置为false。

assign（定义变量标签）

[#assign myname="abc"]
[#assign myname=username]
[#assign myname]孔子[/#assign]

escape（转义标签）

为了避免跨站脚本攻击（XSS），通常会对输出的内容做HTML转义，比如${foo?html}。但是所有变量都要做这个转义不仅麻烦，还容易遗忘。另外FreeMarker空值处理也很麻烦且容易遗忘，比如${foo!}、${(user.username)!}。

使用excape标签可以很好的解决这个问题。

[#escape x as (x)!?html]
    ...
    ${user.username}
    ...
[/#escape]

只要被这个标签包含的代码，都相当于加上了${(foo.bar)!?html}，如${user.username}相当于${(user.username)!?html}。即包含了空值处理，也包含了HTML转义处理。

noescape（不转义标签）

在escape标签内有对象不需要转义时，可以用noescape标签。

[#escape x as (x)!?html]
    ...
    [#noescape]${text}[/#noescape]
    ...
[/#escape]