Freemarker 语法规则

Freemarker页面语法
A 概念
最常用的 3 个概念
sequence 序列，对应java 里的list 、数组等非键值对的集合
hash      键值对的集合
namespace 对一个ftl 文件的引用, 利用这个名字可以访问到该ftl 文件的资源
B 指令
if, else, elseif
语法
Java代码 
1. <#if 条件>  
2.   ...  
3. <#elseif condition2>  
4.   ...  
5. <#elseif condition3>  
6.   ...  
7. ...  
8. <#else>  
9.   ...  
10. </#if> 
用例
Freemarker代码 
1. <#if x = 1>  
2.   x is 1 
3. </#if>  
4. <#if x = 1>  
5.   x is 1 
6. <#else>  
7.   x is not 1 
8. </#if> 
switch, case, default, break
语法

Freemarker代码 
1. <#switch value>  
2.   <#case refValue1>  
3.          ...  
4.          <#break>  
5.   <#case refValue2>  
6.          ...  
7.          <#break>  
8.   ...  
9.   <#case refValueN>  
10.          ...  
11.          <#break>  
12.   <#default>  
13.          ...  
14. </#switch> 
 
用例
字符串
Freemarker代码 
1. <#switch being.size>  
2.   <#case "small">  
3.           This will be processed if it is small  
4.           <#break>  
5.   <#case "medium">  
6.           This will be processed if it is medium  
7.           <#break>  
8.   <#case "large">  
9.           This will be processed if it is large  
10.           <#break>  
11.   <#default>  
12.           This will be processed if it is neither  
13. </#switch> 
 
数字
Freemarker代码 
1. <#switch x>  
2.   <#case x = 1>  
3.          1 
4.   <#case x = 2>  
5.          2 
6.   <#default>  
7.          d  
8. </#switch> 
 
如果x=1 输出 1 2, x=2 输出 2, x=3 输出d
list, break
语法
Freemarker代码 
1. <#list sequence as item>  
2. ...  
3. <#if item = "spring"><#break></#if>  
4. ...  
5. </#list> 
关键字

item_index:是list当前值的下标

item_has_next:判断list是否还有值
用例
Freemarker代码 
1. <#assign seq = ["winter", "spring", "summer", "autumn"]>  
2. <#list seq as x>  
3.   ${x_index + 1}. ${x}<#if x_has_next>,</#if>  
4. </#list> 

输出：
      1.winter,
      2.spring,
      3.summer,
      4.autumn
include
语法
Freemarker代码 
1. <#include filename> 
  或则
Java代码 
1. <#include filename options> 
 
options包含两个属性

encoding="GBK" 编码格式

parse=true 是否作为ftl语法解析,默认是true，false就是以文本方式引入.注意在ftl文件里布尔值都是直接赋值
的如parse=true,而不是parse="true"
用例
/common/copyright.ftl 包含内容
Ftl代码 
1. Copyright 2001-2002 ${me}  
2.  
3. All rights reserved.   
 
模板文件

Java代码 
1. <#assign me = "Juila Smith">  
2.  
3. Some test  
4.  
5. Yeah  
6. ___________________________________________________________________________  
7.  
8. <SPAN><STRONG><SPAN><#include "/common/copyright.ftl" encoding="GBK"></SPAN>  
9.  
10.  
11.  
12.  
13. </STRONG>  
14.  
15.  
16. </SPAN> 


输出结果:
Some test

Yeah.

Copyright 2001-2002 Juila Smith

All rights reserved. 

Import
语法
Freemarker代码 
1. <#import path as hash> 
类似于java里的import,它导入文件，然后就可以在当前文件里使用被导入文件里的宏组件
用例
假设mylib.ftl 里定义了宏copyright 那么我们在其他模板页面里可以这样使用
Freemarker代码 
1. <#import "/libs/mylib.ftl" as my>  
2.  
3. <@my.copyright date="1999-2002"/>  
4.  
5. <#-- "my"在freemarker里被称作namespace --> 
 
compress
语法
Freemarker代码 
1. <#compress>  
2.   ...  
3. </#compress> 
 
用来压缩空白空间和空白的行
escape, noescape
语法
Freemarker代码
1. <#escape identifier as expression>  
2.   ...  
3.   <#noescape>...</#noescape>  
4.   ...  
5. </#escape> 
用例
      主要使用在相似的字符串变量输出，比如某一个模块的所有字符串输出都必须是html安全的，这个时候就可以使用
该表达式
Freemarker代码 
1. <#escape x as x?html>  
2.   First name: ${firstName}  
3.   <#noescape>Last name: ${lastName}</#noescape>  
4.   Maiden name: ${maidenName}  
5. </#escape> 
相同表达式
Ftl代码 
1. First name: ${firstName?html}  
2. Last name: ${lastName }  
3. Maiden name: ${maidenName?html} 
 
assign
语法
Freemarker代码 
1. <#assign name=value>  
2.  
3. <#-- 或则 -->  
4.  
5. <#assign name1=value1 name2=value2 ... nameN=valueN>  
6.  
7. <#-- 或则 -->  
8.  
9. <#assign same as above... in namespacehash>  
10.  
11. <#-- 或则 -->  
12.  
13. <#assign name>  
14.   capture this  
15. </#assign>  
16.  
17. <#-- 或则 -->  
18.  
19. <#assign name in namespacehash>  
20.   capture this  
21. </#assign> 
 
用例
生成变量,并且给变量赋值

给seasons赋予序列值
Ftl代码 
1. <#assign seasons = ["winter", "spring", "summer", "autumn"]> 
给变量test加1
Ftl代码 
1. <#assign test = test + 1> 
给my namespage 赋予一个变量bgColor,下面可以通过my.bgColor来访问这个变量
Ftl代码 
1. <#import "/mylib.ftl" as my>  
2.  
3. <#assign bgColor="red" in my> 
将一段输出的文本作为变量保存在x里
Ftl代码 
1. <#assign x>  
2.   <#list 1..3 as n>  
3.          ${n} <@myMacro />  
4.   </#list>  
5. </#assign>  
6.  
7. Number of words: ${x?word_list?size}  
8.  
9. ${x}  
10.  
11. <#assign x>Hello ${user}!</#assign>          error  
12.  
13. <#assign x=" Hello ${user}!">         true 
同时也支持中文赋值，如：
Ftl代码 
1. <#assign 语法>  
2.   java  
3. </#assign>  
4.  
5. ${语法} 
打印输出:

java

global
语法
Freemarker代码 
1. <#global name=value>  
2.  
3. <#--或则-->  
4.  
5. <#global name1=value1 name2=value2 ... nameN=valueN>  
6.  
7. <#--或则-->  
8.  
9. <#global name>  
10.   capture this  
11. </#global> 
 
     全局赋值语法，利用这个语法给变量赋值，那么这个变量在所有的namespace [A1] 中是可见的, 如果这个变量被当前的assign 语法覆盖 如<#global x=2> <#assign x=1> 在当前页面里x=2 将被隐藏，或者通过${.global.x} 来访问
setting
语法
Freemarker代码 
1. <#setting name=value> 
 
用来设置整个系统的一个环境
locale
number_format
boolean_format
date_format , time_format , datetime_format
time_zone
classic_compatible
用例
假如当前是匈牙利的设置，然后修改成美国
Ftl代码 
1. ${1.2}  
2.  
3. <#setting locale="en_US">  
4.  
5. ${1.2}   
 
输出
         1,2

         1.2
因为匈牙利是采用", "作为十进制的分隔符，美国是用". "
macro, nested, return
语法
Freemarker代码 
1. <#macro name param1 param2 ... paramN>  
2.   ...  
3.   <#nested loopvar1, loopvar2, ..., loopvarN>  
4.   ...  
5.   <#return>  
6.   ...  
7. </#macro> 
用例
Ftl代码 
1. <#macro test foo bar="Bar"[A2]  baaz=-1>  
2.   Test text, and the params: ${foo}, ${bar}, ${baaz}  
3. </#macro>  
4.  
5. <@test foo="a" bar="b" baaz=5*5-2/>  
6.  
7. <@test foo="a" bar="b"/>  
8.  
9. <@test foo="a" baaz=5*5-2/>  
10.  
11. <@test foo="a"/>  
 
输出
  Test text, and the params: a, b, 23
  Test text, and the params: a, b, -1
  Test text, and the params: a, Bar, 23
  Test text, and the params: a, Bar, -1

定义循环输出的宏
Ftl代码 
1. <#macro list title items>  
2. ${title?cap_first}:  
3.         <#list items as x>  
4.            *${x?cap_first}  
5.  
6.          </#list>  
7. </#macro>  
8.  
9. <@list items=["mouse", "elephant", "python"] title="Animals"/> 
 
输出结果:
      Animals:
           *Mouse
           *Elephant
           *Python

包含body 的宏
Ftl代码 
1. <#macro repeat count>  
2.   <#list 1..count as x>  
3.          <#nested x, x/2, x==count>  
4.   </#list>  
5. </#macro>  
6.  
7. <@repeat count=4 ; c halfc last>  
8.   ${c}. ${halfc}<#if last> Last!</#if>  
9. </@repeat>  
 
输出
  1. 0.5
  2. 1
  3. 1.5
  4. 2 Last!
t, lt, rt
语法
Freemarkder代码 
1. <#t> 去掉左右空白和回车换行  
2.  
3. <#lt>去掉左边空白和回车换行  
4.  
5. <#rt>去掉右边空白和回车换行  
6.  
7. <#nt>取消上面的效果 
C 一些常用方法或注意事项
表达式转换类
${expression} 计算expression 并输出
#{ expression } 数字计算#{ expression ;format} 安格式输出数字format 为M 和m
M 表示小数点后最多的位数,m 表示小数点后最少的位数如#{121.2322;m2M2} 输出121.23
数字循环
1..5 表示从1 到5 ，原型number..number
对浮点取整数
${123.23?int} 输出 123
给变量默认值
${var?default("hello world")?html} 如果var is null 那么将会被hello world 替代
判断对象是不是 null
Ftl代码 
1. <#if mouse?exists>  
2.       Mouse found  
3. <#else> 
也可以直接${mouse?if_exists})输出布尔形

－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－
（1）解决输出中文乱码问题：
     freemarker乱码的原因：
• 没有使用正确的编码格式读取模版文件,表现为模版中的中文为乱码
解决方法：在classpath上放置一个文件freemarker.properties，在里面写上模版文件的编码方式，比如
default_encoding=UTF-8
locale=zh_CN
注意：eclipse中除了xml文件、java文件外，默认的文件格式iso8859-1
• 数据插入模版时，没有使用正确的编码，表现出模版中的新插入数据为乱码
解决方法：在result的配置中，指定charset，s2的FreemarkerResult.java会将charset传递freemarker
<action name="ListPersons" class="ListPersons">
<result type="freemarker">
    <param name="location">/pages/Person/view.ftl</param>
    <param name="contentType"> text/html;charset=UTF-8
</param>
</result>
</action>
（2）提高freemarker的性能
在freemarker.properties中设置：
template_update_delay=60000
避免每次请求都重新载入模版，即充分利用cached的模版
（3）尽量使用freemarker本身的提供的tag，使用S2 tags 的标签会在性能上有所损失

（4）freemarker的标签种类：
• ${..}:FreeMarker will replace it in the output with the actual value of the thing in the curly brackets. They are called interpolation s.
• # ,代表是FTL tags（FreeMarker Template Language tags） ，hey are instructions to FreeMarker and will not be printed to the output
o <#if ...></#if>
o <#list totalList as elementObject>...</#list>
• @ ,代表用户自定义的标签
• <#-- --> 注释标签，注意不是<!-- -->
（5）一些特殊的指令：  
• r代表原样输出：${r"C:\foo\bar"}
• <#list ["winter", "spring", "summer", "autumn"] as x>${x}</#list>
• ？引出内置指令
o String处理指令：
 html:特殊的html字符将会被转义，比如"<"，处理后的结果是&lt;
 cap_first 、lower_case 、upper_case
 trim :除去字符串前后的空格
o sequences处理指令
 size ：返回sequences的大小
o numbers处理指令
 int:number的整数部分，(e.g. -1.9?int is -1)
（6）对于null，或者miss value，freemarker会报错
•   ?exists:旧版本的用法
• !：default value operator，语法结构为： unsafe_expr !default_expr，比如 ${mouse!"No mouse."} 当mouse不存在时，返回default value；
o (product.color)!"red" 这种方式，能够处理product或者color为miss value的情况；
o 而product.color!"red"将只处理color为miss value的情况
• ??: Missing value test operator ,测试是否为missing value
o unsafe_expr ?? ：product.color??将只测试color是否为null
o (unsafe_expr )??：(product.color)??将测试product和color是否存在null
Ftl代码 
1. <#if mouse??>  
2.   Mouse found  
3. <#else>  
4.   No mouse found  
5. </#if>  
6. Creating mouse...  
7. <#assign mouse = "Jerry">  
8. <#if mouse??>  
9.   Mouse found  
10.  
11. <#else>  
12.   No mouse found  
13. </#if> 
 
（7）模版值插入方式 （interpolation）
• 通用方式 （ Universal interpolations）： ${expression }
• 对于字符串：只是简单输出
• 对于数值，会自动根据local确定格式，称为human audience，否则称为computer audience，可以"?c", 比如， <a href="/shop/details?id=${product.id ?c }">Details...</a>,因此这里的id是给浏览器使用的，不需要进行格式化，注意?c只对数值有效
• 对于日期，会使用默认的日期格式转换，因此需要事先设置好默认的转换格式，包括date_format , time_format ，atetime_format
• 对于布尔值，不能输出，会报错并停止模版的执行，比如${a = 2} 会出错，但是可以 string built-in来进行转换
数值处理，具体参考：Built-ins for numbers
    http://freemarker.org/docs/ref_builtins_number.html#ref_builtin_string_for_number

    数值处理的例子：
   
    <#setting number_format="currency"/>
    <#assign answer=42/>
    ${answer}
    ${answer?string} <#-- the same as ${answer} -->
    ${answer?string.number}
    ${answer?string.currency}
    ${answer?string.percent}

    除了使用内置的formate，可以使用任何用Java decimal number format syntax 书写的formate，比如

    <#setting number_format="0.###E0"/>
    <#setting number_format="0"/>
    <#setting number_format="#"/>
    ${1234}
    ${12345?string("0.####E0")}

    更加方便的格式：

    <#setting locale="en_US">
    US people writes:        ${12345678?string(",##0.00")}

    <#setting locale="hu">
    Hungarian people writes: ${12345678?string(",##0.00")}

    

    日期处理，参考Built-ins for dates

    http://freemarker.org/docs/ref_builtins_date.html#ref_builtin_string_for_date

    日期处理的例子：
•     ${openingTime?string.short}
•     ${openingTime?string.medium}
•     ${openingTime?string.long}
•     ${openingTime?string.full}
•     ${nextDiscountDay?string.short}
•     ${nextDiscountDay?string.medium}
•     ${nextDiscountDay?string.long}
•     ${nextDiscountDay?string.full}
•     ${lastUpdated?string.short}
•     ${lastUpdated?string.medium}
•     ${lastUpdated?string.long}
•     ${lastUpdated?string.full}

注意：

    由于java语言中的Date类型的不足，freemarker不能根据Date变量判断出变量包含的部分（日期、时间还是全部），在这种情况下，freemarker

    不能正确显示出${lastUpdated?string.short} 或者 simply ${lastUpdated}，因此，可以通过?date, ?time and ?datetime built-ins

    来帮助freemarker来进行判断，比如${lastUpdated?datetime?string.short}

    除了使用内置的日期转换格式外，可以自己指定日期的格式，使用的是Java date format syntax，比如：
•     ${lastUpdated?string("yyyy-MM-dd HH:mm:ss zzzz")}
•     ${lastUpdated?string("EEE, MMM d, ''yy")}
•     ${lastUpdated?string("EEEE, MMMM dd, yyyy, hh:mm:ss a '('zzz')'")}
    数值专用方式 （ Numerical interpolations）：#{expression } or #{expression ; format }，这是数值专用的输出方式，但是 最好使用通用方式的string built-in或者number_format 来完成转换，Numerical interpolations方式将会被停用
（8）创建自定义模版
Ftl代码 
1. <#macro greet>        
2.      <font size="+2">Hello Joe!</font>  
3. </#macro>

　freemarker的文件一般以后缀ftl，ftl文件的头上要写
     <#assign ww=JspTaglibs["/WEB-INF/webwork.tld"] />
     这样才能在ftl中使用webwork的tag。

　　freemarker确实是不错的模版语言引擎，尤其是处理对象图很方便，处理xml也很方便，还支持xpath

　　什么是FreeMarker？

　　FreeMarker 是一个模版引擎，一个基于文本的模板输出工具（生成任意的HTML表单代码）。它是一个Java package，面向Java程序员的class library。它本身并不是针对最终用户的应用，而是允许程序员将其嵌入到他们的产品中。

　　FreeMarker被设计用来生成HTML Web页面，特别是基于MVC（Model View Controller）模式的应用程序。使用 MVC 模式作为动态的WEB页面的想法，是为了分隔页面设计者 (HTML 设计者) 和程序员。.每个人做自己擅长的那一部分。设计者可以不通过程序员的改变或修改代码来改变网页的样子，因为应用逻辑(Java程序)和页面设计（FreeMarker 模版）是分开的。模板不会被复杂繁琐的程序框架所破坏。即使当一个项目的程序员和HIMTL页面的制作者是同一个人时，这种分隔也是很有用，因为这样有助于保持应用的清晰并易于维护。

　　尽管FreeMarker有一些编程的能力，但它并不是一个象PHP那样的成熟的编程语言。与Java不同的是，Java程序准备用来显示的数据(如SQL queries)，而Freemarker仅是生成文本页，这个文本页显示用于模板的预备数据。

　　FreeMarker 不是一个 Web 应用框架，而更适合充当 Web 应用框架里的一个组件的角色，但 FreeMarker 引擎本身对 HTTP 或 servlets 并不关心，它仅仅是生成文本。在非 Web 应用环境中它同样能够展示完美的用途。然而值得注意的是：我们为使用 FreeMarker 提供了方便的解决方案，作为 Model2 框架（如 Struts ）的视图组件，你也可以在模版中使用 JSP 标签。

　　FreeMarker 是免费的，有 BSD-style license 。它是由 OSI 认证的开源软件。

一、 FreeMarker简介
FreeMarker是一个用Java语言编写的模板引擎，它基于模板来生成文本输出。
所谓模板，就是一份已经写好了基本内容，有着固定格式的文档，其中空出或者用占位符标识的内容，由使用者来填充，不同的使用者给出的数据是不同的。在模板中的占位符，在模板运行时，由模板引擎来解析模板，并采用动态数据替换占位符部分的内容。
FreeMarker与Web容器无关，即在Web运行时，它并不知道Servlet或HTTP。它不仅可以用作表现层的实现技术，而且还可以用于生成XML，JSP或Java 文等。

二、 FreeMarker的优点和缺点
(一) FreeMarker的优点
1.使用FreeMarker的优点之一，可以彻底的分离表现层和业务逻辑。
使用JSP 开发过程中在页面中大量的存在业务逻辑的代码，使得页面内容凌乱，在后期大量的修改维护过程中就变得非常困难。
FreeMarker根本不支持Java脚本代码。
FreeMarker的原理就是：模板+数据模型=输出 ，模板只负责数据在页面中的表现，不涉及任何的逻辑代码，而所有的逻辑都是由数据模型来处理的。用户最终看到的输出是模板和数据模型合并后创建的。
     
2.使用FreeMarker的优点之二，可以提高开发效率。
在我们以往的开发中，使用的都是JSP 页面来展示数据的，即所谓的表现层。我们都知道，JSP在第一次执行的时候需要转换成Servlet类，开发阶段进行功能调适时，需要频繁的修改JSP，每次修改都要编译和转换，那么试想一天中我们浪费在程序编译的时间有多少。相对于JSP来说，FreeMarker模板技术不存在编译和转换的问题，所以就不会存在上述问题。而且开发过程中，我们在不必在等待界面设计开发人员完成页面原形后，我们再来开发程序。

3.使用FreeMarker的优点之三，使得开发过程中的人员分工更加明确。
以往用JSP展现数据时，作为程序员的我们，并不熟悉界面设计技术，反之界面开发人员，也并不熟悉程序语言。对两者而言，交替性的工作本身就有难度。有时候稍有不慎，可能会将某个页面元素删除或去掉了某个程序符号，使得页面走样或程序错误，这样就需要双方相互沟通协作，解决出现的问题。有时候因为项目中的时间，任务量等因素的存在，可能这个工作就由一个人来完成，这样就可能加大某一方开发人员的工作量。
使用FreeMarker后，作为界面开发人员，只专心创建HTML文件、图像以及Web页面的其他可视化方面，不用理会数据；而程序开发人员则专注于系统实现，负责为页面准备要显示的数据。

(二)FreeMarker的缺点
1.使用FreeMarker的缺点之一，应用FreeMarker模板技术，在修改模板后，可能会看到已经过期的数据。如：生成静态的HTML页面后，如果一旦模板改变，而没有及时更新模板生成的HTML页面的话，用户看到的就是过期的数据。
2.使用FreeMarker的缺点之二，FreeMarker模板技术在应用过程中，FreeMarker中的变量必须要赋值，如果不赋值，那么就会抛出异常。想避免错误就要应用if/elseif/else 指令进行判段，如果对每一个变量都判断的话，那么则反而增加了编程的麻烦。
3.使用FreeMarker的缺点之三，FreeMarker的map限定key必须是string，其他数据类型无法操作
4.使用FreeMarker的缺点之四，FreeMarker不支持集群应用。为了编成的方便性，把序列化的东西都放到了Session中，如Session，request等，在开发的过程中确实方便，但如果将应用放到集群中，就会出现错误。

通过以上的阐述，希望可以令您清晰FreeMarker的优点和缺点，旨在抛砖引玉。有什么问题可以留下您的宝贵留言，我非常愿意与大家讨论。