?

FreeMarker概述

l???????? FreeMarker是一個模板引擎，一個基于模板生成文本輸出的通用工具，使用純Java編寫

l???????? FreeMarker被設計用來生成HTML Web頁面，特別是基于MVC模式的應用程序

l???????? 雖然FreeMarker具有一些編程的能力，但通常由Java程序準備要顯示的數據，由FreeMarker生成頁面，通過模板顯示準備的數據（如下圖）

l???????? FreeMarker不是一個Web應用框架，而適合作為Web應用框架一個組件

l???????? FreeMarker與容器無關，因為它并不知道HTTP或Servlet；FreeMarker同樣可以應用于非Web應用程序環境

l???????? FreeMarker更適合作為Model2框架（如Struts）的視圖組件，你也可以在模板中使用JSP標記庫

l???????? FreeMarker是免費的

?

?

1、通用目標

l???????? 能夠生成各種文本：HTML、XML、RTF、Java源代碼等等

l???????? 易于嵌入到你的產品中：輕量級；不需要Servlet環境

l???????? 插件式模板載入器：可以從任何源載入模板，如本地文件、數據庫等等

l???????? 你可以按你所需生成文本：保存到本地文件；作為Email發送；從Web應用程序發送它返回給Web瀏覽器

?

2、強大的模板語言

l???????? 所有常用的指令：include、if/elseif/else、循環結構

l???????? 在模板中創建和改變變量

l???????? 幾乎在任何地方都可以使用復雜表達式來指定值

l???????? 命名的宏，可以具有位置參數和嵌套內容

l???????? 名字空間有助于建立和維護可重用的宏庫，或者將一個大工程分成模塊，而不必擔心名字沖突

l???????? 輸出轉換塊：在嵌套模板片段生成輸出時，轉換HTML轉義、壓縮、語法高亮等等；你可以定義自己的轉換

?

3、通用數據模型

l???????? FreeMarker不是直接反射到Java對象，Java對象通過插件式對象封裝，以變量方式在模板中顯示

l???????? 你可以使用抽象（接口）方式表示對象（JavaBean、XML文檔、SQL查詢結果集等等），告訴模板開發者使用方法，使其不受技術細節的打擾

?

4、為Web準備

l???????? 在模板語言中內建處理典型Web相關任務（如HTML轉義）的結構

l???????? 能夠集成到Model2 Web應用框架中作為JSP的替代

l???????? 支持JSP標記庫

l???????? 為MVC模式設計：分離可視化設計和應用程序邏輯；分離頁面設計員和程序員

?

5、智能的國際化和本地化

l???????? 字符集智能化（內部使用UNICODE）

l???????? 數字格式本地化敏感

l???????? 日期和時間格式本地化敏感

l???????? 非US字符集可以用作標識（如變量名）

l???????? 多種不同語言的相同模板

?

6、強大的XML處理能力

l???????? <#recurse> 和<#visit>指令（2.3版本）用于遞歸遍歷XML樹

l???????? 在模板中清楚和直覺的訪問XML對象模型

?

FreeMarker設計指南(1)

?

?

?

1、快速入門

（1）模板 + 數據模型 = 輸出

l???????? FreeMarker基于設計者和程序員是具有不同專業技能的不同個體的觀念

l???????? 他們是分工勞動的：設計者專注于表示——創建HTML文件、圖片、Web頁面的其它可視化方面；程序員創建系統，生成設計頁面要顯示的數據

l???????? 經常會遇到的問題是：在Web頁面（或其它類型的文檔）中顯示的信息在設計頁面時是無效的，是基于動態數據的

l???????? 在這里，你可以在HTML（或其它要輸出的文本）中加入一些特定指令，FreeMarker會在輸出頁面給最終用戶時，用適當的數據替代這些代碼

l???????? 下面是一個例子：

l???????? 這個例子是在簡單的HTML中加入了一些由${…}包圍的特定代碼，這些特定代碼是FreeMarker的指令，而包含FreeMarker的指令的文件就稱為模板（Template）

l???????? 至于user、latestProduct.url和latestProduct.name來自于數據模型（data model）

l???????? 數據模型由程序員編程來創建，向模板提供變化的信息，這些信息來自于數據庫、文件，甚至于在程序中直接生成

l???????? 模板設計者不關心數據從那兒來，只知道使用已經建立的數據模型

l???????? 下面是一個可能的數據模型：

l???????? 數據模型類似于計算機的文件系統，latestProduct可以看作是目錄，而user、url和name看作是文件，url和name文件位于latestProduct目錄中（這只是一個比喻，實際并不存在）

l???????? 當FreeMarker將上面的數據模型合并到模板中，就創建了下面的輸出：

（2）數據模型

l???????? 典型的數據模型是樹型結構，可以任意復雜和深層次，如下面的例子：

l???????? 類似于目錄的變量稱為hashes，包含保存下級變量的唯一的查詢名字

l???????? 類似于文件的變量稱為scalars，保存單值

l???????? scalars保存的值有兩種類型：字符串（用引號括起，可以是單引號或雙引號）和數字（不要用引號將數字括起，這會作為字符串處理）

l???????? 對scalars的訪問從root開始，各部分用“.”分隔，如animals.mouse.price

l???????? 另外一種變量是sequences，和hashes類似，只是不使用變量名字，而使用數字索引，如下面的例子：

l???????? 這種對scalars的訪問使用索引，如animals[0].name

（3）模板

l???????? 在FreeMarker模板中可以包括下面三種特定部分：

????????? ${…}：稱為interpolations，FreeMarker會在輸出時用實際值進行替代

????????? FTL標記（FreeMarker模板語言標記）：類似于HTML標記，為了與HTML標記區分，用#開始（有些以@開始，在后面敘述）

????????? 注釋：包含在<#--和-->（而不是<!--和-->）之間

l???????? 下面是一些使用指令的例子：

????????? if指令

????????? list指令

輸出為：

????????? include指令

????????? 一起使用指令

FreeMarker設計指南(3)

?

?

?

3、模板

（1）整體結構

l???????? 模板使用FTL（FreeMarker模板語言）編寫，是下面各部分的一個組合：

????????? 文本：直接輸出

????????? Interpolation：由${和}，或#{和}來限定，計算值替代輸出

????????? FTL標記：FreeMarker指令，和HTML標記類似，名字前加#予以區分，不會輸出

????????? 注釋：由<#--和-->限定，不會輸出

l???????? 下面是以一個具體模板例子：

l???????? [BR]是用于換行的特殊字符序列

l???????? 注意事項：

????????? FTL區分大小寫，所以list是正確的FTL指令，而List不是；${name}和${NAME}是不同的

????????? Interpolation只能在文本中使用

????????? FTL標記不能位于另一個FTL標記內部，例如：

????????? 注釋可以位于FTL標記和Interpolation內部，如下面的例子：

????????? 多余的空白字符會在模板輸出時移除

（2）指令

l???????? 在FreeMarker中，使用FTL標記引用指令

l???????? 有三種FTL標記，這和HTML標記是類似的：

????????? 開始標記：<#directivename parameters>

????????? 結束標記：</#directivename>

????????? 空內容指令標記：<#directivename parameters/>

l???????? 有兩種類型的指令：預定義指令和用戶定義指令

l???????? 用戶定義指令要使用@替換#，如<@mydirective>...</@mydirective>（會在后面講述）

l???????? FTL標記不能夠交叉，而應該正確的嵌套，如下面的代碼是錯誤的：

l???????? 如果使用不存在的指令，FreeMarker不會使用模板輸出，而是產生一個錯誤消息

l???????? FreeMarker會忽略FTL標記中的空白字符，如下面的例子：

l???????? 但是，<、</和指令之間不允許有空白字符

（3）表達式

l???????? 直接指定值

????????? 字符串

n???????? 使用單引號或雙引號限定

n???????? 如果包含特殊字符需要轉義，如下面的例子：

輸出結果是：

n???????? 下面是支持的轉義序列：

n???????? 有一類特殊的字符串稱為raw字符串，被認為是純文本，其中的\和{等不具有特殊含義，該類字符串在引號前面加r，下面是一個例子：

輸出的結果是：

????????? 數字

n???????? 直接輸入，不需要引號

n???????? 精度數字使用“.”分隔，不能使用分組符號

n???????? 目前版本不支持科學計數法，所以“1E3”是錯誤的

n???????? 不能省略小數點前面的0，所以“.5”是錯誤的

n???????? 數字8、+8、08和8.00都是相同的

????????? 布爾值

n???????? true和false，不使用引號

????????? 序列

n???????? 由逗號分隔的子變量列表，由方括號限定，下面是一個例子：

輸出的結果是：

n???????? 列表的項目是表達式，所以可以有下面的例子：

n???????? 可以使用數字范圍定義數字序列，例如2..5等同于[2, 3, 4, 5]，但是更有效率，注意數字范圍沒有方括號

n???????? 可以定義反遞增的數字范圍，如5..2

????????? 散列（hash）

n???????? 由逗號分隔的鍵/值列表，由大括號限定，鍵和值之間用冒號分隔，下面是一個例子：

n???????? 鍵和值都是表達式，但是鍵必須是字符串

l???????? 獲取變量

????????? 頂層變量： ${variable}，變量名只能是字母、數字、下劃線、$、@和#的組合，且不能以數字開頭

????????? 從散列中獲取數據

n???????? 可以使用點語法或方括號語法，假設有下面的數據模型：

下面都是等價的：

n???????? 使用點語法，變量名字有頂層變量一樣的限制，但方括號語法沒有該限制，因為名字是任意表達式的結果

????????? 從序列獲得數據：和散列的方括號語法語法一樣，只是方括號中的表達式值必須是數字；注意：第一個項目的索引是0

????????? 序列片斷：使用[startIndex..endIndex]語法，從序列中獲得序列片斷（也是序列）；startIndex和endIndex是結果為數字的表達式

????????? 特殊變量：FreeMarker內定義變量，使用.variablename語法訪問

l???????? 字符串操作

????????? Interpolation（或連接操作）

n???????? 可以使用${..}（或#{..}）在文本部分插入表達式的值，例如：

n???????? 可以使用+操作符獲得同樣的結果

n???????? ${..}只能用于文本部分，下面的代碼是錯誤的：

應該寫成：

????????? 子串

n???????? 例子（假設user的值為“Big Joe”）：

結果是（注意第一個字符的索引是0）：

l???????? 序列操作

????????? 連接操作：和字符串一樣，使用+，下面是一個例子：

輸出結果是：

l???????? 散列操作

????????? 連接操作：和字符串一樣，使用+，如果具有相同的key，右邊的值替代左邊的值，例如：

輸出結果是：

l???????? 算術運算

????????? ＋、－、×、／、％，下面是一個例子：

輸出結果是（假設x為5）：

????????? 操作符兩邊必須是數字，因此下面的代碼是錯誤的：

????????? 使用+操作符時，如果一邊是數字，一邊是字符串，就會自動將數字轉換為字符串，例如：

輸出結果是：

????????? 使用內建的int（后面講述）獲得整數部分，例如：

輸出結果是（假設x為5）：

l???????? 比較操作符

????????? 使用=（或==，完全相等）測試兩個值是否相等，使用!= 測試兩個值是否不相等

????????? =和!=兩邊必須是相同類型的值，否則會產生錯誤，例如<#if 1 = "1">會引起錯誤

????????? Freemarker是精確比較，所以對"x"、"x? "和"X"是不相等的

????????? 對數字和日期可以使用<、<=、>和>=，但不能用于字符串

????????? 由于Freemarker會將>解釋成FTL標記的結束字符，所以對于>和>=可以使用括號來避免這種情況，例如<#if (x > y)>

????????? 另一種替代的方法是，使用lt、lte、gt和gte來替代<、<=、>和>=

l???????? 邏輯操作符

????????? &&（and）、||（or）、!（not），只能用于布爾值，否則會產生錯誤

????????? 例子：

l???????? 內建函數

????????? 內建函數的用法類似訪問散列的子變量，只是使用“?”替代“.”，下面列出常用的一些函數

????????? 字符串使用的：

n???????? html：對字符串進行HTML編碼

n???????? cap_first：使字符串第一個字母大寫

n???????? lower_case：將字符串轉換成小寫

n???????? upper_case：將字符串轉換成大寫

n???????? trim：去掉字符串前后的空白字符

????????? 序列使用的：

n???????? size：獲得序列中元素的數目

????????? 數字使用的：

n???????? int：取得數字的整數部分（如-1.9?int的結果是-1）

????????? 例子（假設test保存字符串"Tom & Jerry"）：

輸出結果是：

l???????? 操作符優先順序

（4）Interpolation

l???????? Interpolation有兩種類型：

????????? 通用Interpolation：${expr}

????????? 數字Interpolation：#{expr}或#{expr; format}

l???????? 注意：Interpolation只能用于文本部分

l???????? 通用Interpolation

????????? 插入字符串值：直接輸出表達式結果

????????? 插入數字值：根據缺省格式（由#setting指令設置）將表達式結果轉換成文本輸出；可以使用內建函數string格式化單個Interpolation，下面是一個例子：

輸出結果是：

????????? 插入日期值：根據缺省格式（由#setting指令設置）將表達式結果轉換成文本輸出；可以使用內建函數string格式化單個Interpolation，下面是一個使用格式模式的例子：

輸出的結果類似下面的格式：

????????? 插入布爾值：根據缺省格式（由#setting指令設置）將表達式結果轉換成文本輸出；可以使用內建函數string格式化單個Interpolation，下面是一個例子：

輸出結果是：

l???????? 數字Interpolation的#{expr; format}形式可以用來格式化數字，format可以是：

????????? mX：小數部分最小X位

????????? MX：小數部分最大X位

????????? 例子：

FreeMarker設計指南(4)

?

?

?

4、雜項

（1）用戶定義指令

l???????? 宏和變換器變量是兩種不同類型的用戶定義指令，它們之間的區別是宏是在模板中使用macro指令定義，而變換器是在模板外由程序定義，這里只介紹宏

l???????? 基本用法

????????? 宏是和某個變量關聯的模板片斷，以便在模板中通過用戶定義指令使用該變量，下面是一個例子：

????????? 作為用戶定義指令使用宏變量時，使用@替代FTL標記中的#

????????? 如果沒有體內容，也可以使用：

l???????? 參數

????????? 在macro指令中可以在宏變量之后定義參數，如：

????????? 可以這樣使用這個宏變量：

輸出結果是：

????????? 宏的參數是FTL表達式，所以下面的代碼具有不同的意思：

????????? 這意味著將Fred變量的值傳給person參數，該值不僅是字符串，還可以是其它類型，甚至是復雜的表達式

????????? 宏可以有多參數，下面是一個例子：

????????? 可以這樣使用該宏變量：

????????? 其中參數的次序是無關的，因此下面是等價的：

????????? 只能使用在macro指令中定義的參數，并且對所有參數賦值，所以下面的代碼是錯誤的：

????????? 可以在定義參數時指定缺省值，如：

????????? 這樣<@greet person="Fred"/>就正確了

????????? 宏的參數是局部變量，只能在宏定義中有效

l???????? 嵌套內容

????????? 用戶定義指令可以有嵌套內容，使用<#nested>指令執行指令開始和結束標記之間的模板片斷

????????? 例子：

這樣使用該宏變量：

輸出結果：

????????? <#nested>指令可以被多次調用，例如：

輸出結果：

????????? 嵌套內容可以是有效的FTL，下面是一個有些復雜的例子：

輸出結果：

????????? 宏定義中的局部變量對嵌套內容是不可見的，例如：

輸出結果：

????????? ?

l???????? 在宏定義中使用循環變量

????????? 用戶定義指令可以有循環變量，通常用于重復嵌套內容，基本用法是：作為nested指令的參數傳遞循環變量的實際值，而在調用用戶定義指令時，在<@…>開始標記的參數后面指定循環變量的名字

????????? 例子：

輸出結果：

????????? 指定的循環變量的數目和用戶定義指令開始標記指定的不同不會有問題

n???????? 調用時少指定循環變量，則多指定的值不可見

n???????? 調用時多指定循環變量，多余的循環變量不會被創建

（2）在模板中定義變量

l???????? 在模板中定義的變量有三種類型：

????????? plain變量：可以在模板的任何地方訪問，包括使用include指令插入的模板，使用assign指令創建和替換

????????? 局部變量：在宏定義體中有效，使用local指令創建和替換

????????? 循環變量：只能存在于指令的嵌套內容，由指令（如list）自動創建；宏的參數是局部變量，而不是循環變量

l???????? 局部變量隱藏（而不是覆蓋）同名的plain變量；循環變量隱藏同名的局部變量和plain變量，下面是一個例子：

輸出結果：

l???????? 內部循環變量隱藏同名的外部循環變量，如：

輸出結果：

l???????? 模板中的變量會隱藏（而不是覆蓋）數據模型中同名變量，如果需要訪問數據模型中的同名變量，使用特殊變量global，下面的例子假設數據模型中的user的值是Big Joe：

（3）名字空間

l???????? 通常情況，只使用一個名字空間，稱為主名字空間

l???????? 為了創建可重用的宏、變換器或其它變量的集合（通常稱庫），必須使用多名字空間，其目的是防止同名沖突

l???????? 創建庫

????????? 下面是一個創建庫的例子（假設保存在lib/my_test.ftl中）：

????????? 使用import指令導入庫到模板中，Freemarker會為導入的庫創建新的名字空間，并可以通過import指令中指定的散列變量訪問庫中的變量：

輸出結果：

可以看到例子中使用的兩個同名變量并沒有沖突，因為它們位于不同的名字空間

l???????? 可以使用assign指令在導入的名字空間中創建或替代變量，下面是一個例子：

l???????? 輸出結果：

l???????? 數據模型中的變量任何地方都可見，也包括不同的名字空間，下面是修改的庫：

l???????? 假設數據模型中的user變量的值是Fred，則下面的代碼：

l???????? 輸出結果：