三、FreeMarker 模版开发指南 第三章 模版

时间:2022-11-24 18:35:38

章节内容如下:
 
  总体结构
  指令
  表达式
  插值

一、总体结构

  实际上你用程序语言编写的程序就是模板,模板也被称为FTL(代表FreeMarker模板语言)。这是为编写模板设计的非常简单的编程语言。
  模板(FTL编程)是由如下部分混合而成的:

  Text文本:文本会照着原样来输出。
  Interpolation 插值:这部分的输出会被计算的值来替换。插值由${和}所分隔(或者#{和},这种已经不建议再使用了)。
  FTL  tags标签:FTL标签和HTML标签很相似,但是它们却是给FreeMarker的指示而且不会打印在输出内容中。
  Comments注释:注释和HTML的注释也很相似,但它们是由<#--和-->来分隔的。注释会被FreeMarker所忽略,更不会在输出内容中显示。
  

  我们来看一个具体的模板,其中的内容已经用颜色来标记了:文本,插值,FTL标签,注释,为了可视地看到换行符而使用了[BR]。

三、FreeMarker 模版开发指南 第三章 模版

  FTL 是区分大小写的。list是指令的名称而List就不是,类似地${name}和${Name}或者${NAME}也是不同的。

  应该意识到非常重要的一点:插值仅仅可以在文本中间使用(也可以在字符串表达式
中,后续介绍)。
  FTL标签不可以在其他FTL标签和插值中使用。下面这样写就是错的: <#if <#include 'foo'>='bar'>...</#if>
  注释可以放在FTL标签和插值中间。比如:

三、FreeMarker 模版开发指南 第三章 模版

  注意:
  如果您已经自己尝试了上面所有的示例的话,那么你也许会注意一些空格、制表符和换行符从模板输出中都不见了,尽管我们之前已经说了文本是按照原样输出的。现在不用为此而计较,这是由于“空格剥离”特性在起作用,它当然会自动去除一些多余的空格,制表符和换行符了。这个特性后续也会解释到。

二、指令

  使用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语法。

三、表达式