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

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

----------

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

 

宏

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

如例：

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

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

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

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

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

 

参数

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

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

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

<@greet person="Fred"/>

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

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

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

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

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

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

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

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

 

嵌套内容

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

<#macro border>
    <table border=4 cellspacing=0 cellpadding=4><tr><td>
        <#nested>
    </td></tr></table>
</#macro>

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

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

那么就会输出：

<table border=4 cellspacing=0 cellpadding=4><tr><td>
    The bordered text
</td></tr></table>

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

<@greet person="Joe">
    Anything.
</@greet>

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

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

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

 

宏和循环变量

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

<#macro do_thrice>
    <#nested 1>
    <#nested 2>
    <#nested 3>
</#macro>

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

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

将会输出：

1 Anything.

2 Anything.

3 Anything.

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