(1)模板 + 数据模型 = 输出FreeMarker基于设计者和程序员是具有不同专业技能的不同个体的观念他们是分工劳动的: 设计者专注于表示——创建HTML文件、图片、Web页面的其它可视化方面; 程序员创建系统,生成设计页面要显示的数据。 经常会遇到的问题是:在Web页面(或其它类型的文档)中显示的信息在设计页面时是无效的,是基于动态数据的。在这里,你可以在HTML(或其它要输出的文本)中加入一些特定指令,FreeMarker会在输出页面给最终用户时,用适当的数据替代这些代码。 下面是一个例子: <html> <head> <title>Welcome!</title> </head> <body> <h1>Welcome ${user}!</h1> <p>Our latest product: <a href="${latestProduct.url}">${latestProduct.name}</a>! </body> </html>这个例子是在简单的HTML中加入了一些由${…}包围的特定代码,这些特定代码是FreeMarker的指令,而包含FreeMarker的指令的文件就称为模板(Template)。 至于user、latestProduct.url和latestProduct.name来自于数据模型(data model)。 数据模型由程序员编程来创建,向模板提供变化的信息,这些信息来自于数据库、文件,甚至于在程序中直接生成。 模板设计者不关心数据从那儿来,只知道使用已经建立的数据模型。 下面是一个可能的数据模型: (root) | +- user = "Big Joe" | +- latestProduct | +- url = "products/greenmouse.html" | +- name = "green mouse"数据模型类似于计算机的文件系统,latestProduct可以看作是目录。 2、数据模型(1)基础在快速入门中介绍了在模板中使用的三种基本对象类型:scalars、hashes 和sequences,其实还可以有其它更多的能力:
通常每个变量只具有上述的一种能力,但一个变量可以具有多个上述能力,如下面的例子: (root) | +- mouse = "Yerri" | +- age = 12 | +- color = "brown">mouse既是scalars又是hashes,将上面的数据模型合并到下面的模板: ${mouse} <#-- use mouse as scalar --> ${mouse.age} <#-- use mouse as hash --> ${mouse.color} <#-- use mouse as hash -->输出结果是: Yerri 12 brown (2)Scalar变量Scalar变量存储单值,可以是:
(3)hashes 、sequences和集合有些变量不包含任何可显示的内容,而是作为容器包含其它变量,者有两种类型:
集合变量通常类似sequences,除非无法访问它的大小和不能使用索引来获得它的子变量;集合可以看作只能由<#list …>指令使用的受限sequences (4)方法方法变量通常是基于给出的参数计算值。 下面的例子假设程序员已经将方法变量avg放到数据模型中,用来计算数字平均值: The average of 3 and 5 is: ${avg(3, 5)} The average of 6 and 10 and 20 is: ${avg(6, 10, 20)} The average of the price of python and elephant is: ${avg(animals.python.price, animals.elephant.price)} (5)宏和变换器宏和变换器变量是用户自定义指令(自定义FTL标记),会在后面讲述这些高级特性 (6)节点节点变量表示为树型结构中的一个节点,通常在XML处理中使用,会在后面的专门章节中讲 3、模板(1)整体结构模板使用FTL(FreeMarker模板语言)编写,是下面各部分的一个组合:
下面是以一个具体模板例子: <html> <head> <title>Welcome!</title> </head> <body> <#-- Greet the user with his/her name --> <h1>Welcome ${user}!</h1> <p>We have these animals: <ul> <#list animals as being> <li>${being.name} for ${being.price} Euros </#list> </ul> </body> </html> 注意事项:
<#if <#include 'foo'>='bar'>...</if>
<h1>Welcome ${user <#-- The name of user -->}!</h1> <p>We have these animals: <ul> <#list <#-- some comment... --> animals as <#-- again... --> being> ...
(2)指令在FreeMarker中,使用FTL标记引用指令。有三种FTL标记,这和HTML标记是类似的:
有两种类型的指令:预定义指令和用户定义指令。 用户定义指令要使用@替换#,如<@mydirective>...</@mydirective>(会在后面讲述)。 FTL标记不能够交叉,而应该正确的嵌套,如下面的代码是错误的: <ul> <#list animals as being> <li>${being.name} for ${being.price} Euros <#if use = "Big Joe"> (except for you) </#list> </#if> <#-- WRONG! --> </ul>如果使用不存在的指令,FreeMarker不会使用模板输出,而是产生一个错误消息。 FreeMarker会忽略FTL标记中的空白字符,如下面的例子: <#list animals as being > ${being.name} for ${being.price} Euros </#list >但是,<、</和指令之间不允许有空白字符。 (3)表达式直接指定值
如果包含特殊字符需要转义,如下面的例子: ${"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: /下面是支持的转义序列:
有一类特殊的字符串称为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"] as x> ${x} </#list>输出的结果是: winter spring summer autumn列表的项目是表达式,所以可以有下面的例子: [2 + 2, [1, 2, 3, 4], "whatnot"]可以使用数字范围定义数字序列,例如2..5等同于[2, 3, 4, 5],但是更有效率,注意数字范围没有方括号 可以定义反递增的数字范围,如5..2
{"name":"green mouse", "price":150}键和值都是表达式,但是键必须是字符串 获取变量
可以使用点语法或方括号语法,假设有下面的数据模型: (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"]使用点语法,变量名字有顶层变量一样的限制,但方括号语法没有该限制,因为名字是任意表达式的结果
序列片断:使用[startIndex..endIndex]语法,从序列中获得序列片断(也是序列);startIndex和endIndex是结果为数字的表达式
字符串操作
可以使用${..}(或#{..})在文本部分插入表达式的值,例如: ${"Hello ${user}!"} ${"${user}${user}${user}${user}"}可以使用+操作符获得同样的结果 ${"Hello " + user + "!"} ${user + user + user + user}${..}只能用于文本部分,下面的代码是错误的: <#if ${isBig}>Wow!</#if> <#if "${isBig}">Wow!</#if>应该写成: <#if isBig>Wow!</#if>
例子(假设user的值为“Big Joe”): ${user[0]}${user[4]} ${user[1..4]}结果是(注意第一个字符的索引是0): BJ ig J序列操作
<#list ["Joe", "Fred"] + ["Julia", "Kate"] as user> - ${user} </#list>输出结果是: - Joe - Fred - Julia - Kate散列操作
<#assign ages = {"Joe":23, "Fred":25} + {"Joe":30, "Julia":18}> - 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"} <#-- WRONG! -->使用+操作符时,如果一边是数字,一边是字符串,就会自动将数字转换为字符串,例如: ${3 + "5"}输出结果是: 35使用内建的int(后面讲述)获得整数部分,例如: ${(x/2)?int} ${1.1?int} ${1.999?int} ${-1.1?int} ${-1.999?int}输出结果是(假设x为5): 2 1 1 -1 -1
使用=(或==,完全相等)测试两个值是否相等,使用!= 测试两个值是否不相等 =和!=两边必须是相同类型的值,否则会产生错误,例如<#if 1 = "1">会引起错误 Freemarker是精确比较,所以对"x"、"x "和"X"是不相等的 对数字和日期可以使用<、<=、>和>=,但不能用于字符串 由于Freemarker会将>解释成FTL标记的结束字符,所以对于>和>=可以使用括号来避免这种情况,例如<#if (x > y)> 另一种替代的方法是,使用lt、lte、gt和gte来替代<、<=、>和>=
&&(and)、||(or)、!(not),只能用于布尔值,否则会产生错误 例子: <#if x < 12 && color = "green"> We have less than 12 things, and they are green. </#if> <#if !hot> <#-- here hot must be a boolean --> It's not hot. </#if>
内建函数的用法类似访问散列的子变量,只是使用“?”替代“.”,下面列出常用的一些函数
html:对字符串进行HTML编码 cap_first:使字符串第一个字母大写 lower_case:将字符串转换成小写 upper_case:将字符串转换成大写 trim:去掉字符串前后的空白字符
size:获得序列中元素的数目
int:取得数字的整数部分(如-1.9?int的结果是-1) 例子(假设test保存字符串"Tom & Jerry"): ${test?html} ${test?upper_case?html}输出结果是: Tom & Jerry TOM & JERRY
(4)InterpolationInterpolation有两种类型:
注意:Interpolation只能用于文本部分
插入字符串值:直接输出表达式结果 插入数字值:根据缺省格式(由#setting指令设置)将表达式结果转换成文本输出;可以使用内建函数string格式化单个Interpolation,下面是一个例子: <#setting number_format="currency"/> <#assign answer=42/> ${answer} ${answer?string} <#-- the same as ${answer} --> ${answer?string.number} ${answer?string.currency} ${answer?string.percent}输出结果是: $42.00 $42.00 42 $42.00 4,200%插入日期值:根据缺省格式(由#setting指令设置)将表达式结果转换成文本输出;可以使用内建函数string格式化单个Interpolation,下面是一个使用格式模式的例子: ${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')'")}输出的结果类似下面的格式: 2003-04-08 21:24:44 Pacific Daylight Time Tue, Apr 8, '03 Tuesday, April 08, 2003, 09:24:44 PM (PDT)插入布尔值:根据缺省格式(由#setting指令设置)将表达式结果转换成文本输出;可以使用内建函数string格式化单个Interpolation,下面是一个例子: <#assign foo=true/> ${foo?string("yes", "no")}输出结果是: yes
mX:小数部分最小X位 MX:小数部分最大X位 例子: <#-- If the language is US English the output is: --> <#assign x=2.582/> <#assign y=4/> #{x; M2} <#-- 2.58 --> #{y; M2} <#-- 4 --> #{x; m1} <#-- 2.6 --> #{y; m1} <#-- 4.0 --> #{x; m1M2} <#-- 2.58 --> #{y; m1M2} <#-- 4.0 --> 4、杂项(1)用户定义指令宏和变换器变量是两种不同类型的用户定义指令,它们之间的区别是宏是在模板中使用macro指令定义,而变换器是在模板外由程序定义,这里只介绍宏
宏是和某个变量关联的模板片断,以便在模板中通过用户定义指令使用该变量,下面是一个例子: <#macro greet> <font size="+2">Hello Joe!</font> </#macro>作为用户定义指令使用宏变量时,使用@替代FTL标记中的# <@greet></@greet>如果没有体内容,也可以使用: <@greet/>
在macro指令中可以在宏变量之后定义参数,如: <#macro greet person> <font size="+2">Hello ${person}!</font> </#macro>可以这样使用这个宏变量: <@greet person="Fred"/> and <@greet person="Batman"/>输出结果是: <font size="+2">Hello Fred!</font> and <font size="+2">Hello Batman!</font> 宏的参数是FTL表达式,所以下面的代码具有不同的意思: <@greet person=Fred/>这意味着将Fred变量的值传给person参数,该值不仅是字符串,还可以是其它类型,甚至是复杂的表达式 可以有多参数,下面是一个例子: <#macro greet person color> <font size="+2" color="${color}">Hello ${person}!</font> </#macro>可以这样使用该宏变量: <@greet person="Fred" color="black"/>其中参数的次序是无关的,因此下面是等价的: <@greet color="black" person="Fred"/>只能使用在macro指令中定义的参数,并且对所有参数赋值,所以下面的代码是错误的: <@greet person="Fred" color="black" background="green"/> <@greet person="Fred"/>可以在定义参数时指定缺省值,如: <#macro greet person color="black"> <font size="+2" color="${color}">Hello ${person}!</font> </#macro>这样<@greet person="Fred"/>就正确了 宏的参数是局部变量,只能在宏定义中有效
用户定义指令可以有嵌套内容,使用<#nested>指令执行指令开始和结束标记之间的模板片断 例子: <#macro border> <table border=4 cellspacing=0 cellpadding=4><tr><td> <#nested> </tr></td></table> </#macro>这样使用该宏变量: <@border>The bordered text</@border>输出结果: <table border=4 cellspacing=0 cellpadding=4><tr><td> The bordered text </tr></td></table> <#nested>指令可以被多次调用,例如: <#macro do_thrice> <#nested> <#nested> <#nested> </#macro> <@do_thrice> Anything. </@do_thrice>输出结果: Anything. Anything. Anything.嵌套内容可以是有效的FTL,下面是一个有些复杂的例子: <@border> <ul> <@do_thrice> <li><@greet person="Joe"/> </@do_thrice> </ul> </@border> }}} 输出结果: <table border=4 cellspacing=0 cellpadding=4><tr><td> <ul> <li><font size="+2">Hello Joe!</font> <li><font size="+2">Hello Joe!</font> <li><font size="+2">Hello Joe!</font> </ul> </tr></td></table>宏定义中的局部变量对嵌套内容是不可见的,例如: <#macro repeat count> <#local y = "test"> <#list 1..count as x> ${y} ${count}/${x}: <#nested> </#list> </#macro> <@repeat count=3>${y?default("?")} ${x?default("?")} ${count?default("?")}</@repeat>输出结果: test 3/1: ? ? ? test 3/2: ? ? ? test 3/3: ? ? ?
用户定义指令可以有循环变量,通常用于重复嵌套内容,基本用法是:作为nested指令的参数传递循环变量的实际值,而在调用用户定义指令时,在<@…>开始标记的参数后面指定循环变量的名字 例子: <#macro repeat count> <#list 1..count as x> <#nested x, x/2, x==count> </#list> </#macro> <@repeat count=4 ; c, halfc, last> ${c}. ${halfc}<#if last> Last!</#if> </@repeat>输出结果: 1. 0.5 2. 1 3. 1.5 4. 2 Last! 指定的循环变量的数目和用户定义指令开始标记指定的不同不会有问题 调用时少指定循环变量,则多指定的值不可见 调用时多指定循环变量,多余的循环变量不会被创建 (2)在模板中定义变量在模板中定义的变量有三种类型:
宏的参数是局部变量,而不是循环变量;局部变量隐藏(而不是覆盖)同名的plain变量;循环变量隐藏同名的局部变量和plain变量,下面是一个例子: <#assign x = "plain"> 1. ${x} <#-- we see the plain var. here --> <@test/> 6. ${x} <#-- the value of plain var. was not changed --> <#list ["loop"] as x> 7. ${x} <#-- now the loop var. hides the plain var. --> <#assign x = "plain2"> <#-- replace the plain var, hiding does not mater here --> 8. ${x} <#-- it still hides the plain var. --> </#list> 9. ${x} <#-- the new value of plain var. --> <#macro test> 2. ${x} <#-- we still see the plain var. here --> <#local x = "local"> 3. ${x} <#-- now the local var. hides it --> <#list ["loop"] as x> 4. ${x} <#-- now the loop var. hides the local var. --> </#list> 5. ${x} <#-- now we see the local var. again --> </#macro>输出结果: 1. plain 2. plain 3. local 4. loop 5. local 6. plain 7. loop 8. loop 9. plain2 内部循环变量隐藏同名的外部循环变量,如: <#list ["loop 1"] as x> ${x} <#list ["loop 2"] as x> ${x} <#list ["loop 3"] as x> ${x} </#list> ${x} </#list> ${x} </#list>输出结果: loop 1 loop 2 loop 3 loop 2 loop 1模板中的变量会隐藏(而不是覆盖)数据模型中同名变量,如果需要访问数据模型中的同名变量,使用特殊变量global,下面的例子假设数据模型中的user的值是Big Joe: <#assign user = "Joe Hider"> ${user} <#-- prints: Joe Hider --> ${.globals.user} <#-- prints: Big Joe --> (3)名字空间通常情况,只使用一个名字空间,称为主名字空间 为了创建可重用的宏、变换器或其它变量的集合(通常称库),必须使用多名字空间,其目的是防止同名冲突
下面是一个创建库的例子(假设保存在lib/my_test.ftl中): <#macro copyright date> <p>Copyright (C) ${date} Julia Smith. All rights reserved. <br>Email: ${mail}</p> </#macro> <#assign mail = "jsmith@acme.com">使用import指令导入库到模板中,Freemarker会为导入的库创建新的名字空间,并可以通过import指令中指定的散列变量访问库中的变量: <#import "/lib/my_test.ftl" as my> <#assign mail="fred@acme.com"> <@my.copyright date="1999-2002"/> ${my.mail} ${mail}输出结果: <p>Copyright (C) 1999-2002 Julia Smith. All rights reserved. <br>Email: jsmith@acme.com</p> jsmith@acme.com fred@acme.com可以看到例子中使用的两个同名变量并没有冲突,因为它们位于不同的名字空间 可以使用assign指令在导入的名字空间中创建或替代变量,下面是一个例子: <#import "/lib/my_test.ftl" as my> ${my.mail} <#assign mail="jsmith@other.com" in my> ${my.mail}输出结果: jsmith@acme.com jsmith@other.com数据模型中的变量任何地方都可见,也包括不同的名字空间,下面是修改的库: <#macro copyright date> <p>Copyright (C) ${date} ${user}. All rights reserved.</p> </#macro> <#assign mail = "${user}@acme.com">假设数据模型中的user变量的值是Fred,则下面的代码: <#import "/lib/my_test.ftl" as my> <@my.copyright date="1999-2002"/> ${my.mail}输出结果: <p>Copyright (C) 1999-2002 Fred. All rights reserved.</p> Fred@acme.com |
FreeMarker学习手册
最新推荐文章于 2023-11-01 17:40:56 发布