FreeMarker概述
 

         FreeMarker是一个模板引擎，一个基于模板生成文本输出的通用工具，使用纯Java编写

         FreeMarker被设计用来生成HTML Web页面，特别是基于MVC模式的应用程序

         尽管FreeMarker具有一些编程的能力，但通常由Java程序准备要显示的数据，由FreeMarker生成页面，通过模板显示准备的数据（例如以下图）

         FreeMarker不是一个Web应用框架，而适合作为Web应用框架一个组件

         FreeMarker与容器无关，由于它并不知道HTTP或Servlet；FreeMarker相同能够应用于非Web应用程序环境

         FreeMarker更适合作为Model2框架（如Struts）的视图组件，你也能够在模板中使用JSP标记库

         FreeMarker是免费的

 

 

1、通用目标

         可以生成各种文本：HTML、XML、RTF、Java源码等等

         易于嵌入到你的产品中：轻量级；不须要Servlet环境

         插件式模板加载器：能够从不论什么源加载模板，如本地文件、数据库等等

         你能够按你所需生成文本：保存到本地文件；作为Email发送；从Web应用程序发送它返回给Web浏览器

 

2、强大的模板语言

         全部经常使用的指令：include、if/elseif/else、循环结构

         在模板中创建和改变变量

         差点儿在不论什么地方都能够使用复杂表达式来指定值

         命名的宏，能够具有位置參数和嵌套内容

         名字空间有助于建立和维护可重用的宏库，或者将一个大project分成模块，而不必操心名字冲突

         输出转换块：在嵌套模板片段生成输出时，转换HTML转义、压缩、语法高亮等等；你能够定义自己的转换

 

3、通用数据模型

         FreeMarker不是直接反射到Java对象，Java对象通过插件式对象封装，以变量方式在模板中显示

         你能够使用抽象（接口）方式表示对象（JavaBean、XML文档、SQL查询结果集等等），告诉模板开发人员用法，使其不受技术细节的打搅

 

4、为Web准备

         在模板语言中内建处理典型Web相关任务（如HTML转义）的结构

         可以集成到Model2 Web应用框架中作为JSP的替代

         支持JSP标记库

         为MVC模式设计：分离可视化设计和应用程序逻辑；分离页面设计员和程序猿

 

5、智能的国际化和本地化

         字符集智能化（内部使用UNICODE）

         数字格式本地化敏感

         日期和时间格式本地化敏感

         非US字符集能够用作标识（如变量名）

         多种不同语言的同样模板

 

6、强大的XML处理能力

         和指令（2.3版本号）用于递归遍历XML树

         在模板中清楚和直觉的訪问XML对象模型

  
 

  
FreeMarker设计指南(1)

 
1、高速入门

（1）模板 + 数据模型 = 输出

         FreeMarker基于设计者和程序猿是具有不同专业技能的不同个体的观念

         他们是分工劳动的：设计者专注于表示——创建HTML文件、图片、Web页面的其他可视化方面；程序猿创建系统，生成设计页面要显示的数据

         常常会遇到的问题是：在Web页面（或其他类型的文档）中显示的信息在设计页面时是无效的，是基于动态数据的

         在这里，你能够在HTML（或其他要输出的文本）中添?一些特定指令，FreeMarker会在输出页面给终于用户时，用适当的数据替代这些代码

         以下是一个样例：

 

 

Welcome ${user}!

 

Our latest product:

  ${latestProduct.name}!

 

         这个样例是在简单的HTML中添?了一些由${…}包围的特定代码，这些特定代码是FreeMarker的指令，而包括FreeMarker的指令的文件就称为模板（Template）

         至于user、latestProduct.url和latestProduct.name来自于数据模型（data model）

         数据模型由程序猿编程来创建，向模板提供变化的信息，这些信息来自于数据库、文件，甚至于在程序中直接生成

         模板设计者不关心数据从那儿来，仅仅知道使用已经建立的数据模型

         以下是一个可能的数据模型：

(root)

  |

  +- user = "Big Joe"

  |

  +- latestProduct

      |

      +- url = "products/greenmouse.html"

      |

      +- name = "green mouse"

         数据模型类似于计算机的文件系统，latestProduct能够看作是文件夹，而user、url和name看作是文件，url和name文件位于latestProduct文件夹中（这仅仅是一个比喻，实际并不存在）

         当FreeMarker将上面的数据模型合并到模板中，就创建了以下的输出：

 

 

Welcome Big Joe!

 

Our latest product:

 green mouse!

 

（2）数据模型

         典型的数据模型是树型结构，能够随意复杂和深层次，如以下的样例：

(root)

  |

  +- animals

  |   |

  |   +- mouse

  |   |   |  

  |   |   +- size = "small"

  |   |   |  

  |   |   +- price = 50

  |   |

  |   +- elephant

  |   |   |  

  |   |   +- size = "large"

  |   |   |  

  |   |   +- price = 5000

  |   |

  |   +- python

  |       |  

  |       +- size = "medium"

  |       |  

  |       +- price = 4999

  |

  +- test = "It is a test"

  |

  +- whatnot

      |

      +- because = "don‘t know"

         类似于文件夹的变量称为hashes，包括保存下级变量的唯一的查询名字

         类似于文件的变量称为scalars，保存单值

         scalars保存的值有两种类型：字符串（用引號括起，能够是单引號或双引號）和数字（不要用引號将数字括起，这会作为字符串处理）

         对scalars的訪问从root開始，各部分用“.”分隔，如animals.mouse.price

         第二种变量是sequences，和hashes类似，仅仅是不使用变量名字，而使用数字索引，如以下的样例：

(root)

  |

  +- animals

  |   |

  |   +- (1st)

  |   |   |

  |   |   +- name = "mouse"

  |   |   |

  |   |   +- size = "small"

  |   |   |

  |   |   +- price = 50

  |   |

  |   +- (2nd)

  |   |   |

  |   |   +- name = "elephant"

  |   |   |

  |   |   +- size = "large"

  |   |   |

  |   |   +- price = 5000

  |   |

  |   +- (3rd)

  |       |

  |       +- name = "python"

  |       |

  |       +- size = "medium"

  |       |

  |       +- price = 4999

  |

  +- whatnot

      |

      +- fruits

          |

          +- (1st) = "orange"

          |

          +- (2nd) = "banana"

         这样的对scalars的訪问使用索引，如animals[0].name

（3）模板

         在FreeMarker模板中能够包含以下三种特定部分：

?         ${…}：称为interpolations，FreeMarker会在输出时用实际值进行替代

?         FTL标记（FreeMarker模板语言标记）：类似于HTML标记，为了与HTML标记区分，用#開始（有些以@開始，在后面叙述）

?         凝视：包括在（而不是）之间

         以下是一些使用指令的样例：

?         if指令

  Pythons are cheaper than elephants today.

  Pythons are not cheaper than elephants today.

#if> 

?         list指令

We have these animals:

 

Name	Price
${being.name}	${being.price} Euros   #list>

 

输出为：

We have these animals:

 

Name	Price
mouse	50 Euros
elephant	5000 Euros
python	4999 Euros

 

?         include指令

 

 

Test page

 

Blah blah...

 

?         一起使用指令

We have these animals:

 

   

Name	Price
#if>       ${being.name}       #if>	${being.price} Euros   #list>

 

 

-------------------------------------------------------------
 

FreeMarker设计指南(3)

 
3、模板

（1）总体结构

         模板使用FTL（FreeMarker模板语言）编写，是以下各部分的一个组合：

?         文本：直接输出

?         Interpolation：由${和}，或#{和}来限定，计算值替代输出

?         FTL标记：FreeMarker指令，和HTML标记类似，名字前加#予以区分，不会输出

?         凝视：由限定，不会输出

         以下是以一个详细模板样例：

[BR]

[BR]

 

[BR]

[BR]

[BR]

  [BR]

 

Welcome ${user}!

[BR]

 

We have these animals:[BR]

 

[BR]

  [BR]

   

• ${being.name} for ${being.price} Euros[BR]

    #list>[BR]

   

[BR]

[BR]

 

         [BR]是用于换行的特殊字符序列

         注意事项：

?         FTL区分大写和小写，所以list是正确的FTL指令，而List不是；${name}和${NAME}是不同的

?         Interpolation仅仅能在文本中使用

?         FTL标记不能位于还有一个FTL标记内部，比如：

=‘bar‘>...

?         凝视能够位于FTL标记和Interpolation内部，如以下的样例：

Welcome ${user }!

[BR]

We have these animals:[BR]

[BR]

animals as being>[BR]

... 

?         多余的空白字符会在模板输出时移除

（2）指令

         在FreeMarker中，使用FTL标记引用指令

         有三种FTL标记，这和HTML标记是类似的：

?         開始标记：

?         结束标记：#directivename>

?         空内容指令标记：

         有两种类型的指令：提前定义指令和用户定义指令

         用户定义指令要使用@替换#，如...@mydirective>（会在后面讲述）

         FTL标记不可以交叉，而应该正确的嵌套，如以下的代码是错误的：

 

• ${being.name} for ${being.price} Euros

   

       (except for you)

  #list>

  #if>

 

         假设使用不存在的指令，FreeMarker不会使用模板输出，而是产生一个错误消息

         FreeMarker会忽略FTL标记中的空白字符，如以下的样例：

  animals       as[BR]

     being[BR]

>[BR]

${being.name} for ${being.price} Euros[BR]

#list    > 

         可是，

（3）表达式

         直接指定值

?         字符串

n         使用单引號或双引號限定

n         假设包括特殊字符须要转义，如以下的样例：

${"It‘s \"quoted\" and

this is a backslash: \\"}

 

${‘It\‘s "quoted" and

this is a backslash: \\‘}

输出结果是：

It‘s "quoted" and

this is a backslash: \

 

It‘s "quoted" and

this is a backslash: \

n         以下是支持的转义序列： 
转义序列
 
含义
 

\"
 
双引號(u0022)
 

\‘
 
单引號(u0027)
 

\\
 
反斜杠(u005C)
 

\n
 
换行(u000A)
 

\r
 
Return (u000D)
 

\t
 
Tab (u0009)
 

\b
 
Backspace (u0008)
 

\f
 
Form feed (u000C)
 

\l
 
 

\g
 
> 
 

\a
 
&
 

\{
 
{
 

\xCode
 
4位16进制Unicode代码
 


n         有一类特殊的字符串称为raw字符串，被觉得是纯文本，当中的\和{等不具有特殊含义，该类字符串在引號前面加r，以下是一个样例：

${r"${foo}"}

${r"C:\foo\bar"} 

输出的结果是：

${foo}

C:\foo\bar 

?         数字

n         直接输入，不须要引號

n         精度数字使用“.”分隔，不能使用分组符号

n         眼下版本号不支持科学计数法，所以“1E3”是错误的

n         不能省略小数点前面的0，所以“.5”是错误的

n         数字8、+8、08和8.00都是同样的

?         布尔值

n         true和false，不使用引號

?         序列

n         由逗号分隔的子变量列表，由方括号限定，以下是一个样例：

${x}

#list>

输出的结果是：

winter

spring

summer

autumn

n         列表的项目是表达式，所以能够有以下的样例：

[2 + 2, [1, 2, 3, 4], "whatnot"]

n         能够使用数字范围定义数字序列，比如2..5等同于[2, 3, 4, 5]，可是更有效率，注意数字范围没有方括号

n         能够定义反递增的数字范围，如5..2

?         散列（hash）

n         由逗号分隔的键/值列表，由大括号限定，键和值之间用冒号分隔，以下是一个样例：

{"name":"green mouse", "price":150}

n         键和值都是表达式，可是键必须是字符串

         获取变量

?         顶层变量： ${variable}，变量名仅仅能是字母、数字、下划线、$、@和#的组合，且不能以数字开头

?         从散列中获取数据

n         能够使用点语法或方括号语法，如果有以下的数据模型：

(root)

|

+- book

|   |

|   +- title = "Breeding green mouses"

|   |

|   +- author

|       |

|       +- name = "Julia Smith"

|       |

|       +- info = "Biologist, 1923-1985, Canada"

|

+- test = "title"

以下都是等价的：

book.author.name

book["author"].name

book.author.["name"]

book["author"]["name"]

n         使用点语法，变量名字有顶层变量一样的限制，但方括号语法没有该限制，由于名字是随意表达式的结果

?         从序列获得数据：和散列的方括号语法语法一样，仅仅是方括号里的表达式值必须是数字；注意：第一个项目的索引是0

?         序列片断：使用[startIndex..endIndex]语法，从序列中获得序列片断（也是序列）；startIndex和endIndex是结果为数字的表达式

?         特殊变量：FreeMarker内定义变量，使用.variablename语法訪问

         字符串操作

?         Interpolation（或连接操作）

n         能够使用${..}（或#{..}）在文本部分插入表达式的值，比如：

${"Hello ${user}!"}

${"${user}${user}${user}${user}"} 

n         能够使用+操作符获得相同的结果

${"Hello " + user + "!"}

${user + user + user + user}

n         ${..}仅仅能用于文本部分，以下的代码是错误的：

Wow!#if>

Wow!#if>

应该写成：

Wow!#if>

?         子串

n         样例（如果user的值为“Big Joe”）：

${user[0]}${user[4]}

${user[1..4]}

结果是（注意第一个字符的索引是0）：

BJ

ig J

         序列操作

?         连接操作：和字符串一样，使用+，以下是一个样例：

- ${user}

#list>

输出结果是：

- Joe

- Fred

- Julia

- Kate

         散列操作

?         连接操作：和字符串一样，使用+，假设具有同样的key，右边的值替代左边的值，比如：

- Joe is ${ages.Joe}

- Fred is ${ages.Fred}

- Julia is ${ages.Julia} 

输出结果是：

- Joe is 30

- Fred is 25

- Julia is 18 

         算术运算

?         ＋、－、×、／、％，以下是一个样例：

${x * x - 100}

${x / 2}

${12 % 10}

输出结果是（如果x为5）：

-75

2.5

2 

?         操作符两边必须是数字，因此以下的代码是错误的：

${3 * "5"}  

?         使用+操作符时，假设一边是数字，一边是字符串，就会自己&