学习FreeMaker（基础篇）

一直以来，都有听说过FreeMaker，最近抽空仔细研究了一下这个东东，在这里我也把自己的心得给分享出来吧。

FreeMaker简介
FreeMaker其实是一种比较简单的网页展示技术，说白了就是网页模板和数据模型的结合体。这种结合模式的好处就是，分离了网页界面设计人员和编程人员的工作，让他们各司其职。

据个人理解，FreeMaker大致的工作方式是，网页模板里面嵌入了数据模型中的数据、FreeMake自定义流程控制语言、FreeMake自定义的操作函数等等，在装载网页的时候，FreeMaker模板自动从数据模型中提取数据，并解释整个网页为我们熟知的HTML页面。

数据模型(The Data Model)
首先看看下面的两个例子（注：这里只是用示意图的形式来展示数据模型的概念，此处的图片并不代表源码中的一个文本性质的文件）： 

这种结构有点类似于目录树结构，其中，String性质的属性值我们都用双引号或单引号围起来，如"mouse" or 'mouse'表示String类型。同理，Number数字则不需要任何引号，如字符"50"和50分别是两种不同性质的节点。

在这里，有以下几个FreeMaker术语需要了解：
●hashes：处于“目录”位置的节点。如左图中的root, animals, mouse, elephant, python, whatnot；
●scalars：叶子节点，即处于“文件”位置的节点。如左图中的size, price, test, because，如果你要访问price节点，我们可以通过如下的方式在HTML代码中嵌入${animals.mouse.price}，scalars可以有多种类型的值。
●sequences：类似于hashes，但是它不用名字来命名子节点，而是把该子节点写作为一个数字序列，相关的scalars置于这些数字序列下。如右图中的animals和whatnot.fruits，如果你要访问第一个动物的name，那么可以写为${animals[0].name}；访问第2个水果，则写为${whatnot.fruits[1]}。

网页模板(Template)
我们在简介中已经初步介绍了一下网页模板的概念。网页模板事实上就是一个静态的HTML文件，里面包含了以下几种元素：
●Interpolation：具体的格式为${expression}，在数据模型中，我们已经提到了这个特殊的符号，主要还是用来容纳模板中节点内容的。此外，也可以采用#{expression}或#{expression; format}来展示数字(如#{x; m1M3}表示x小数部分最小长度为1最大长度为3，多出部分四舍五入)。
●FTL tags(FreeMarker Template Language tags)：简单的说，就是FreeMaker的子定义流程控制语言和操作函数，他们均以HTML tag的形式存在，只不过采用了#和@的标志符来区别于普通的HTML标记。FTL tags 不能互相嵌套，如<#if <#include 'foo'>='bar'>...是一个错误的用法。
FreeMaker默认使用尖括号来涵盖FTL tags的内容，但是系统也可以统一使用方括号来修饰FTL tags，两者不能同时混用(注：每一个网页Template可以在最开始处使用<#ftl>或[#ftl]来标示整个模板的基本配置，因此后文中的所有的tags的括号都应该和ftl的一致，不一致的FTL tags一律视为普通的Text)。
●注释(Comments)：类似于HTML的注释，表示方式为 <#-- and --> (注意：不是<!----><!---->)，嵌入在里面的所有内容均不会被FreeMaker本身所解释。此外，Comments可以处于FTL tags和Interpolation中间。
除了以上三种之外，其他的网页代码都不会被FreeMaker本身所解释，而最终保留并直接呈现出来，FreeMaker称之为Text。




表达式(Expressions)

1. 基础数据类型

String: 由前后引号括起来的字符串，如："Green Mouse", "I am \"tailsherry\"!", r"C:\raw\string"，和其他的编程语言一样，FreeMaker的String类型也支持转义字符：

转义字符

详细描述

\"	双引号(u0022)
\'	单引号(u0027)
\\	反斜杠 (u005C)
\n	换行 (u000A)
\r	回车 (u000D)
\t	TAB键 (u0009)
\b	退格(u0008)
\f	Form feed (u000C)
\l	小于号: <
\g	大于号: >
\a	&符号: &
\{	大括号: {
\xCode	16进制的Unicode (UCS)

备注：
●在转义符\x之后，应该是1至4个十六进制的数值，如："\xA9 1999-2001", "\x0A9 1999-2001", "\x00A9 1999-2001"均表示内嵌一个Copy Right标志。如果\x之后超出4个数值，那么FreeMaker就成白痴了； :P
●另外，在String类型中，我们还有一个"生字符串"(Raw string literals)的概念。在生字符串中，\和${都失去FreeMaker本身的意义了，直接当作了普通的文本处理。表示生字符串的方式是，在第一个引号之前，加上一个字母r，如r"C:\foo\bar"输出就应该是"C:\foo\bar"；
●如何引用字符串？我们常用的方式有${"Hello ${user}!"}，此处假设user是tailsherry，那么输出结果为Hello tailsherry!。同样，你也可以直接用+连接已有的字符串${"Hello" + user + "!"}，此结果和前者一样；
●如何取用一个字符串中的部分序列？可以用${user[0]}, ${user[1..4]}, ${user[5..]}。当然，推荐的还是用内嵌函数substring来解决了${user?substring(0,0)}, ${user?substring(1,4)}, ${user?substring(5)}；
●一些正确的用法：〈h1〉Hello ${name}!〈/h1〉    <#include "/footer/${company}.html">；
●一些典型的错误用法：<#if ${isBig}>Wow!    <#if "${isBig}">Wow!。

Number: 在模板中直接用数字表示，如：150 or -90.05 or +0.001。

备注：
●数字中只能用.号，不可以用其他的符号(如,)来分割为小数；
●你可以用+和-来标示该数字为正数和负数；
●到目前为止，Number还不支持科学计数法，如1E3是错误的用法。

Date: 分为Date, Time, DateTime(TimeStamp)三种格式，这里不讨论具体的Date的实现规则，这是一个比较复杂的问题;

Boolean: 布尔值，表示逻辑上的true/false，实际使用的时候请不要用引号把true/false涵括起来。

Sequences: 序列值，可以理解为一个java的枚举/集合类型。常用的形式为：["winter", "spring", "summer", "autumn"]。

备注：
●序列中的子项目可以是一个任意的Expression，如[2 + 2, [1, 2, 3, 4], "whatnot"]；
●你可以用区间的方式来表示一组连续的数字，如2..5 (注意了，这里的2..5没有前后方括号的)，该序列即等同于[2, 3, 4, 5] (ps: 一般来说，前者更加有效率一点，因为它占用的内存小一点，访问速度更快)；同样，你也可以倒过来这个序列使用5..2，或者干脆省略掉结束数5.., 5,6,7,... 表示从5到无穷大！
●可以合并两个Sequences序列，如["Joe", "Fred"] + ["Julia", "Kate"] as user，那么${user}的将是一个新的序列，其值为["Joe", "Fred", "Julia", "Kate"]；
●建议不要多次反复合并Sequences序列，这样降低系统对合并后序列的访问速度。

Hashes: 传统的键/值对方式，类似于java的Map，表示形式为{"name":"green mouse", "price":150}，其中[值]部分可以是一个任意的Expression。

备注：
●Hashes可以类似于Sequences一样进行两者合并，如{"Joe":23, "Fred":25} + {"Joe":30, "Julia":18}。如果前后存在有两个相同的[键]，那么合并后以+号右边的Hashes对应的[值]为基准；
●同样，建议不要多次反复合并Hashes，这样降低系统对合并后Hashes的访问速度。

 

 

2. 数学运算
类似于java的数学运算，加+减-乘*除/余%，没有什么比较特别的地方。
数学预算仅限于Number类型，如果尝试用String和Number进行运算，将会出现异常！当然，有一个例外，如果你使用${3 + "5"}，那这里的数字会自动转变为String来处理，事实上这里的+就是一个字符串的连接符了，返回的结果应该就是字串"35"了。

3. 逻辑运算
类似于java的逻辑运算，=,==,!=,〉,〈,〉=,〈=,||,&&,!等等，许多人对这些符号都耳熟能详，就不一一介绍了。

有几点需要注意的地方：
●=和==在FreeMaker中都可以用来等值判断；
●!=,〉,〈,〉=,〈=仅用于Number和Date类型的比较，如果有String参与比较，将会抛出异常；
●由于〉,〈,〉=,〈=中的〈〉等同于tags中的前后封闭符，这里应该分别用>,<,>e, ●使用expression??，可以判断这个expression是否有指定值，如果有值，那么返回true，否则false。可以结合[5 默认值设定]部分理解。
 

4. 内嵌函数(Built-ins)
不同于一般的java和c的访问连接符，这里用?顶替.来处理。如${test?html}、${test?upper_case?html}等。

简单列举一下几个常见的内嵌函数：
●String字符串函数
html: 将特殊的HTML字符转为转义符号，常见的〈〉&等变化为<>&等。
cap_first: 将String的第一个字母大写。
lower_case: 将String的所有字母小写。
upper_case: 将String的所有字母大写。
trim: 去除String前后的空白符。

●Sequence序列函数
size: 标志Seuqence的大小。

●Number数值函数
int: 获得一个Number的整数部分的值，如-1.9?int返回-1。

5. 默认值设定(Default value)
FreeMaker用一个!符号表示某个expression的默认值，如${mouse!"No mouse."}。

有几点需要注意的地方：
●如果!后面的默认值没有内容，那么默认为一个空String或空Sequence或空Hash。注意，对于Number和Boolean如果让默认值为0和false，必须显式的指定默认值，不可以省略；
●如${product.color!"red"}只保证了最后一个color的默认值为red，如果product没有指定，同样会引发错误。但是， (product.color)!"red" 却一定保证这个值为red，不管product或color指不指定。

6. 操作符的优先级(Operator precedence)
所有FreeMaker操作符的优先级类似于java, C等高级语言，除了一些FreeMaker本身独有的操作符之外。

操作符

详细内容

前缀符	[subvarName] [subStringRange] . ? (methodParams) expr!default expr! expr??
正负否	+expr -expr !expr
乘除余	* / %
加减	+ -
大小比较	〈  〉 〈=  〉= (and quivalents: gt, lt, etc.)
等于比较	== != (and equivalents: =)
逻辑与	&&
逻辑或	||
数字区间	..

通过以上的一些介绍，也算是对FreeMaker有了一个大致的了解，在后续的文章中，我将继续和大家一起深入探讨FreeMaker。