FreeMarker 設計指南 (四/完)：巨集、命名空間與進階變數控制

1. 使用者定義指令：巨集

巨集在模板中以 <#macro name> 定義，調用時用 <@name> (以 @ 取代 #)。

基本語法

<#macro greet person color="black">
  <font size="+2" color="${color}">Hello ${person}!</font>
</#macro>

<@greet person="Fred"/>
<@greet person="Batman" color="red"/>

巢狀內容與 <#nested>

<#macro border>
  <div class="border"><#nested></div>
</#macro>

<@border>被框起的文字</@border>

<#nested> 可多次呼叫，實現重複輸出。

迴圈變數

<#macro repeat count>
  <#list 1..count as x>
    <#nested x, x/2, x==count>
  </#list>
</#macro>

<@repeat count=4 ; c, half, last>
  ${c}. ${half}<#if last> Last!</#if>
</@repeat>

2. 模板中定義變數

<#assign x = "plain">  ${x}  <!-- plain -->
<#macro test>
  ${x}               <!-- plain -->
  <#local x = "local"> ${x}  <!-- local -->
  <#list ["loop"] as x> ${x} <!-- loop --></#list>
  ${x}               <!-- local -->
</#macro>
<@test/>
${x}                 <!-- plain -->

存取資料模型同名變數用 .globals.var。

3. 命名空間

防止巨集/變數命名衝突，建立可複用函式庫。

建立庫

<!-- lib/my_test.ftl -->
<#macro copyright date>
  Copyright (C) ${date} Julia Smith. <br> Email: ${mail}
</#macro>
<#assign mail = "JSmith@acme.com">

匯入與使用

<#import "/lib/my_test.ftl" as my>
<@my.copyright date="1999-2002"/>
${my.mail}   <!-- JSmith@acme.com -->
<#assign mail="fred@acme.com" in my>
${my.mail}   <!-- JSmith@other.com -->

資料模型變數跨命名空間可見，庫內可直接引用 ${user} 等。

完結撒花

四篇指南涵蓋 FreeMarker 核心語法、資料模型、指令/表達式/插值、巨集與命名空間，足以應對實戰模板開發需求。