FTML

語言概括

FTML 是（Fadfox Template Markup Language）的縮寫，是由知啟蒙團隊開發的模板引擎（FadfoxTemplate）使用的檔案擴展名。

FTML語法類似於Java&Javascript，力求學習簡單，易理解。FTML包含有七種標記語句和支持四十九種表達式，如下：

相關語句

一、變數定義語句（_Var）：

<#var name = "凡狐模板引擎"/>

表示定義變數name的值為“凡狐模板引擎”。

二、函式定義語句（_Function）：

<#function functionName(param1, param2)>

<div>param1 = ${param1}</div>

<div>param2 = ${param2}</div>

</#function>

三、檔案包含語句（_Include）

<#include "/ftml/inc.ftml"/>

表示包含檔案“/ftml/inc.ftml”的內容到該頁面中。

四、判斷語句（_If）

<#if (!Validates.isEmpty(name) && name.startWith("凡狐"))>

${name}

</#if>

五、遍歷語句（_For）

<#for (var item : list)>

<#if (Validates.isNotEmpty(item))>

${item}

</#if>

</#for>

六、攔截器語句（_Interceptor）

<#interceptor "chkLogin"/>

攔截器語句用於在執行之前判斷是否支持定義的參數的值，如"chkLogin"表示是一個攔截器名稱

七、表達式語句（_Expression）：

表達式語句是通過連線、計算和合併的方式執行多個表達式，得到執行結果，然後把結果顯示在頁面上，值為（null）不顯示結果，如：

${name} 表示執行表達式name

${name + "模板引擎"} 表示執行表達式name + "模板引擎"

表達式

表達式共49個，分三類，原型表達式（Primitive）8個，符號表達式（Symbol）21個，和操作表達式（Operator）20個。

一、原型表達式

一共支持8種原型表達式，如下：

1、_Variable， 變數表達式。由字母或下劃線開頭，字母數字下劃線組合的字元串，表示是變數，${n123}、${name}、${_123}、${Fadfox}中的字元串n123、name、_123、Fadfox是變數表達式。

2、_Integer，整數表達式。由純數組成的字元串表示整數，注意（0開頭不是8進制，會被過濾），暫不支持十六進制（0x的開頭），如${12345}中12345是整數表達式。

3、_Decimal，小數表達式。由兩個整數表達式和一個點號表達式組合而成，如${123.45}，在表達式計算合併前是分解成{123}，{.}，{45}三個表達式，合併後是一個小數表達式。

4、_String，字元串表達式。由雙引號引用起來的字元串，如果字元串中含有雙引號，使用轉義符（“\”）轉義，如${"123+&fadfox...\"abc...zhiqim"}，其中123+&fadfox...\"abc...zhiqim是一個整體字元串。

5、_Char，字元表達式。由單引號引用起來的字元，如字元是單引號，使用轉義符（“\”）轉義，如${'a'}、${'\''}中a和\'是字元。

6、_Boolean，布爾表達式。內容是true或false兩個字元串表示的，表示其值為真/假。如${true}、${false}。

7、_Null，空表達式。內容是null的字元串表示，表示其值為null，如${null}。

8、_Class，類表達式。由.class結尾的，類名是字元串下劃線數字組合且，類名和包名要求字母或下劃線開頭，格式如{com.zhiqm.fadfox.bootstrap.Startup.class}。在表達式計算合併之前是由多個變數表達式和點號表達式組成。

二、符號表達式

一共支持21種符號，如下：

1、_Plus（+），加號或連線符，由字元"+"組成，如${23 + 23}，${"fad" + "fox"}表示加法運算或表示字元串等連線。

2、_Minus（-），減號或取負符，由字元"-"組成，如${23 - 23}，${-12}表示減法運算或表示負數。

3、_Asterisk（*），星號表達式。由一個"*"字元組成，如${a * 5}表示a乘5，在乘法操作表達式中會用到。

4、_Slash（/），斜槓符、除號，由字元"/"組成，如${33 / 3}，表示除法運算。

5、_Percent（%），百分號，取模求余號，由字元"/"組成，如${32 % 3}，表示取模求余運算。

6、_OpenParenthesis（(），左括弧。由一個"("字元組成，如${(1+2) * 3}，${fadfox(a)}，${Validates.isEmpty(empty)}，在運算表達式和方法表達式中會用到，表示優先運算，函式調用或對象的方法調用等。

7、_CloseParenthesis（)），右括弧。同左括弧。

8、_OpenBracket（[），左方括弧。由一個"["字元組成，如${a[1]}，${obj["name"]}，${map["key"]}，在屬性表達式中會用到，表示數組、列表下標，對象屬性，哈唏表取值等。

9、_CloseBracket（]），右方括弧。同左方括弧。

10、_Comma（,），逗號。由一個","字元組成，如${fadfox(a, b)}，用於表示函式或方法調用的參數分隔設定。

11、_Dot（.），點號。由一個"."字元組成，如${com.zhiqim.fadfox.bootstrap.Startup.class}，${Validates.isEmpty(empty)}，用於表達式之間的連線符，如表示包結構，類的方法等。

12、_DotDot（..），雙點號。由兩個"."字元組成，如<#for (var i : 1 .. 10)>，${(a..b)[0]}表示從N1到N2的整數數組，用於遍歷和數組取值等。

13、_Exclamation（!），感嘆號，由一個"!"字元組成，如${!Validates.isEmpty(empty)}，在取反表達式中用到。

14、_Equal（==），恆等號，由兩個"="字元組成，如<#if (fad== 0)>、<#if (fox == null)>、<#if (fad == "fad")>，用於轉化為操作表達式_EqualEqual。

15、_Inequal（!=），不等符，由"!="兩個字元組成，<#if (fad != 0)>、<#if (fox != null)>、<#if (fad != "fad")>，用於轉化為操作表達式_EqualNot。

16、_Gt（gt），大於符，由“gt”兩個字元組成，如<#if (fad gt 0)>，表示左值和右值比較，同運算符">"，由於在HTML中">"作為標記在使用，所以FTML中使用"gt"代替">"。

17、_Gte（gte），大於等於符，由“gte”三個字元組成，如<#if (fad gte 0)>，表示左值和右值比較，同運算符">="，由於在HTML中">"作為標記在使用，所以FTML中使用"gte"代替">="。

18、_Lt（lt），大於符，由“lt”兩個字元組成，如<#if (fad lt 0)>，表示左值和右值比較，同運算符"<"，由於在HTML中"<"作為標記在使用，所以FTML中使用"lt"代替"<"。

19、_Lte（lte），大於符，由“lte”三個字元組成，如<#if (fad lte 0)>，表示左值和右值比較，同運算符"<="，由於在HTML中"<"作為標記在使用，所以FTML中使用"lte"代替"<="。

20、_Ampersand（&），和與號表達式。由一個"&"字元組成，如$(a & 5) 或 ${a && true}兩種操作表達式中會使用到，一個表示數字之間的與計算，一個由兩個和與號組合成&&，表示兩個布爾型之間的和連線。

21、_VerticalBar（|），豎槓，異或號表達式。由一個"|"字元組成，如$(a | 5) 或 ${a || true}兩種操作表達式中會使用到，一個表示數字之間的與計算，一個由兩個和與號組合成||，表示兩個布爾型之間的和連線。

三、操作表達式

操作表達式：是對原型表達式和符號表達式進行合併和運算得到最終一個表達式，輸出結果給相應的語句中進行判斷或顯示。當前支持一共20種，如下：

1、_Add，加法表達式，在運算前，由左右兩個表達式符組成，如${(a - 3 + 2) + (b +3 -2)}，最終合併得到加法表達式。

2、_Subtraction，減法表達式，在運算前，由左右兩個表達式符組成，如${(a - 3 + 2) - (b +3 -2)}，最終合併得到減法表達式。

3、_Multiplication，乘法表達式，在運算前，由左右兩個表達式符組成，如${(a - 3 + 2) * (b +3 -2)}，最終合併得到乘法表達式。

4、_Division，除法表達式，在運算前，由左右兩個表達式符組成，如${(a - 3 + 2) / (b +3 -2)}，最終合併得到除法表達式。

5、_Modulus，取模求余表達式，在運算前，由左右兩個表達式符組成，如${(a - 3 + 2) % (b +3 -2)}，最終合併得到取模表達式。

6、_Bracket，括弧表達式，由左右括弧包含的一個表達式，如${(a - 3 + 2)}，最終合併成括弧表達式。

7、_Negative，取負表達式，最前為負號（_Minus），負號後面連線一個表達式，如${-(a - 3 + 2)}，最終合併成取負表達式。

8、_Not，取反表達式，最前為感嘆號（_Exclamation），感嘆號後面連線一個結果是布爾的表達式，如${!Validates.isEmpty(fadfox)}，最終合併成取反表達式。

9、_EqualEqual，恆等表達式，由恆等符（_Equal），連線左右兩個表達式，並對左右表達式求值，如果表達式是原型表達式（_NULL、_Boolean、_Integer、_Decimal、_Char、_String等）比較其值，非原型表達式使用equals方法進行比較，得到一個布爾值。

10、_EqualNot，不等表達式，連線符為（_Inequal），和_EqualEqual類似，最終結果對比較之後的值取反。

11、_GreateThen，大於表達式，連線符為（_Gt），連線左右兩個表達式，如是原型表達式，比較其值，否則轉為字元串使用compareTo進行比較。

12、_GreateThenEqual，大於等於表達式，和_GreateThen，連線符為（_Gte）。

13、_LessThen，小於表達式，和_GreateThen，連線符為（_Lt）。

14、_LessThenEqual，小於等於表達式，和_GreateThen，連線符為（_Lte）。

15、_And，與表達式，連線符為（&&，兩個_Ampersand），連線左右兩個布爾值的表達式，兩值都為真時表達式的值為真，否則為假。<#if (Validates.isEmpty(fad) && Validates.isEmpty(fox))>

16、_Or，或表達式，連線符為（||，兩個_VerticalBar），連線左右兩個布爾值的表達式，兩值有一個為真時表達式的值為真，否則為假。如<#if (Validates.isEmpty(fad) || Validates.isEmpty(fox))>

17、_IntegerArray，整數數組表達式，連線符為（_DotDot），連線左右兩個整數值的表達式，生成數組，從第一個整數到第二個整數。如${1 .. 4}，<#for (var i : 1..4)>表示是1，2，3，4四個值的整數數組

18、_Property，屬性表達式，連線符為（[]），包括三種：

------1）原對象是數組或列表的情況，屬性表示取下標值，如${a[2]}，a對象表示是數組或列表的。

------2）原對象是MAP的情況，屬性表示根據KEY取VALUE，如${b["key"]}，表示b為Map，取b.get(key)的值

------3）其他情況，視為讀取對象的定義的屬性值，如${c["prop"]}，表示c對象定義了prop的屬性的值。

19、_Method，方法表達式，連線符為（()），包括兩種：

------1）有目標對象時，表示執行目標對象上的方法，如${obj.getMessage("abc")}表示從對象obj的類結構中找到getMessage方法並且參數是一個字元串，傳入值執行該方法得到結果。

------2）沒有目標對象時，表示為全局定義的函式，從全局函式（_Function）表中找到函式，並執行，如${fadfox("abc")}表示全局函式（_Function）中找到fadfox，傳入參數並執行得到。

20、_New，構造對象表達式，最前為字元（new），連線後面的方法表達式，合併成構造函式表達式。

運算優先權

表達式合併運算，共21個(其中1個賦值/20個運算表達式)，優先權排列如下：

最佳化級	名稱	操作	結合性
1	後綴運算符	_Bracket（()）、_Property（[ ]）、_Method（()）	從左到右
2	單目運算	_Not（!）、_Negative（-） _IntegerArray（..）	從右到左
3	創建	_New（new）	從右到左
4	乘除取模	_Multiplication（*）、_Division（/） 、 _Modulus（%）	從左到右
5	加減	_Add（+）、_Subtraction（-）	從左到右
6	關係	_GreateThen（ gt）、_GreateThenEqual（ gte）、 _LessThen（ lt）、_LessThenEqual（ lte）	從左到右
7	相等	_EqualEqual（==）、_EqualNot（!=）	從左到右
8	邏輯與	_And（&&）	從左到右
9	邏輯或	_Or（||）	從左到右
10	賦值	_Var（=）	從右到左

模板檔案

凡狐模板引擎支持在初始化的時候提供一個全局上下文申明檔案，默認名稱（context.ftml），在全局上下文檔案中支持如下語句：

一、注釋語句

在全局上下文檔案（context.ftml）中申明注釋語句，用於對語句進行描述的，格式為<#-- 描述內容 -->，如下所示：

<#----------------------------------------------------------------------------------------> <#-----------------------------以下為變數定義--------------------------------------> <#---------------------------------------------------------------------------------------->

二、包含語句

在全局上下文檔案（context.ftml）中申明_Include語句，表示全局上下文檔案包含多個子檔案，如下所示：申明了（a.context.ftml）和（b.context.ftml）則在初始化時也會載入並註冊到全局模板引擎中。

<#--包含另外的檔案--> <#include "/conf/a.context.ftml"/> <#include "/conf/b.context.ftml"/>

三、變數定義語句

在全局上下文檔案（context.ftml）中申明_Var語句，表示該變數定義在全局上下文環境的作用域下。在運行時可直接調用，並支持被最佳化級高的作用域重寫。

<#--定義全局變數--> <#var name = "凡狐引擎指南"/> <#var version = "V1.0"/>

四、函式定義語句

在全局上下文檔案（context.ftml）中申明_Function語句，表示該函式定義在全局上下文環境的作用域下。在運行時可直接調用，並支持在最佳化級高的作用域下重寫。

<#--頭部起始--> <#function fadfox_top_web_head()> <!DOCTYPE html> <html> <head> <title>${context.getContextName()}</title> <meta charset="UTF-8"> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> <meta http-equiv="X-UA-Compatible" content="IE=edge"> <meta name="Author" content="${context.getContextName()}" /> <meta name="Keywords" content="${context.getAttribute("keywords")}" /> <meta name="Description" content="${context.getAttribute("description")}" /> <link rel="shortcut icon" type="image/ico" href="/favicon.ico"> ${Styles.src(context.getAttribute("fadfox.css"))} ${Scripts.src(context.getAttribute("fadfox.js"))} </#function>

作用域範圍

Fadfox模板引擎變數作用域參考Java&Javascript的作用域規範，比Javascript多了語句級作用域，類似於Java的{}作用域，又因為模板引擎類似於Javascript的弱類型定義規則，所以在作用域上比Java多了支持覆蓋定義而不需要檢查類型。

作用域的範圍，依次為①語句級作用域，②頁級作用域，③請求作用域，④上下文作用域，⑤系統作用域，作用範圍如圖所示：

FTML

語句級作用域

語句級作用域，是指在指定的一條語句的參數定義、遍歷條目定義和自定義的變數，只在語句內部有效，退出語句後被銷毀。

1、_For語句定義的<#for (var item : list)>中的變數item在</#for>之內是有效的，之外是無效的或是上一級作用域的值。

<#var item = "我是頁級作用域"/> <#for (var item : list)> 這個${item}是在_For內定義的，取值為list的遍歷出來的值，比頁級作用域小喔。 </#for> 這個${item}在_For之外，取值為上一級（頁級作用域）的值。

2、_Function語句定義的形參變數，在函式內有效，之外是無效的。

<#function func(param1, param2)> ${param1}和${param2}只在函式內有效，比頁級作用域小喔。 </function>

3、在_Function、_For、_If中自定義的變數，也是語句級作用域，如下：

<#function func(param1, param2)> ${param1}和${param2}只在函式內有效。 ------ <#var item = "我也是在函式內有效"/> ------ <#for (var item : list)> 這個${item}是在_For內定義的，取值為list的遍歷出來的值，只在_For內有效喔。 ------ <#if Validates.isNotEmpty(item)> <#var item = "我覆蓋了_For和_Function中定義的item，我只在_If中有效啦。"/> ${item} </#if> ------ </#for> ------ </function>

頁級作用域

頁級作用域，是定義在FTML檔案中通過_Var定義的變數，這些變數從定義的位置開始到頁面結束的範圍內有效，其作用域比語句作域大，所有的語句中都可調用，並支持語句級作用域覆寫。

<#var item = "我是頁級作用域，從這裡向下的頁面都可以使用"/>

請求作用域

請求作用域，由框架定義的當前請求對應的變數如request、response、session、sessionUser、context等，以及在轉入FTML前的request的屬性中（通過request.setAttribute(String key, Object value)設定的屬性），和請求的參數表（通過request.getParameter(String name)設定的參數）。這些變數是整個FTML頁面有效，其作用域比語句作域之大，所有的語句中都可調用，並支持語句級作用域覆寫。框架定義的變數表如下：

序號	變數名	描述
1	request	當前頁的請求對象
2	response	當前頁的回響對象
3	session	當前頁的會話對象
4	sessionUser	當前頁的會話關聯的用戶對象
5	sessionId	當前頁會話編號
6	sessionName	當前頁的會話關聯的用戶名稱
7	context	當前頁的上下文對象

上下文作用域

上下文作用域，是定義在全局上下文檔案（context.ftml）中的變數，在上下文初始化時載入到模板引擎中，其作用域比頁級作用大，可以在所有的FTML頁面中可重複使用，並支持頁級和語句級作用域覆寫。。

系統作用域

系統作用域，包括兩部分，一是框架本身定義的變數，所有定義了註解@AnAlias別名的類，如Validates、DateTimes、Strings，request，response，等常用變數。二是用戶可自定義系統變數，在類上定義註解@AnAlias，或在上下文初始化時通過TemplateEngine.addSystemVariable(String name, Object value)添加到系統作用域中。框架本身定義的變數見下表（只列了常用的幾個，後續加全）：

序號	變數名	描述
1	Global	對應com.zhiqim.fadfox.bootstrap.Global，可調用其靜態方法，該類是工程全局定義，如通過Global.getString(String groupId, String key)獲取配置檔案的信息
2	Jsons	對應com.zhiqim.fadfox.json.Jsons，可調用其靜態方法，該類是JSON工具類，支持toObject和toString，在對象和字元串之間轉化。
3	Amounts	對應com.zhiqim.fadfox.util.Amounts，可調用其靜態方法，該類是金額工具類，支持字元串元轉整數分，金額數值轉人民幣大寫等。
4	Validates	對應com.zhiqim.fadfox.util.Validates，可調用其靜態方法，該類是驗證工具類，有大量的驗證方法，如驗證空、數字、字母、IP位址、Email，時間字元串包括，正則表達式等等
5	Strings	對應com.zhiqim.fadfox.util.Strings，可調用其靜態方法，該類是字元串工具類，有大量的串轉化的方法，如去除前後空白，增加和刪除前後綴等等
6	DateTimes	對應com.zhiqim.fadfox.util.DateTimes，可調用其靜態方法，該類是日曆工具類，包括各種獲取當前時間格式，19位的，10位的，和各種Calendar、long、Date和字元串之間的轉換等
7	Pagings	對應com.zhiqim.fadfox.httpd.context.util.Pagings，可調用其靜態方法，該類是分頁顯示的工具類，包括各種分頁顯示界面等