freemarker中文手册.docx
《freemarker中文手册.docx》由会员分享，可在线阅读，更多相关《freemarker中文手册.docx（36页珍藏版）》请在冰点文库上搜索。
freemarker中文手册
FreeMarker概述
● FreeMarker是一个模板引擎，一个基于模板生成文本输出的通用工具，使用纯Java编写
● FreeMarker被设计用来生成HTMLWeb页面，特别是基于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、循环结构
● 在模板中创建和改变变量
● 几乎在任何地方都可以使用复杂表达式来指定值
● 命名的宏，可以具有位置参数和嵌套内容
● 名字空间有助于建立和维护可重用的宏库，或者将一个大工程分成模块，而不必担心名字冲突
● 输出转换块：
在嵌套模板片段生成输出时，转换HTML转义、压缩、语法高亮等等；你可以定义自己的转换
3、通用数据模型
● FreeMarker不是直接反射到Java对象，Java对象通过插件式对象封装，以变量方式在模板中显示
● 你可以使用抽象（接口）方式表示对象（JavaBean、XML文档、SQL查询结果集等等），告诉模板开发者使用方法，使其不受技术细节的打扰
4、为Web准备
● 在模板语言中内建处理典型Web相关任务（如HTML转义）的结构
● 能够集成到Model2Web应用框架中作为JSP的替代
● 支持JSP标记库
● 为MVC模式设计：
分离可视化设计和应用程序逻辑；分离页面设计员和程序员
5、智能的国际化和本地化
● 字符集智能化（内部使用UNICODE）
● 数字格式本地化敏感
● 日期和时间格式本地化敏感
● 非US字符集可以用作标识（如变量名）
● 多种不同语言的相同模板
6、强大的XML处理能力
● <#recurse>和<#visit>指令（2.3版本）用于递归遍历XML树
● 在模板中清楚和直觉的访问XML对象模型
FreeMarker设计指南
（1）
1、快速入门
（1）模板+数据模型=输出
● FreeMarker基于设计者和程序员是具有不同专业技能的不同个体的观念
● 他们是分工劳动的：
设计者专注于表示——创建HTML文件、图片、Web页面的其它可视化方面；程序员创建系统，生成设计页面要显示的数据
● 经常会遇到的问题是：
在Web页面（或其它类型的文档）中显示的信息在设计页面时是无效的，是基于动态数据的
● 在这里，你可以在HTML（或其它要输出的文本）中加入一些特定指令，FreeMarker会在输出页面给最终用户时，用适当的数据替代这些代码
● 下面是一个例子：
Welcome!</p><p>Welcome${user}!
Ourlatestproduct:
${latestProduct.name}!
● 这个例子是在简单的HTML中加入了一些由${…}包围的特定代码，这些特定代码是FreeMarker的指令，而包含FreeMarker的指令的文件就称为模板（Template）
● 至于user、latestProduct.url和latestProduct.name来自于数据模型（datamodel）
● 数据模型由程序员编程来创建，向模板提供变化的信息，这些信息来自于数据库、文件，甚至于在程序中直接生成
● 模板设计者不关心数据从那儿来，只知道使用已经建立的数据模型
● 下面是一个可能的数据模型：
（root）
|
+-user="BigJoe"
|
+-latestProduct
|
+-url="products/greenmouse.html"
|
+-name="greenmouse"
● 数据模型类似于计算机的文件系统，latestProduct可以看作是目录，而user、url和name看作是文件，url和name文件位于latestProduct目录中（这只是一个比喻，实际并不存在）
● 当FreeMarker将上面的数据模型合并到模板中，就创建了下面的输出：
Welcome!</p><p>WelcomeBigJoe!
Ourlatestproduct:
greenmouse!
（2）数据模型
● 典型的数据模型是树型结构，可以任意复杂和深层次，如下面的例子：
（root）
|
+-animals
||
|+-mouse
|||
||+-size="small"
|||
||+-price=50
||
|+-elephant
|||
||+-size="large"
|||
||+-price=5000
||
|+-python
||
|+-size="medium"
||
|+-price=4999
|
+-test="Itisatest"
|
+-whatnot
|
+-because="don'tknow"
● 类似于目录的变量称为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指令
<#ifanimals.python.price
Pythonsarecheaperthanelephantstoday.
<#else>
Pythonsarenotcheaperthanelephantstoday.
Ø list指令
Wehavetheseanimals:
| Name | Price <#listanimalsasbeing> |
|---|
| ${being.name} | ${being.price}Euros 输出为： Wehavetheseanimals:
|
| Name | Price |
|---|
| mouse | 50Euros |
| elephant | 5000Euros |
| python | 4999Euros Ø include指令 TestpageTestpageBlahblah... <#include"/copyright_footer.html"> Ø 一起使用指令 Wehavetheseanimals:
|
| Name | Price <#listanimalsasbeing> |
|---|
<#ifbeing.size="large"> ${being.name} <#ifbeing.size="large"> | ${being.price}Euros FreeMarker设计指南（3） 3、模板 （1）整体结构 ● 模板使用FTL（FreeMarker模板语言）编写，是下面各部分的一个组合： Ø 文本： 直接输出 Ø Interpolation： 由${和}，或#{和}来限定，计算值替代输出 Ø FTL标记： FreeMarker指令，和HTML标记类似，名字前加#予以区分，不会输出 Ø 注释： 由<#--和-->限定，不会输出 ● 下面是以一个具体模板例子： [BR] [BR] Welcome!</p><p>[BR][BR] [BR] <#-- Greet the user with his/her name -->[BR] Welcome ${user}![BR] We have these animals: [BR] [BR][BR] ● [BR]是用于换行的特殊字符序列 ● 注意事项： Ø FTL区分大小写，所以list是正确的FTL指令，而List不是；${name}和${NAME}是不同的 Ø Interpolation只能在文本中使用 Ø FTL标记不能位于另一个FTL标记内部，例如： <#if<#include'foo'>='bar'>... Ø 注释可以位于FTL标记和Interpolation内部，如下面的例子： Welcome ${user<#--Thenameofuser-->}![BR] We have these animals: [BR] [BR]<#list <#--somecomment...-->animalsas <#--again...-->being>[BR] ... Ø 多余的空白字符会在模板输出时移除 （2）指令 ● 在FreeMarker中，使用FTL标记引用指令 ● 有三种FTL标记，这和HTML标记是类似的： Ø 开始标记： <#directivenameparameters> Ø 结束标记： Ø 空内容指令标记： <#directivenameparameters/> ● 有两种类型的指令： 预定义指令和用户定义指令 ● 用户定义指令要使用@替换#，如<@mydirective>...（会在后面讲述） ● FTL标记不能够交叉，而应该正确的嵌套，如下面的代码是错误的： <#listanimalsasbeing> - ${being.name}for${being.price}Euros
<#ifuse="BigJoe"> （exceptforyou） <#--WRONG! -->
● 如果使用不存在的指令，FreeMarker不会使用模板输出，而是产生一个错误消息 ● FreeMarker会忽略FTL标记中的空白字符，如下面的例子： <#list[BR] animals as[BR] being[BR] >[BR] ${being.name} for ${being.price} Euros[BR] ● 但是，<、 （3）表达式 ● 直接指定值 Ø 字符串 ⏹ 使用单引号或双引号限定 ⏹ 如果包含特殊字符需要转义，如下面的例子： ${"It's\"quoted\"and thisisabackslash: \\"} ${'It\'s"quoted"and thisisabackslash: \\'} 输出结果是： It's"quoted"and thisisabackslash: \ It's"quoted"and thisisabackslash: \ ⏹ 下面是支持的转义序列： 转义序列 含义 \" 双引号（u0022） \' 单引号（u0027） \\ 反斜杠（u005C） \n 换行（u000A） \r Return（u000D） \t Tab（u0009） \b Backspace（u0008） \f Formfeed（u000C） \l < \g > \a & \{ { \xCode 4位16进制Unicode代码 ⏹ 有一类特殊的字符串称为raw字符串，被认为是纯文本，其中的\和{等不具有特殊含义，该类字符串在引号前面加r，下面是一个例子： ${r"${foo}"} ${r"C: \foo\bar"} 输出的结果是： ${foo} C: \foo\bar Ø 数字 ⏹ 直接输入，不需要引号 ⏹ 精度数字使用“.”分隔，不能使用分组符号 ⏹ 目前版本不支持科学计数法，所以“1E3”是错误的 ⏹ 不能省略小数点前面的0，所以“.5”是错误的 ⏹ 数字8、+8、08和8.00都是相同的 Ø 布尔值 ⏹ true和false，不使用引号 Ø 序列 ⏹ 由逗号分隔的子变量列表，由方括号限定，下面是一个例子： <#list["winter","spring","summer","autumn"]asx> ${x} 输出的结果是： winter spring summer autumn ⏹ 列表的项目是表达式，所以可以有下面的例子： [2+2,[1,2,3,4],"whatnot"] ⏹ 可以使用数字范围定义数字序列，例如2..5等同于[2,3,4,5]，但是更有效率，注意数字范围没有方括号 ⏹ 可以定义反递增的数字范围，如5..2 Ø 散列（hash） ⏹ 由逗号分隔的键/值列表，由大括号限定，键和值之间用冒号分隔，下面是一个例子： {"name": "green mouse","price": 150} ⏹ 键和值都是表达式，但是键必须是字符串 ● 获取变量 Ø 顶层变量： ${variable}，变量名只能是字母、数字、下划线、$、@和#的组合，且不能以数字开头 Ø 从散列中获取数据 ⏹ 可以使用点语法或方括号语法，假设有下面的数据模型： （root） | +-book || |+-title="Breedinggreenmouses" || |+-author || |+-name="JuliaSmith" || |+-info="Biologist,1923-1985,Canada" | +-test="title" 下面都是等价的： book.author.name book["author"].name book.author.["name"] book["author"]["name"] ⏹ 使用点语法，变量名字有顶层变量一样的限制，但方括号语法没有该限制，因为名字是任意表达式的结果 Ø 从序列获得数据： 和散列的方括号语法语法一样，只是方括号中的表达式值必须是数字；注意： 第一个项目的索引是0 Ø 序列片断： 使用[startIndex..endIndex]语法，从序列中获得序列片断（也是序列）；startIndex和endIndex是结果为数字的表达式 Ø 特殊变量： FreeMarker内定义变量，使用.variablename语法访问 ● 字符串操作 Ø Interpolation（或连接操作） ⏹ 可以使用${..}（或#{..}）在文本部分插入表达式的值，例如： ${"Hello${user}! "} ${"${user}${user}${user}${user}"} ⏹ 可以使用+操作符获得同样的结果 ${"Hello"+user+"! "} ${user+user+user+user} ⏹ ${..}只能用于文本部分，下面的代码是错误的： <#if${isBig}>Wow! <#if"${isBig}">Wow! 应该写成： <#ifisBig>Wow! Ø 子串 ⏹ 例子（假设user的值为“BigJoe”）： ${user[0]}${user[4]} ${user[1..4]} 结果是（注意第一个字符的索引是0）： BJ igJ ● 序列操作 Ø 连接操作： 和字符串一样，使用+，下面是一个例子： <#list["Joe","Fred"]+["Julia","Kate"]asuser> -${user} 输出结果是： -Joe -Fred -Julia -Kate ● 散列操作 Ø 连接操作： 和字符串一样，使用+，如果具有相同的key，右边的值替代左边的值，例如： <#assignages={"Joe": 23,"Fred": 25}+{"Joe": 30,"Julia": 18}> -Joeis${ages.Joe} -Fredis${ages.Fred} -Juliais${ages.Julia} 输出结果是： -
展开阅读全文
相关搜索
资源标签
|