章节内容如下:
总体结构
指令
表达式
插值
一、总体结构
实际上你用程序语言编写的程序就是模板,模板也被称为FTL(代表FreeMarker模板语言)。这是为编写模板设计的非常简单的编程语言。
模板(FTL编程)是由如下部分混合而成的:
Text文本:文本会照着原样来输出。
Interpolation 插值:这部分的输出会被计算的值来替换。插值由${和}所分隔(或者#{和},这种已经不建议再使用了)。
FTL tags标签:FTL标签和HTML标签很相似,但是它们却是给FreeMarker的指示而且不会打印在输出内容中。
Comments注释:注释和HTML的注释也很相似,但它们是由<#--和-->来分隔的。注释会被FreeMarker所忽略,更不会在输出内容中显示。
我们来看一个具体的模板,其中的内容已经用颜色来标记了:文本,插值,FTL标签,注释,为了可视地看到换行符而使用了[BR]。
FTL 是区分大小写的。list是指令的名称而List就不是,类似地${name}和${Name}或者${NAME}也是不同的。
应该意识到非常重要的一点:插值仅仅可以在文本中间使用(也可以在字符串表达式
中,后续介绍)。
FTL标签不可以在其他FTL标签和插值中使用。下面这样写就是错的: <#if <#include 'foo'>='bar'>...</#if>
注释可以放在FTL标签和插值中间。比如:
注意:
如果您已经自己尝试了上面所有的示例的话,那么你也许会注意一些空格、制表符和换行符从模板输出中都不见了,尽管我们之前已经说了文本是按照原样输出的。现在不用为此而计较,这是由于“空格剥离”特性在起作用,它当然会自动去除一些多余的空格,制表符和换行符了。这个特性后续也会解释到。
二、指令
使用FTL标签来调用directives指令,比如调用list 指令。在语法上我们使用了两个标签:<#list animals as being>和</#list>。
标签分为两种:
- 开始标签:<#directivename parametes>
- 结束标签:</#directivename>
除了标签以#开头外,其他都和HTML,XML的语法很相似。如果标签没有嵌套内容(在开始标签和结束标签之内的内容),那么可以只使用开始标签。例如<#if something>...</#if>,但是FreeMarker 知道<#include something>中include指令没有可嵌套的内容。
parameters的格式由directivename来决定。
事实上,指令有两种类型:预定义指令和用户自定义指令。对于用户自定义的指令使用@来代替#,比如<@mydirective parameters>...</@mydirective>。更深的区别在于如果指令没有嵌套内容,那么必须这么使用<@mydirective parameters />,这和XML语法很相似(例如<img ... />).但是用户自定义指令是后面要讨论的高级主题。
像HTML标签一样,FTL标签必须正确的嵌套使用。下面这段示例代码就是错的,因为if 指令在list 指令嵌套内容的内外都有:
<ul>
<#list animals as being>
<li>${being.name} for ${being.price} Euros
<#if user == "Big Joe">
(except for you)
</#list> <#-- WRONG! The "if" has to be closed first. -->
</#if>
</ul>
注意一下FreeMarker仅仅关心FTL标签的嵌套而不关心HTML标签的嵌套,它只会把HTML看做是相同的文本,不会来解释HTML。
如果你尝试使用一个不存在的指令(比如你输错了指令的名称),FreeMarker就会拒绝执行模板,同时抛出错误信息。
FreeMarker会忽略FTL标签中的多余空白标记,所以你也可以这么来写代码:
<#list[BR]
animals as[BR]
being[BR]
>[BR]
${being.name} for ${being.price} Euros[BR]
</#list >
当然,也不能在<,</和指令名中间插入空白标记。
指令列表和详细介绍可以参照指令参考部分(但是我建议先看表达章节)。
注意:
通过配置后,FreeMarker可以在FTL标签和FTL注释中,使用[和]来代替<和>,就像[#if user == "Big Joe"]...[/#if]。然而我们不建议这样来使用。要获取更多信息,请参考:废弃deepFTL结构/老实FTL语法。
三、表达式