FreeMarker学习笔记——模板开发

FreeMarker 前端开发

1. 定义：FreeMarker是一款模板引擎：即一种基于模板、用来生成输出文本的通用工具。

• FreeMarker并不是一款全面的编程语言，仅仅是使用模板生成文本页面来呈现已经准备好的数据。
• FreeMarker不是Web开发的应用程序框架。它是一个适用于Web应用程序框架中的组件。

2. 数据类型：

• 标量：字符串、数字、布尔型、日期；
• 容器：哈希表（对象）、序列（数组）、集；
• 子程序：方法和函数、用户自定义指令

3. 模板

• 总体结构：Text、Interpolation 插值、FTL tags标签、Comments注释
• 插值由${和}所分隔，仅仅可以在文本中间使用

4. 表达式

• 检索变量：可以从顶层变量中检索、从序列中检索、从哈希表中检索
• 序列操作：连接：users + ["guest"]
  序列切分：使用[firstindex..lastindex]可以获取序列中的一部分。lastindex可以被省略，那么这样将会读取到序列的末尾。
• 哈希表操作：连接：像连接字符串那样，也可以使用+号的方式来连接哈希表。如果两个哈希表含有键相同的项，那么在+号右侧的哈希表中的项目优先。

5. 内建函数：

• html: 字符串中所有的特殊HTML字符都需要用实体引用来代替（比如<代替&lt;）。
• cap_first:字符串的第一个字母变为大写形式
• lower_case:字符串的小写形式
• upper_case:字符串的大写形式
• trim:去掉字符串首尾的空格
• size：序列中元素的个数（序列中才能使用）
• int:数字的整数部分（比如-1.9?int就是-1）（数字才能使用）

6. 处理不存在的值：

• 默认值:不论在哪里引用变量，都可以指定一个默认值来避免变量丢失这种情况，通过在变量名后面跟着一个!和默认值。 使用形式概览：unsafe_expr ! default_expr

  <h1>Welcome ${user!"Anonymous"}!</h1>

• 处理不存在的值：在变量名后面通过放置??来询问FreeMarker一个变量是否存在。使用形式概览：unsafe_expr?? 或 (unsafe_expr)??

  <#if user??><h1>Welcome ${user}!</h1></#if>

7. 自定义指令：

• 使用#macro定义指令，使用@来代替#调用指令。用户自定义指令（换句话说，就是FreeMarker的标签）这种类型的值也是一种子程序，一种可以复用的模板代码段。

• 按经验来说，如果能够实现，请先用自定义指令而不要用函数/方法。输出（返回值）的是标记（HTML,XML等）情况下使用自定义指令

• 自定义指令参数：在macro指令中，宏名称的后面位置是用来定义变量的

<#macro greet person>
    <font size="+2">Hello ${person}!</font>
</#macro>

可以调用如下：

<@greet person="Fred"/> and <@greet person="Batman"/>

8. 自定义指令高级内容：

• 嵌套内容：自定义指令可以嵌套内容，和预定义指令相似：<#if ...>nested content</#if>。

<#macro border>
    <table border=4 cellspacing=0 cellpadding=4><tr><td>
        <#nested>
    </td></tr></table>
</#macro>

    <#nested>指令执行位于开始和结束标记指令之间的模板代码段。写法如下所示：

<@border>The bordered text</@border>

• 宏和循环变量：自定义指令中也可以有循环变量，如下例子：

<#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!

9. 在模板中定义变量：

• 可以访问一个在模板里定义的变量，就像是访问数据模型根上的变量一样。这个变量比定义在数据模型中的同名参数有更高的优先级

• 变量类型：

  • 简单变量: 它能从模板中的任何位置来访问。可以使用assign或macro指令来创建或替换这些变量。
  • 局部变量: 可以使用local指令在宏定义体内创建或替换局部变量。
  • 循环变量: 循环变量是由指令（如list）自动创建的，而且它们只在指令的开始和结束标记内有效

  <#assign x = 1> <#-- 创建变量 x -->
  ${x}
  <#assign x = x + 3> <#-- 替换变量 x -->
  ${x}

  • 局部变量也会隐藏（不是覆盖）同名的简单变量。循环变量也会隐藏（不是覆盖）同名的局部变量和简单变量。有时会发生一个变量隐藏数据模型中的同名变量，但是如果想访问数据模型中的变量，就可以使用特殊变量globals

10. 命名空间：

• 在简单的情况下可以只使用一个命名空间，称之为main namespace主命名空间。当引用了一个模板之后，需要调用模板的命名空间，则需通过import的调用者（本例中的主命名空间）创建一个新的哈希表变量。

<#import "/lib/my_test.ftl" as my>
<#-- 被称为"my"的哈希表就会是那个"大门" -->
<@my.copyright date="1999-2002"/>
${my.mail}

• 数据模型中的变量在任何位置都是可见的。在被引用的ftl文件中也能访问之。