FreeMarker快速上手

FreeMarker是一个Java模版语言，它是 JSP 的绝佳替代方案. FreeMarker在你的action result可能需要在Servlet容器环境以外被载入的情况下是理想选择. 例如,如果你希望在你的应用程序中支持plugins,你可能会乐意使用Freemarker，因为那样的话plugins可以支持将所有的action class和view都打包到一个从classloader进行装载的jar文件里面.
关于FreeMarker的更多信息，请访问FreeMarker网站.

FreeMarker与Velocity非 常相似, 它们都是可以在Servlet容器外使用的模版语言. WebWork小组更推荐FreeMarker, 而不是Velocity, 这是因为FreeMarker提供了更好的错误报告, 支持JSP标签, 稍多的功能. 当然, 这两种技术都是代替JSP的很好方案.

快速上手

确认配置好你的项目的classpath中的所有依赖以后, 开始使用FreeMarker就非常简单了. 典型情况下只需要 freemarker.jar. 除它以外, webwork-default.xml已经配置好了将FreeMarker Result映射到你的模版文件. 你现在可以试验一下如下 xwork.xml 配置:

"test" class="com.acme.TestAction">
    "success" type="freemarker">test-success.ftl

然后写好 test-success.ftl:

    


Hello, ${name}

这里 name 是你的action中的一个属性. 这样就可以了! 该文档的余下部分将介绍模版如何被加载, 变量如何解析, tags(标签)也可以使用.

模版加载

Webwork在两个位置查找FreeMarker模版(按顺序):

1. Web应用程序目录(Web application)
2. Class path
   这个顺序对于在完全编译的jar中提供模版很理想, 但是也同时支持在Web应用程序目录中定义这些模版来覆盖jar中的模版文件. 事实上, 这就是为什么你可以覆盖WebWork中默认的UI tags和Form Tags的原理.
   还有, 你可以通过templatePath 上下文变量(context variable)指定一个路径(你的文件系统中的一个目录). 如果指定了该变量, 那么这个目录中的内容将会被优先寻找.

变量解析/决定(Resolution)

在FreeMarker中, 变量将会在多个位置进行寻找, 顺序如下:

1. 值栈(value stack)
2. action上下文(action context)
3. Request范围(scope)
4. Session范围(scope)
5. Application范围(scope)
6. 内建变量
   注意action上下文在value stack后进行搜索. 这意味着你可以引用变量而不必使用标准的符号(#)前缀，不像在JSP中使用ww:property中必须使用的那种语法(译者注:现在在JSP中也可以 不用#而访问默认的ValueStack). 这是一个很好的便利特性, 但是小心, 它有时也会把你陷进去.

   <@ww.url id="url" value="http://"/>
   Click "${url}">here!

Webwork-FreeMarker整合提供的内建变量如下:

Name	Des cription
stack	值栈本身, 方便使用 ${stack.findString('ognl expr')}的方式调用
action	最近执行的action
response	HttpServletResponse
res	与response相同
request	HttpServletRequest
req	与reqeust相同
session	HttpSession
application	ServletContext
base	request的上下文路径(context path)

标签支持

FreeMarker是很棒的模版语言, 因为它完整的支持标签(tag). 参照WebWork提供的 FreeMarker Tags 文档中的如何使用通用(generic) Tags 部分获取更多信息. 除了那些, 你还可以使用任何的JSP标签(tag), 就像这样:

<#assign mytag=JspTaglibs["/WEB-INF/mytag.tld"]>
<@mytag.tagx attribute1="some ${value}"/>

这里 mytag.tld 是你使用的JSP标签库的定义文件. 注意: 为了使用FreeMarker的这个支持, 你必须开启 web.xml 2.1.x compatibility 文档中的 JSPSupportServlet.

提示和技巧

下面是在使用FreeMarker构建WebWork应用程序时的一些有用的进阶功能.

类型转换与本地化

FreeMarker内置支持日期与数字的格式化. 格式化的规则基于action request的地区信息(locale), locale是通过webwork.properties配置的, 它也可以通过I18n Interceptor进行覆盖. 这种方式一般会完美的满足你的需求, 但是你要记住, 这些格式化信息是通过FreeMarker处理的,而不是通过WebWork的类型转换支持实现.
如果你希望WebWork根据你所指定的类型转换处理格式化, 你不应该使用平常的&{...}语法. 取而代之, 你应该使用property标签. 区别在于property标签特别为OGNL表达式设计， 计算它的值， 然后将结果用你指定的Type Conversion转换为String. 平常使用的${...}语法则会使用FreeMarker的表达式语言(EL), 计算它的值, 然后通过内建的格式化规则转化为String. 这些区别甚微, 但是一定要了解.

扩展

有时你可能需要扩展WebWork提供的FreeMarker支持. 最常见的原因是你希望引入你自己的标签, 就像你扩展WebWork内建标签一样.
如果需扩展, 首先要新建一个继承 com.opensymphony.webwork.views.freemarker.FreemarkerManager 并且重载了相应方法的类. 然后将下面代码添加到webwork.properties:

webwork.freemarker.manager.classname = com.yourcompany.YourFreeMarkerManager

ObjectWrapper设置

如果你熟悉了FreeMarker, 你会发现它的敏感性会带来一些困扰. 最常见的方法就是尝试使用FreeMarker提供的BeanWrapper. 如果你不知道那是什么,别担心. 只要知道这些酒可以了:

WebWorkBeanWrapper继承自默认的FreeMarker BeansWrapper, 提供了基本完全一致的功能, 只是修改了maps处理机制. 一般, FreeMarker有两种操作模式: 一种支持友好的内置的map (?key, ?values, etc),但是只支持String作为key; 或者特殊的内置支持(例如: ?key 返回map的相应方法而不是key), 但是它支持String和String相似的非String作为key. WebWork提供了两种情况下的可选的实现方案.
这种特殊的做法也许会让你迷惑或产生问题. 所以, 你可以将 webwork.properties 中的*webwork.freemarker.wrapper.altMap*设置为false, 允许替换为常规的BeansWrapper逻辑.

语法注释

如果是FreeMarker 2.3.4, 还支持另外的语法. 这种可选的语法在你感觉你使用的IDE(尤其是ItelliJ IDEA)在默认的语法下运行困难时非常有用. 关于这种语法的更多内容, 请阅读这里