freemarker中文手冊(cè)

1、freemarker概述freemarker概述l freemarker是一個(gè)模板引擎，一個(gè)基于模板生成文本輸出的通用工具，使用純java編寫 l freemarker被設(shè)計(jì)用來生成html web頁面，特別是基于mvc模式的應(yīng)用程序 l 雖然freemarker具有一些編程的能力，但通常由java程序準(zhǔn)備要顯示的數(shù)據(jù)，由freemarker生成頁面，通過模板顯示準(zhǔn)備的數(shù)據(jù)（如下圖）l freemarker不是一個(gè)web應(yīng)用框架，而適合作為web應(yīng)用框架一個(gè)組件 l freemarker與容器無關(guān)，因?yàn)樗⒉恢纇ttp或servlet；freemarker同樣可以應(yīng)用于非web應(yīng)用程序環(huán)境

2、l freemarker更適合作為model2框架（如struts）的視圖組件，你也可以在模板中使用jsp標(biāo)記庫 l freemarker是免費(fèi)的 1、通用目標(biāo) l 能夠生成各種文本：html、xml、rtf、java源代碼等等 l 易于嵌入到你的產(chǎn)品中：輕量級(jí)；不需要servlet環(huán)境 l 插件式模板載入器：可以從任何源載入模板，如本地文件、數(shù)據(jù)庫等等 l 你可以按你所需生成文本：保存到本地文件；作為email發(fā)送；從web應(yīng)用程序發(fā)送它返回給web瀏覽器 2、強(qiáng)大的模板語言 l 所有常用的指令：include、if/elseif/else、循環(huán)結(jié)構(gòu) l 在模板中創(chuàng)建和改變變量 l 幾乎在任

3、何地方都可以使用復(fù)雜表達(dá)式來指定值 l 命名的宏，可以具有位置參數(shù)和嵌套內(nèi)容 l 名字空間有助于建立和維護(hù)可重用的宏庫，或者將一個(gè)大工程分成模塊，而不必?fù)?dān)心名字沖突 l 輸出轉(zhuǎn)換塊：在嵌套模板片段生成輸出時(shí)，轉(zhuǎn)換html轉(zhuǎn)義、壓縮、語法高亮等等；你可以定義自己的轉(zhuǎn)換 3、通用數(shù)據(jù)模型 l freemarker不是直接反射到j(luò)ava對(duì)象，java對(duì)象通過插件式對(duì)象封裝，以變量方式在模板中顯示 l 你可以使用抽象（接口）方式表示對(duì)象（javabean、xml文檔、sql查詢結(jié)果集等等），告訴模板開發(fā)者使用方法，使其不受技術(shù)細(xì)節(jié)的打擾 4、為web準(zhǔn)備 l 在模板語言中內(nèi)建處理典型web相關(guān)任務(wù)（如

4、html轉(zhuǎn)義）的結(jié)構(gòu) l 能夠集成到model2 web應(yīng)用框架中作為jsp的替代 l 支持jsp標(biāo)記庫 l 為mvc模式設(shè)計(jì)：分離可視化設(shè)計(jì)和應(yīng)用程序邏輯；分離頁面設(shè)計(jì)員和程序員 5、智能的國際化和本地化 l 字符集智能化（內(nèi)部使用unicode） l 數(shù)字格式本地化敏感 l 日期和時(shí)間格式本地化敏感 l 非us字符集可以用作標(biāo)識(shí)（如變量名） l 多種不同語言的相同模板 6、強(qiáng)大的xml處理能力 l 和指令（2.3版本）用于遞歸遍歷xml樹 l 在模板中清楚和直覺的訪問xml對(duì)象模型 freemarker設(shè)計(jì)指南(1)1、快速入門（1）模板 + 數(shù)據(jù)模型 = 輸出l freemarker基于

5、設(shè)計(jì)者和程序員是具有不同專業(yè)技能的不同個(gè)體的觀念l 他們是分工勞動(dòng)的：設(shè)計(jì)者專注于表示創(chuàng)建html文件、圖片、web頁面的其它可視化方面；程序員創(chuàng)建系統(tǒng)，生成設(shè)計(jì)頁面要顯示的數(shù)據(jù)l 經(jīng)常會(huì)遇到的問題是：在web頁面（或其它類型的文檔）中顯示的信息在設(shè)計(jì)頁面時(shí)是無效的，是基于動(dòng)態(tài)數(shù)據(jù)的l 在這里，你可以在html（或其它要輸出的文本）中加入一些特定指令，freemarker會(huì)在輸出頁面給最終用戶時(shí)，用適當(dāng)?shù)臄?shù)據(jù)替代這些代碼l 下面是一個(gè)例子： welcome! welcome $user! our latest product: $latestp! l 這個(gè)例子是在簡(jiǎn)單的h

6、tml中加入了一些由$包圍的特定代碼，這些特定代碼是freemarker的指令，而包含freemarker的指令的文件就稱為模板（template）l 至于user、latestproduct.url和latestp來自于數(shù)據(jù)模型（data model）l 數(shù)據(jù)模型由程序員編程來創(chuàng)建，向模板提供變化的信息，這些信息來自于數(shù)據(jù)庫、文件，甚至于在程序中直接生成l 模板設(shè)計(jì)者不關(guān)心數(shù)據(jù)從那兒來，只知道使用已經(jīng)建立的數(shù)據(jù)模型l 下面是一個(gè)可能的數(shù)據(jù)模型：(root) | +- user = big joe | +- latestproduct | +- url = product

7、s/greenmouse.html | +- name = green mousel 數(shù)據(jù)模型類似于計(jì)算機(jī)的文件系統(tǒng)，latestproduct可以看作是目錄，而user、url和name看作是文件，url和name文件位于latestproduct目錄中（這只是一個(gè)比喻，實(shí)際并不存在）l 當(dāng)freemarker將上面的數(shù)據(jù)模型合并到模板中，就創(chuàng)建了下面的輸出： welcome! welcome big joe! our latest product: green mouse! （2）數(shù)據(jù)模型l 典型的數(shù)據(jù)模型是樹型結(jié)構(gòu)，可以任意復(fù)雜和深層次，如下面的例子：(root) | +- animal

8、s | | | +- mouse | | | | | +- size = small | | | | | +- price = 50 | | | +- elephant | | | | | +- size = large | | | | | +- price = 5000 | | | +- python | | | +- size = medium | | | +- price = 4999 | +- test = it is a test | +- whatnot | +- because = dont knowl 類似于目錄的變量稱為hashes，包含保存下級(jí)變量的唯一的查詢名字l 類似于

9、文件的變量稱為scalars，保存單值l scalars保存的值有兩種類型：字符串（用引號(hào)括起，可以是單引號(hào)或雙引號(hào)）和數(shù)字（不要用引號(hào)將數(shù)字括起，這會(huì)作為字符串處理）l 對(duì)scalars的訪問從root開始，各部分用“.”分隔，如animals.mouse.pricel 另外一種變量是sequences，和hashes類似，只是不使用變量名字，而使用數(shù)字索引，如下面的例子：(root) | +- animals | | | +- (1st) | | | | | +- name = mouse | | | | | +- size = small | | | | | +- price = 50

10、| | | +- (2nd) | | | | | +- name = elephant | | | | | +- size = large | | | | | +- price = 5000 | | | +- (3rd) | | | +- name = python | | | +- size = medium | | | +- price = 4999 | +- whatnot | +- fruits | +- (1st) = orange | +- (2nd) = bananal 這種對(duì)scalars的訪問使用索引，如（3）模板l 在freemarker模板中可以

11、包括下面三種特定部分： $：稱為interpolations，freemarker會(huì)在輸出時(shí)用實(shí)際值進(jìn)行替代 ftl標(biāo)記（freemarker模板語言標(biāo)記）：類似于html標(biāo)記，為了與html標(biāo)記區(qū)分，用#開始（有些以開始，在后面敘述） 注釋：包含在（而不是）之間l 下面是一些使用指令的例子： if指令#if animals.python.price pythons are cheaper than elephants today. pythons are not cheaper than elephants today. list指令we have these animals: namepr

12、ice $$being.price euros 輸出為：we have these animals: nameprice mouse50 euros elephant5000 euros python4999 euros include指令 test page test page blah blah. 一起使用指令we have these animals: nameprice $ $being.price euros freemarker設(shè)計(jì)指南(3)3、模板（1）整體結(jié)構(gòu)l 模板使用ftl（freemarker模板語言）編寫，是下面各部分的一個(gè)組合：

13、 文本：直接輸出 interpolation：由$和，或#和來限定，計(jì)算值替代輸出 ftl標(biāo)記：freemarker指令，和html標(biāo)記類似，名字前加#予以區(qū)分，不會(huì)輸出 注釋：由限定，不會(huì)輸出l 下面是以一個(gè)具體模板例子：brbrwelcome!brbrbrbrwelcome$user!brwehavetheseanimals:brbrbr$for$being.price eurosbrbrbrbr l br是用于換行的特殊字符序列l(wèi) 注意事項(xiàng)： ftl區(qū)分大小寫，所以list是正確的ftl指令，而list不是；$name和$name是不同的 interpolation只

14、能在文本中使用 ftl標(biāo)記不能位于另一個(gè)ftl標(biāo)記內(nèi)部，例如：#if =bar. 注釋可以位于ftl標(biāo)記和interpolation內(nèi)部，如下面的例子：welcome$user !brwehavetheseanimals:brbr#list animals as beingbr. 多余的空白字符會(huì)在模板輸出時(shí)移除（2）指令l 在freemarker中，使用ftl標(biāo)記引用指令l 有三種ftl標(biāo)記，這和html標(biāo)記是類似的： 開始標(biāo)記： 結(jié)束標(biāo)記： 空內(nèi)容指令標(biāo)記：l 有兩種類型的指令：預(yù)定義指令和用戶定義指令l 用戶定義指令要使用替換#，如.（會(huì)在后面講述）l ftl標(biāo)記不能夠交叉，而應(yīng)該正確的

15、嵌套，如下面的代碼是錯(cuò)誤的： $ for $being.price euros (except for you) l 如果使用不存在的指令，freemarker不會(huì)使用模板輸出，而是產(chǎn)生一個(gè)錯(cuò)誤消息l freemarker會(huì)忽略ftl標(biāo)記中的空白字符，如下面的例子：br$for$being.priceeurosbr l 但是，、/和指令之間不允許有空白字符（3）表達(dá)式l 直接指定值 字符串n 使用單引號(hào)或雙引號(hào)限定n 如果包含特殊字符需要轉(zhuǎn)義，如下面的例子：$its quoted andthis is a backslash: $its quoted a

16、ndthis is a backslash: 輸出結(jié)果是：its quoted andthis is a backslash: its quoted andthis is a backslash: n 下面是支持的轉(zhuǎn)義序列：轉(zhuǎn)義序列含義雙引號(hào)(u0022)單引號(hào)(u0027)反斜杠(u005c)n換行(u000a)rreturn (u000d)ttab (u0009)bbackspace (u0008)fform feed (u000c)la&xcode4位16進(jìn)制unicode代碼n 有一類特殊的字符串稱為raw字符串，被認(rèn)為是純文本，其中的和等不具有特殊含義，該類字符串在引號(hào)前面加r，下面

17、是一個(gè)例子：$r$foo$rc:foobar 輸出的結(jié)果是：$fooc:foobar 數(shù)字n 直接輸入，不需要引號(hào)n 精度數(shù)字使用“.”分隔，不能使用分組符號(hào)n 目前版本不支持科學(xué)計(jì)數(shù)法，所以“1e3”是錯(cuò)誤的n 不能省略小數(shù)點(diǎn)前面的0，所以“.5”是錯(cuò)誤的n 數(shù)字8、+8、08和8.00都是相同的 布爾值n true和false，不使用引號(hào) 序列n 由逗號(hào)分隔的子變量列表，由方括號(hào)限定，下面是一個(gè)例子：$x輸出的結(jié)果是：winterspringsummerautumnn 列表的項(xiàng)目是表達(dá)式，所以可以有下面的例子：2 + 2, 1, 2, 3, 4, whatnotn 可以使用數(shù)字范圍定義數(shù)字

18、序列，例如2.5等同于2, 3, 4, 5，但是更有效率，注意數(shù)字范圍沒有方括號(hào)n 可以定義反遞增的數(shù)字范圍，如5.2 散列（hash）n 由逗號(hào)分隔的鍵/值列表，由大括號(hào)限定，鍵和值之間用冒號(hào)分隔，下面是一個(gè)例子：name:greenmouse, price:150n 鍵和值都是表達(dá)式，但是鍵必須是字符串l 獲取變量 頂層變量： $variable，變量名只能是字母、數(shù)字、下劃線、$、和#的組合，且不能以數(shù)字開頭 從散列中獲取數(shù)據(jù)n 可以使用點(diǎn)語法或方括號(hào)語法，假設(shè)有下面的數(shù)據(jù)模型：(root) | +- book | | | +- title = breeding green mouses

19、 | | | +- author | | | +- name = julia smith | | | +- info = biologist, 1923-1985, canada | +- test = title下面都是等價(jià)的：bookauthornamen 使用點(diǎn)語法，變量名字有頂層變量一樣的限制，但方括號(hào)語法沒有該限制，因?yàn)槊质侨我獗磉_(dá)式的結(jié)果 從序列獲得數(shù)據(jù)：和散列的方括號(hào)語法語法一樣，只是方括號(hào)中的表達(dá)式值必須是數(shù)字；注意：第一個(gè)項(xiàng)目的索引是0 序列片斷：使用startindex.endi

20、ndex語法，從序列中獲得序列片斷（也是序列）；startindex和endindex是結(jié)果為數(shù)字的表達(dá)式 特殊變量：freemarker內(nèi)定義變量，使用.variablename語法訪問l 字符串操作 interpolation（或連接操作）n 可以使用$.（或#.）在文本部分插入表達(dá)式的值，例如：$hello $user!$user$user$user$user n 可以使用+操作符獲得同樣的結(jié)果$hello + user + !$user + user + user + usern $.只能用于文本部分，下面的代碼是錯(cuò)誤的：wow!wow!應(yīng)該寫成：wow! 子串n 例子（假設(shè)user的

21、值為“big joe”）：$user0$user4$user1.4結(jié)果是（注意第一個(gè)字符的索引是0）：bjig jl 序列操作 連接操作：和字符串一樣，使用+，下面是一個(gè)例子：- $user輸出結(jié)果是：- joe- fred- julia- katel 散列操作 連接操作：和字符串一樣，使用+，如果具有相同的key，右邊的值替代左邊的值，例如：- joe is $ages.joe- fred is $ages.fred- julia is $ages.julia 輸出結(jié)果是：- joe is 30- fred is 25- julia is 18 l 算術(shù)運(yùn)算 、，下面是一個(gè)例子：$x * x

22、 - 100$x / 2$12 % 10輸出結(jié)果是（假設(shè)x為5）：-752.52 操作符兩邊必須是數(shù)字，因此下面的代碼是錯(cuò)誤的：$3 * 5 使用+操作符時(shí)，如果一邊是數(shù)字，一邊是字符串，就會(huì)自動(dòng)將數(shù)字轉(zhuǎn)換為字符串，例如：$3 + 5 輸出結(jié)果是：35 使用內(nèi)建的int（后面講述）獲得整數(shù)部分，例如：$(x/2)?int$1.1?int$1.999?int$-1.1?int$-1.999?int輸出結(jié)果是（假設(shè)x為5）：211-1-1l 比較操作符 使用=（或=，完全相等）測(cè)試兩個(gè)值是否相等，使用!= 測(cè)試兩個(gè)值是否不相等 =和!=兩邊必須是相同類型的值，否則會(huì)產(chǎn)生錯(cuò)誤，例如會(huì)引起錯(cuò)誤 fre

23、emarker是精確比較，所以對(duì)x、x 和x是不相等的 對(duì)數(shù)字和日期可以使用、和=，但不能用于字符串 由于freemarker會(huì)將解釋成ftl標(biāo)記的結(jié)束字符，所以對(duì)于和=可以使用括號(hào)來避免這種情況，例如 y) 另一種替代的方法是，使用lt、lte、gt和gte來替代、和=l 邏輯操作符 &（and）、|（or）、!（not），只能用于布爾值，否則會(huì)產(chǎn)生錯(cuò)誤 例子：#if x we have less than 12 things, and they are green. its not hot. l 內(nèi)建函數(shù) 內(nèi)建函數(shù)的用法類似訪問散列的子變量，只是使用“?”替代“.”，下面列出常用的一些函數(shù)

24、 字符串使用的：n html：對(duì)字符串進(jìn)行html編碼n cap_first：使字符串第一個(gè)字母大寫n lower_case：將字符串轉(zhuǎn)換成小寫n upper_case：將字符串轉(zhuǎn)換成大寫n trim：去掉字符串前后的空白字符 序列使用的：n size：獲得序列中元素的數(shù)目 數(shù)字使用的：n int：取得數(shù)字的整數(shù)部分（如-1.9?int的結(jié)果是-1） 例子（假設(shè)test保存字符串tom & jerry）：$test?html$test?upper_case?html輸出結(jié)果是：tom & jerrytom & jerry l 操作符優(yōu)先順序操作符組操作符后綴subvarname

25、 substringrange . (methodparams)一元+expr、-expr、!內(nèi)建?乘法*、 / 、%加法+、-關(guān)系、=（lt、lte、gt、gte）相等=（=）、!=邏輯and&邏輯or|數(shù)字范圍.（4）interpolationl interpolation有兩種類型：select userid count 通用interpolation：$expr 數(shù)字interpolation：#expr或#expr; formatl 注意：interpolation只能用于文本部分l 通用interpolation 插入字符串值：直接輸出表達(dá)式結(jié)果 插入數(shù)字值：根據(jù)缺省格式（由#se

26、tting指令設(shè)置）將表達(dá)式結(jié)果轉(zhuǎn)換成文本輸出；可以使用內(nèi)建函數(shù)string格式化單個(gè)interpolation，下面是一個(gè)例子：$answer$answer?string $answer?string.number$answer?string.currency$answer?string.percent輸出結(jié)果是：$42.00$42.0042$42.004,200% 插入日期值：根據(jù)缺省格式（由#setting指令設(shè)置）將表達(dá)式結(jié)果轉(zhuǎn)換成文本輸出；可以使用內(nèi)建函數(shù)string格式化單個(gè)interpolation，下面是一個(gè)使用格式模式的例子：$lastupdated?string(yyyy-

27、mm-dd hh:mm:ss zzzz)$lastupdated?string(eee, mmm d, yy)$lastupdated?string(eeee, mmmm dd, yyyy, hh:mm:ss a (zzz) 輸出的結(jié)果類似下面的格式：2003-04-08 21:24:44 pacific daylight timetue, apr 8, 03tuesday, april 08, 2003, 09:24:44 pm (pdt) 插入布爾值：根據(jù)缺省格式（由#setting指令設(shè)置）將表達(dá)式結(jié)果轉(zhuǎn)換成文本輸出；可以使用內(nèi)建函數(shù)string格式化單個(gè)interpolation，下面

28、是一個(gè)例子：$foo?string(yes, no)輸出結(jié)果是：yesl 數(shù)字interpolation的#expr; format形式可以用來格式化數(shù)字，format可以是： mx：小數(shù)部分最小x位 mx：小數(shù)部分最大x位 例子： #x; m2 #y; m2 #x; m1 #y; m1 #x; m1m2 #y; m1m2 freemarker設(shè)計(jì)指南(4)4、雜項(xiàng)（1）用戶定義指令l 宏和變換器變量是兩種不同類型的用戶定義指令，它們之間的區(qū)別是宏是在模板中使用macro指令定義，而變換器是在模板外由程序定義，這里只介紹宏l 基本用法 宏是和某個(gè)變量關(guān)聯(lián)的模板片斷，以便在模板中通過用戶定義指令

29、使用該變量，下面是一個(gè)例子： hello joe! 作為用戶定義指令使用宏變量時(shí)，使用替代ftl標(biāo)記中的# 如果沒有體內(nèi)容，也可以使用：l 參數(shù) 在macro指令中可以在宏變量之后定義參數(shù)，如： hello $person! 可以這樣使用這個(gè)宏變量： and 輸出結(jié)果是： hello fred! and hello batman! 宏的參數(shù)是ftl表達(dá)式，所以下面的代碼具有不同的意思： 這意味著將fred變量的值傳給person參數(shù)，該值不僅是字符串，還可以是其它類型，甚至是復(fù)雜的表達(dá)式 宏可以有多參數(shù)，下面是一個(gè)例子： hello $person! 可以這樣使用該宏變量： 其中參數(shù)的次序是無

30、關(guān)的，因此下面是等價(jià)的： 只能使用在macro指令中定義的參數(shù)，并且對(duì)所有參數(shù)賦值，所以下面的代碼是錯(cuò)誤的： 可以在定義參數(shù)時(shí)指定缺省值，如： hello $person! 這樣就正確了 宏的參數(shù)是局部變量，只能在宏定義中有效l 嵌套內(nèi)容 用戶定義指令可以有嵌套內(nèi)容，使用指令執(zhí)行指令開始和結(jié)束標(biāo)記之間的模板片斷 例子： 這樣使用該宏變量：the bordered text輸出結(jié)果： the bordered text 指令可以被多次調(diào)用，例如： anything. 輸出結(jié)果： anything. anything. anything. 嵌套內(nèi)容可以是有效的ftl，下面是一個(gè)有些復(fù)雜的例子： 輸

31、出結(jié)果： hello joe! hello joe! hello joe! 宏定義中的局部變量對(duì)嵌套內(nèi)容是不可見的，例如： $y $count/$x: $y?default(?) $x?default(?) $count?default(?)輸出結(jié)果： test 3/1: ? ? ? test 3/2: ? ? ? test 3/3: ? ? ? l 在宏定義中使用循環(huán)變量 用戶定義指令可以有循環(huán)變量，通常用于重復(fù)嵌套內(nèi)容，基本用法是：作為nested指令的參數(shù)傳遞循環(huán)變量的實(shí)際值，而在調(diào)用用戶定義指令時(shí)，在開始標(biāo)記的參數(shù)后面指定循環(huán)變量的名字 例子： $c. $halfc last! 輸出結(jié)

32、果： 1. 0.5 2. 1 3. 1.5 4. 2 last! 指定的循環(huán)變量的數(shù)目和用戶定義指令開始標(biāo)記指定的不同不會(huì)有問題n 調(diào)用時(shí)少指定循環(huán)變量，則多指定的值不可見n 調(diào)用時(shí)多指定循環(huán)變量，多余的循環(huán)變量不會(huì)被創(chuàng)建（2）在模板中定義變量l 在模板中定義的變量有三種類型： plain變量：可以在模板的任何地方訪問，包括使用include指令插入的模板，使用assign指令創(chuàng)建和替換 局部變量：在宏定義體中有效，使用local指令創(chuàng)建和替換 循環(huán)變量：只能存在于指令的嵌套內(nèi)容，由指令（如list）自動(dòng)創(chuàng)建；宏的參數(shù)是局部變量，而不是循環(huán)變量l 局部變量隱藏（而不是覆蓋）同名的plain變量；循環(huán)變量隱藏同名的局部變量和plain變量，下面是一個(gè)例子：1. $x 6. $x 7. $x 8. $x 9. $x 2. $x 3. $x 4. $x 5. $x 輸出結(jié)果：1. plain 2. plain 3. local 4. loop 5. local6. plain 7. loop 8. loop9. plain2l 內(nèi)部循環(huán)變量隱藏同名的外部循環(huán)變量，如： $x