FreeMarker 指令

概念

概念	描述
sequence	序列，对应java里的list、数组等非键值对的集合
hash	键值对的集合，对应java里的map集合
namespace	对一个ftl文件的引用,利用这个名字可以访问到该ftl文件的资源

基本指令

setting指令

该指令用于设置FreeMarker的运行环境,该指令的语法格式如下:<#setting name=value>,在这个格式中,name的取值范围如下所示:

取值	含义
locale	该选项指定该模板所用的国家/语言选项
number_format	指定格式化输出数字的格式
boolean_format	指定两个布尔值的语法格式,默认值是true,false
date_format,time_format,datetime_format	定格式化输出日期的格式
time_zone	设置格式化输出日期时所使用的时区

assign指令

<#assign name=value> 

<#assign name1=value1 name2=value2 ... nameN=valueN> 

<#assign same as above... in namespacehash> 

<#assign name> 
  capture this 
</#assign> 

<#assign name in namespacehash> 
  capture this 
</#assign>
   
   
1
2
3
4
5
6
7
8
9
10
11
12
13
   
   

    
    
   
   
   
   
1
2
3
4
5
6
7
8
9
10
11
12
13

生成变量,并且给变量赋值：

<!-- 示例： -->
给seasons赋予序列值： 
<#assign seasons = ["winter", "spring", "summer", "autumn"]> 

给变量test加1： 
<#assign test = test + 1> 

给my namespage 赋予一个变量bgColor,下面可以通过my.bgColor来访问这个变量： 
<#import "/mylib.ftl" as my> 
<#assign bgColor="red" in my> 

将一段输出的文本作为变量保存在x里： 
<#assign x>Hello ${user}!</#assign> 

同时也支持中文赋值，如： 
<#assign 语法> 
  java
</#assign> 
${语法}
<!-- 输出结果是: -->
java
   
   
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
   
   

    
    
   
   
   
   
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

if指令

这是一个典型的分支控制指令,该指令的作用完全类似于Java语言中的if,if指令的语法格式如下:

<#if condition>... 
<#elseif condition>... 
<#else> ... 
</#if>

<!-- 示例： -->
<#if animals.python.price < animals.elephant.price>
  Pythons are cheaper than elephants today.
<#elseif animals.python.price > animals.elephant.price>
  Elephants are cheaper than pythons today.
<#else>
  Elephants and pythons cost the same today.
</#if>
   
   
1
2
3
4
5
6
7
8
9
10
11
12
13
   
   

    
    
   
   
   
   
1
2
3
4
5
6
7
8
9
10
11
12
13

list指令

list指令是一个迭代输出指令,用于迭代输出数据模型中的集合,list指令的语法格式如下:

<#list sequence as item> 
... 
</#list> 

<!-- 示例： -->
<ul>
<#list misc.fruits as fruit>
  <li>${fruit}
</#list>
</ul>
   
   
1
2
3
4
5
6
7
8
9
10
   
   

    
    
   
   
   
   
1
2
3
4
5
6
7
8
9
10

(list, items[列表条目], sep[分隔符], else) 指令可以一起使用，就像下面这样:

<#list misc.fruits>
  <p>Fruits:
  <ul>
    <#items as fruit>
      <li>${fruit}<#sep> and</#sep>
    </#items>
  </ul>
<#else>
  <p>We have no fruits.
</#list>
   
   
1
2
3
4
5
6
7
8
9
10
   
   

    
    
   
   
   
   
1
2
3
4
5
6
7
8
9
10

include指令

<#include filename> 
    or 
<#include filename options> 

<!-- 示例： -->
File: /common/copyright.ftl
    Copyright 2001-2002 ${me}<br>

<#assign me="Juila Smith"> 
<h1>home page</h1> 
<hr> 
<#include "/common/copyright.ftl" encoding="UTF-8"> 

<!-- 输出结果： --> 
<h1>home page</h1> 
<hr> 
Copyright 2001-2002 Juila Smith 
   
   
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
   
   

    
    
   
   
   
   
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

options包含两个属性：

encoding="GBK" 编码格式 
parse=true     是否作为FTL语法解析,默认是true. false就是以文本方式引入
注意在ftl文件里布尔值都是直接赋值的如parse=true,而不是parse=”true” 

switch指令

它常和 case, default, break指令一起使用

<#switch value> 
  <#case refValue1> 
    ... 
    <#break> 
  <#case refValue2> 
    ... 
    <#break> 
  ... 
  <#case refValueN> 
    ... 
    <#break> 
  <#default> 
    ... 
</#switch>
   
   
1
2
3
4
5
6
7
8
9
10
11
12
13
14
   
   

    
    
   
   
   
   
1
2
3
4
5
6
7
8
9
10
11
12
13
14

compress指令

用来压缩空白空间和空白的行

<#compress> 
  ... 
</#compress>

<!-- 示例： -->
<#assign x = "    moo  \n\n   "> 
(<#compress> 
  1 2  3   4    5 
  ${moo} 
  test only 

  I said, test only 

</#compress>) 

<!-- 输出结果是: -->
(1 2 3 4 5 
moo 
test only 
I said, test only) 
   
   
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
   
   

    
    
   
   
   
   
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

escape, noescape指令

主要使用在相似的字符串变量输出。比如某一个模块的所有字符串输出都必须是html安全的，这个时候就可以使用该表达式：

<#escape identifier as expression> 
  ... 
  <#noescape>...</#noescape> 
  ... 
</#escape>

<!-- 示例： -->
<#escape x as x?html> 
  First name: ${firstName} 
  <#noescape>Last name: ${lastName}</#noescape> 
  Maiden name: ${maidenName} 
</#escape> 

<!-- 相同表达式： -->
First name: ${firstName?html} 
Last name: ${lastName } 
Maiden name: ${maidenName?html} 
   
   
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
   
   

    
    
   
   
   
   
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

import指令

类似于java里的import,它导入文件，然后就可以在当前文件里使用被导入文件里的宏组件

<#import path as hash> 

假设mylib.ftl里定义了宏copyright那么我们在其他模板页面里可以这样使用 
<#import "/libs/mylib.ftl" as my> 

// "my"在freemarker里被称作namespace
<@my.copyright date="1999-2002"/>
   
   
1
2
3
4
5
6
7
   
   

    
    
   
   
   
   
1
2
3
4
5
6
7

内置函数

内置函数就像java中的方法，访问他们必须使用“?”代替，明确其来自哪里。

内置函数	描述	示例
obj?html	html特殊字符转义	& 将会被替换成 &amp
obj?upper_case	大写转换	“John Doe” 将会转换成 “JOHN DOE”
obj?cap_first	首字母大写	“john” 将会转换成 “John”
obj?length	计算字符串长度	“John Doe” length=8
fruits?size	计算序列条目的数量	misc/fruits/orange，banana size=2
<#list animals as animal> list指令下内置函数：
animal?index	位置索引，从0开始
animal?counter	计数器
animal?item_parity	依据计数器，给出”odd”/”even”(奇/偶)字符串	间色表格
一些内置函数需要用参数指定更多行为：
animal.protected?string("Y", "N")	根据animal.protected的布尔值返回”Y”/”N”字符串
animal?item_cycle('lightRow', 'darkRow')	是item_parity早时更通用的变体
fruits?join(", ")	将序列条目转换称字符串形式，转换中在每两个条目中加分隔符”,”	“orange, banana”
obj?starts_with("J")	判断obj是否以字符J开头，返回true/false

处理遗失参数

默认值

<!-- 
    示例：
    当user参数遗失时，使用"visitor"作为默认值 
-->
<h1>Welcome ${user!"visitor"}!</h1>
   
   
1
2
3
4
5
   
   

    
    
   
   
   
   
1
2
3
4
5

忽略处理

<!-- 
    示例：
    当user参数遗失时，忽略处理指令内部操作
-->
<#if user??><h1>Welcome ${user}!</h1></#if>
   
   
1
2
3
4
5
   
   

    
    
   
   
   
   
1
2
3
4
5

参考链接：官方指南