转自：http://fhd001.iteye.com/blog/1167764

freemarker之模板开发(其它之自定义指令)

----------

自定义指令可以使用macro指令来定义，这是模板设计者所关心的内容。Java程序员若不想在模板中实现自定义指令，而是在java语言中实现指令的定义，这时可以使用:freemarker.template.TemplateDirectiveModel类来扩展。

宏

宏是有一个变量名的模板片段。你可以在模板中使用宏作为自定义指令，这样就能进行重复性的工作。

如例：

Html代码  

1. <#macro greet>  
2.     <font size="+2">Hello Joe!</font>  
3. </#macro>  

macro指令自身不打印任何内容，它只是用来创建宏变量，所以就会有一个名为greet的变量,在<#macro greet>和</#macro>之间的内容(称为宏定义体)当使用它作为指令时将会被执行。你可以在FTL标记中通过@代替#来使用自定义指令。使用变量名作为指令名。而且，自定义指令的结束标记也是需要的，如：<@greet></@greet>

因为<anything>,/anything>和<anything/>是相同的，你也可以使用：<@greet/>

宏能做的事情还有很多，因为在<#macro...>和</#macro>之间的东西是模板片段，也就是说它可以包含插值(${..})和FTL标签(如：<#if...>...</#if>)。

注意：程序员通常将使用<@...>，这称为宏调用。

参数

在macro指令中，宏名称的后面位置是用来定义变量的。如例： 

Html代码  

1. <#macro greet person>  
2.     <font size="+2">Hello ${person}!</font>  
3. </#macro>  

那么就可以这样来使用这个宏：

Html代码  

1. <@greet person="Fred"/>  

使用预定义指令时，参数的值(=号后边的值)可以是FTL表达式。这样，不像HTML，"Fred"的引号就可以不用要了。<@greet person=Fred/>也意味着使用变量的值Fred作为person参数，而不是字符串"Fred"。当然参数值并不一定是字符串类型，也可以是数字，布尔值，哈希表，序列等...也可以在=号左边使用复杂表达式(比如：someParam=(price+50)*1.25)

自定义指令可以有多个参数，如：  

Html代码  

1. <#macro greet person color>  
2.     <font size="+2" color="${color}">Hello ${persion}!</font>  
3. </#macro>  

那么，这个宏就可以这样来使用：

Html代码  

1. <@greet person="Fred" color="black"/>  

同时也必须给出在宏中定义所有参数的值。如果你尝试<@greet person="Fred"/>时也会发生错误，因为忘记指定color的值了。 

根据FTL表达式规则，明白下面这一点是至关重要的，someParam=foo和someParam="${foo}"是不同的。第一种情况，是把变量foo的值作为参数的值来使用。第二种情况则是使用插值形式的字符串，那么参数值就是字符串了，这个时候，foo的值呈现为文本，而不管foo是什么类型的。

宏参数的另外一个重要的方面是它们是局部变量。

嵌套内容

自定义指令可以嵌套内容，和预定义指令相似。如： 

Html代码  

1. <#macro border>  
2.     <table border=4 cellspacing=0 cellpadding=4><tr><td>  
3.         <#nested>  
4.     </td></tr></table>  
5. </#macro>  

注：<#nested>指令执行位于开始和结束标记指令之间的模板代码段。如果这样写：

Html代码  

1. <@border>The bordered text</@border>  

那么就会输出：

Html代码  

1. <table border=4 cellspacing=0 cellpadding=4><tr><td>  
2.     The bordered text  
3. </td></tr></table>  

如果不使用nested指令，那么嵌套的内容就不会被执行，前面的例子如果这样写：

Html代码  

1. <@greet person="Joe">  
2.     Anything.  
3. </@greet>  

FreeMarker不会把它视为错误，只是打印：

Html代码  

1. <font size="+2">Hello Joe!</font>  

嵌套的内容被忽略了，因为greet宏没有使用nested指令。

宏和循环变量

像list这样的预定义指令可以使用循环变量，如例：

Html代码  

1. <#macro do_thrice>  
2.     <#nested 1>  
3.     <#nested 2>  
4.     <#nested 3>  
5. </#macro>  

用户自定义指令，使用";"代替"as"

Html代码  

1. <@do_thrice ; x>  
2.     ${x} Anything.  
3. </@do_thrice>  

将会输出：

1 Anything.

2 Anything.

3 Anything.

nested指令(当然参数可以是任意的表达式)的参数,循环变量的名称是在自定义指令的开始标记(<@...>)的参数后面通过分号确定的。