FreeMarker笔记

FreeMarker

• 模板 + 数据模型 = 输出
• 将HTML静态页面中的内容用${...}代替，数据是在FreeMarker之外准备的
• 数据模型：可以被看作是树形结构
  • 哈希表：扮演目录的角色，它用于存储其他变量，通过名称来查找。一种存储变量及其相关且有唯一标识名称的容器。
  • 标量：存储单值的变量。可以是字符串，数字，日期/时间或者布尔值。
  • 序列：像哈希表那样存储子变量，但是子变量没有名字，它们只是列表中的项。存储的变量可以通过数字索引来检索，索引通常从0开始。
• 模版
  • ${...}： FreeMarker将会输出真实的值来替换大括号内的表达式，这样的表达式被称为 interpolation(插值)。里面的内容是字符串。
  • FTL 标签 (FreeMarker模板的语言标签)： FTL标签和HTML标签有一些相似之处，但是它们是FreeMarker的指令，是不会在输出中打印的。 这些标签的名字以 # 开头。(用户自定义的FTL标签则需要使用 @ 来代替 #)
  • 注释： 注释和HTML的注释也很相似， 但是它们使用 <#-- and --> 来标识。 不像HTML注释那样，FTL注释不会出现在输出中(不出现在访问者的页面中)， 因为 FreeMarker会跳过它们。
• 指令
  • if指令：<#if condition> ... <#elseif condition2>... <#else> ... </#if> ：在conditions中可以使用比较运算符
  • list指令：<#list sequence as loopVariable>repeatThis</#list> ：sequence列表，loopVariable循环变量
    • 防止list为空时输出一个空的 <ul></ul>
      
    • 列表分割符<#sep>：<p>Fruits: <#list misc.fruits as fruit>${fruit}<#sep>, </#list>
    • 联合使用指令(list, items, sep, else)
      
  • include指令：<#include "/copyright_footer.html">：在模板中插入其他文件的内容
  • 内建函数：它们并不是数据模型中的东西，是 FreeMarker 在数值上添加的。使用 ?(问号)代替 .(点)来访问它们。
• 处理不存在的变量：
  • 在变量名后面跟着一个 !和默认值。${user!"visitor"}：当 user 不存在于数据模型时, 模板将会将 user 的值表示为字符串 "visitor"
  • 也可以在变量名后面通过放置 ?? 来询问一个变量是否存在。<#if user??><h1>Welcome ${user}!</h1></#if>：将它和 if 指令合并， 那么如果 user 变量不存在的话将会忽略整个问候的代码段。
• 表达式
  • 原生字符串：开始的引号或单引号之前放置字母r。${r"${foo}"} 输出结果：${foo}
  • 哈希表：键和值成对出现并以冒号分隔。比如： { "name": "green mouse", "price": 150 }。
  • 字符串：+ 和使用 ${...} 的规则相同
  • 获取字符：在给定索引值时可以获取字符串中的一个字符，这和 序列的子变量是相似的， 比如 user[0]。
  • 连接：序列的连接可以按照字符串那样使用 + 号来进行
  • 序列切分：使用 seq[range]， 这里 range 是一个值域，可以得到序列的一个切分。结果序列会包含原序列 (seq)中的项。
  • 内建函数：不能使用点 (.)，这里使用问号 (?)来和父对象分隔开。
  • 默认值表达式：unsafe_expr!default_expr
  • 括号：没有括号时， 仅允许表达式的最后部分可以不被定义。(product.color)!"red"
  • 不存在值检测：unsafe_expr??
• 插值
  • 插值的使用格式是： ${expression}
  • 插值是用来给 表达式 插入具体值然后转换为文本(字符串)。
  • 插值仅仅可以在两种位置使用：在 文本区 (比如 <h1>Hello ${name}!</h1>) 和 字符串表达式 (比如 <#include "/footer/${company}.html">)中。
  • 布尔插值：${married?string("yes", "no")}
    • 当想生成JavaScript或其它计算机语言代码部分时，那么可以考虑使用 ${someBoolean?c}("c" 代表计算机)来输出布尔值true/false。 (?c 也可以用来输出给计算机看的数字。)
• 自定义指令
  • macro，它本身不执行，只是用来创建宏变量。 <#macro greet> 和 </#macro>：宏 定义，greet是变量名。<@greet/> : 宏 调用。
  • 增加参数：<#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>
  • 参数可以设置默认值：<#macro greet person color="black"> ... </#macro>。可以在调用时给予覆盖。
  • 自定义指令可以嵌套内容。<#nested>指令
• 模版中三种类型的变量：
  • '简单''变量： 它能从模板中的任何位置来访问，或者从使用 include 指令引入的模板访问。可以使用assign 指令来创建或替换这些变量。因为宏和方法只是变量，那么 macro 指令 和 function 指令也可以用来设置变量，就像 assign 那样。
  • 局部变量：它们只能被设置在 宏定义体内， 而且只在宏内可见。一个局部变量的生命周期只是宏的调用过程。可以使用 local指令 在宏定义体内创建或替换局部变量。
  • 循环变量：循环变量是由如 list 指令自动创建的，而且它们只在指令的开始和结束标记内有效。宏的参数是局部变量而不是循环变量。
  • 全局变量：这是一个高级话题了， 并且这种变量最好别用。即便它们属于不同的命名空间， 全局变量也被所有模板共享，因为它们是被 import进来的， 不同于 include 进来的。那么它们的可见度就像数据模型那样。 全局变量通过 global指令来定义。
• 命名空间
  • <#import "/lib/my_test.ftl" as my>
  • 替换命名空间变量：<#assign mail="[e-mail]" in my>
• 空白处理
  • 剥离空白：如果对模板开启这个特性，那么它就会自动忽略 (也就是不在输出中打印出来)两种典型的多余空白。
  • compress：和剥离空白相反，这个工作是直接基于生成的输出内容， 而不是对于模板进行。