FreeMarker标签是WebWork提供的一般标签的扩展. 只要简单的了解这些标签的访问方式: <@ww.xxx> ...</@ww.xxx> (这里的xxx指WebWork支持的标签), 就可以马上开始使用了.

语法

例如, 在JSP中你可能这样创建一个form:

<ww:form action="updatePerson">
    <ww:textfield label="First name" name="firstName"/>
    <ww:submit value="Update"/>
</ww:form>

FreeMarker中创建同样的form是这样的:

<@ww.form action="updatePerson">
    <@ww.textfield label="First name" name="firstName"/>
    <@ww.submit value="Update"/>    
</@ww.form>

这就基本上覆盖了使用FreeMarker标签的所有内容了, 还有一些高级功能你应该了解, 特别是属性和参数如何共同工作, 还有参数的类型 (String, List, 等等) 能够影响到标签的行为.

属性和参数

与老版本的JSP不同 (JSP标签的基础), FreeMarker 允许 动态属性, 很就像JSP 2.0. 这就意味着你可以给这些标签提供这些标签本不支持的属性. 这些不能够直接被应用到标签对象的属性将会被放到这个标签的通用 parameters map.

例如, 假设你的JSP中有如下代码:

<ww:url value="somePage">
    <ww:param name="personId" value="%{personId}"/>
</ww:url>

在FreeMarker中, 你可以将它简化为:

<@ww.url value="somePage" personId="${personId}"/>

不仅可以替代原本要使用 param 的情况, 你还可以在扩展你的 Form标签的模版或者主题的时候使用这个功能. 例如, 假设你创建了一个 "三分栏" 主题来替代标准的两分栏主题 (xhtml). 你可能想要在第三栏中显示一个叫做"description"的扩展参数. 你的form可以这样写:

<@ww.form action="updatePerson">
    <@ww.textfield label="First name" name="firstName" description="..."/>
    <@ww.submit value="Update"/>    
</@ww.form>

然后在你的新模版中你可以通过 ${parameters.description} 应用这个description.

有时你也许还是希望使用 param 标签, 例如当你需要在标签中嵌入复杂的HTML时. param标签能够提供FreeMarker所提供的内联(inline)属性以外的属性: 它可以将param标签内的所有内容作为 _value_attribute 提供访问.

属性类型

记住所有的标签属性都首先设定为String类型 – 然后它们会被解析 (使用 OGNL) 为不同类型, 例如List, int, 或者boolean. 一般情况下这样就够了, 但是在使用FreeMarker的时候它可能会成为一种限制, FreeMarker提供了更先进的方式来设定属性. 假设如下的例子:

<@ww.select label="Foo label - ${foo}" name="${name}" list="%{{1, 2, 3}}"/>

这里会发生的是每个属性将会被最佳匹配并解析为string. 这可能会调用hash的内部FreeMarker对象的toString()方法, 所有的对象最后将会与你所预期的一样. 这样, 当标签运行时, _list_attribute 将会被从String转化为List，通过 OGNL 的先进集合支持.

但是假设你希望使用FreeMarker的list后者hash支持来替代呢? 你可以这样做:

<@ww.select label="Foo label - ${foo}" name="${name}" list={1, 2, 3}/>

注意这个list属性两边已经没有了引号. 现在它将会作为一个对象进入标签, 它将不容易被转换为String. 一般的, 标签将会调用toString(), 它将返回"[1, 2, 3]", 而这个字符串将不能被OGNL转换为List. 比来回传递要好, WebWork里面的FreeMarker标签支持将会识别出这个集合并且不会讲他们传送到一般的标签属性中, 而是讲他们直接注入到 parameters map , 等待模版来访问.

最后, 所有都会像你期望的那样运转, 但是它能够帮助你理解OGNL什么时候会被使用而什么时候不会, 还有属性类型是如何被转换的.

JSP标签支持

虽然WebWork提供了原生的FreeMarker标签, 但是你可能希望使用那些只能在JSP中使用的第三方标签. 幸运的是, FreeMarker 能够运行JSP标签. 如果希望这样做, 你必须配置 web.xml 2.1.x 兼容性中描述的 JspSupportServlet, 这样就允许FreeMarker能够访问所需要的对象来模拟一个JSP标签库运行容器.

当你那样配置好后, 你可以类似这样的在你的模版中加入:

<#assign cewolf=JspTaglibs["/WEB-INF/cewolf.tld"] />
...
<@cewold.xxx ... />