14.4. Velocity和FreeMarker - Spring Framework reference 2.0.5 参考手册中文版

这个文件是可选的，不过一旦指定，其所包含的值即影响Velocity运行时状态。只有当你要做一些高级配置时才需要这个文件，这时你可以在上面定义的 VelocityConfigurer 中指定它的位置。

<bean id="velocityConfig" class="org.springframework.web.servlet.view.velocity.VelocityConfigurer">
  <property name="configLocation value="/WEB-INF/velocity.properties"/>
</bean>

另一种方法，你可以直接在Velocity config bean的定义中指定velocity属性，来取代"configLocation"属性。

<bean id="velocityConfig" class="org.springframework.web.servlet.view.velocity.VelocityConfigurer">
  <property name="velocityProperties">
    <props>
      <prop key="resource.loader">file</prop>
      <prop key="file.resource.loader.class">
        org.apache.velocity.runtime.resource.loader.FileResourceLoader
      </prop>
      <prop key="file.resource.loader.path">${webapp.root}/WEB-INF/velocity</prop>
      <prop key="file.resource.loader.cache">false</prop>
    </props>
  </property>
</bean>
				

关于Spring中Velocity的配置请参考 API文档，或者参考Velocity自身文档中的例子和定义来了解如何配置 'velocity.properties'。

FreeMarker的'Settings'和'SharedVariables'配置可以通过直接设置 FreeMarkerConfigurer 的相应属性来传递给Spring管理的FreeMarker Configuration 对象，其中 freemarkerSettings 属性需要一个 java.util.Properties 类型对象，freemarkerVariables 需要一个 java.util.Map 类型对象。

<bean id="freemarkerConfig" class="org.springframework.web.servlet.view.freemarker.FreeMarkerConfigurer">
  <property name="templateLoaderPath" value="/WEB-INF/freemarker/"/>
  <property name="freemarkerVariables">
    <map>
      <entry key="xml_escape" value-ref="fmXmlEscape"/>
    </map>
  </property>
</bean>

<bean id="fmXmlEscape" class="freemarker.template.utility.XmlEscape"/>

关于settings和variables如何影响 Configuration 对象的细节信息，请参考FreeMarker的文档。

spring.jar 文件为这两种语言维护了一套标准宏，对于正确配置的应用，它们总是可用的，前提是你将VelocityView bean 或者 FreeMarkerView bean 的 exposeSpringMacroHelpers 属性设为'true'。其实还有更方便的方法，如果你恰好在使用 VelocityViewResolver 或 FreeMarkerViewResolver，你也可以设置它们的这个属性，这样你的视图都会继承这个值。注意，对任何HTML表单处理方面的问题来说，这个属性是 不必要 的，除非 你确定需要Spring宏提供的好处。下面是一份view.properties文件的例子，其中展示了对这两种语言都适用的正确配置。

personFormV.class=org.springframework.web.servlet.view.velocity.VelocityView
personFormV.url=personForm.vm
personFormV.exposeSpringMacroHelpers=true

personFormF.class=org.springframework.web.servlet.view.freemarker.FreeMarkerView
personFormF.url=personForm.ftl
personFormF.exposeSpringMacroHelpers=true

下面是一个完整的Spring Web MVC 配置文件。通过这个配置，每个Velocity视图都可以调用标准的 Velocity宏命令。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN 2.0//EN" "http://www.springframework.org/dtd/spring-beans-2.0.dtd">

<beans>

    <bean name="helloController" class="info.wilhelms.springwebapp.SampleController">
        <property name="commandName" value="command"/>
        <property name="commandClass" value="info.wilhelms.springwebapp.Message"/>
        <property name="formView" value="foo"/>
        <property name="successView" value="banjo"/>
        <property name="bindOnNewForm" value="true"/>
        <property name="sessionForm" value="true"/>
    </bean>

    <bean id="velocityConfig"
          class="org.springframework.web.servlet.view.velocity.VelocityConfigurer">
        <property name="resourceLoaderPath" value="/WEB-INF/velocity/"/>
    </bean>

    <bean id="viewResolver" class="org.springframework.web.servlet.view.velocity.VelocityViewResolver">
        <property name="cache" value="false"/>
        <property name="prefix" value=""/>
        <property name="suffix" value=".vm"/>
        <property name="exposeSpringMacroHelpers" value="true"/>
    </bean>

    <bean class="org.springframework.web.servlet.handler.SimpleUrlHandlerMapping">
        <property name="mappings">
            <value>
                **/hello.htm=helloController
            </value>
        </property>
    </bean>

</beans>

Spring 库中定义的一些宏被认为是内部的（私有的），但宏定义中没有这种限制范围的方式，这使得对调用代码和用户模板来说，所有的宏都是可见的。下面的内容集中于供用户模板直接调用的宏。如果你希望看看宏定义的代码，可以分别参考 org.springframework.web.servlet.view.velocity 包中的spring.vm文件和 org.springframework.web.servlet.view.freemarker 包中的spring.ftl文件。

在扮演Spring表单控制器对应视图的html表单（或vm/ftl模板）里，你可以模仿下面的代码来绑定表单数据并显示错误信息（和JSP的形式非常相似）。注意默认情况下命令对象的名字是"command"，你可以在配置自己的表单控制器时通过设置'commandName'属性来覆盖默认值。例子代码如下（其中的 personFormV 和 personFormF 是前面定义的视图）：

<!-- velocity宏自动可用 -->
<html>
...
<form action="" method="POST">
  Name: 
  #springBind( "command.name" )
  <input type="text" 
    name="${status.expression}" 
    value="$!status.value" /><br>
  #foreach($error in $status.errorMessages) <b>$error</b> <br> #end
  <br>
  ... 
  <input type="submit" value="submit"/>
</form>
...
</html>

<!-- FreeMarker宏必须导入到一个名称空间，这里推荐你定义为'spring'空间 -->
<#import "spring.ftl" as spring />
<html>
...
<form action="" method="POST">
  Name: 
  <@spring.bind "command.name" /> 
  <input type="text" 
    name="${spring.status.expression}" 
    value="${spring.status.value?default("")}" /><br>
  <#list spring.status.errorMessages as error> <b>${error}</b> <br> </#list>
  <br>
  ... 
  <input type="submit" value="submit"/>
</form>
...
</html>

#springBind / <@spring.bind> 需要一个'path'属性，格式为命令对象的名字（默认值为'command'，除非你在配置FormController的属性时改变它）后跟圆点再加上你希望绑定到的命令对象的属性名。你也可以使用类似"command.address.street"的格式来处理嵌套对象。使用 bind 宏时，HTML转码行为由web.xml中名为 defaultHtmlEscape 的ServletContext参数指定。

上述宏的另一种可选形式是 #springBindEscaped / <@spring.bindEscaped>，它另外接受一个布尔型参数，显式指定了输出值或错误信息这些状态信息时是否使用HTML转码。附加的表单处理宏简化了HTML转码的使用，只要有可能，你就应该使用它们。关于它们的细节将在下节讲述。

为这两种语言附加的一些很方便的宏同时简化了表单绑定和表单生成（包括显示校验错误信息）。不需要使用这些宏来生成表单输入域，它们可以被混杂并匹配到简单HTML，或者直接调用前面讲过的spring绑定宏。

下表展示了可用的宏的VTL定义和FTL定义，以及它们需要的参数。

* 在FTL（FreeMarker）中，这二种宏实际上并不是必需的，因为你可以使用普通的 formInput 宏，指定fieldType参数的值为 'hidden' 或 'password'即可 。

上面列出的所有宏的参数都具有一致的含义，如下述：

宏的例子在下面描述，其中一些是FTL的，一些是VTL的。两种语言之间的用法差别在旁注中解释。

<!-- 上面提到的Name域的例子，使用VTL中定义的表单宏 -->
...
    Name:
    #springFormInput("command.name" "")<br>
    #springShowErrors("<br>" "")<br>

<@spring.formInput "command.name"/>
<@spring.showErrors "<br>"/>

Name:
  <input type="text" name="name" value=""     
>
<br>
  <b>required</b>
<br>
<br>

...
  Town:
  <@spring.formRadioButtons "command.address.town", cityMap, "" /><br><br>

Town:
<input type="radio" name="address.town" value="London">
London
<input type="radio" name="address.town" value="Paris" checked="checked">
Paris
<input type="radio" name="address.town" value="New York">
New York

protected Map referenceData(HttpServletRequest request) throws Exception {
  Map cityMap = new LinkedHashMap();
  cityMap.put("LDN", "London");
  cityMap.put("PRS", "Paris");
  cityMap.put("NYC", "New York");
  
  Map m = new HashMap();
  m.put("cityMap", cityMap);
  return m;
}

Town:
<input type="radio" name="address.town" value="LDN">
London
<input type="radio" name="address.town" value="PRS" checked="checked">
Paris
<input type="radio" name="address.town" value="NYC">
New York

缺省情况下使用上面这些宏将产生符合HTML 4.01标准的标签，并且Spring的绑定支持使用web.xml中定义的HTML转码行为。为了产生符合XHTML标准的标签以及覆盖默认的HTML转码行为，你可以在你的模板（或者模板可见的模型对象）中指定两个变量。在模板中指定的好处是稍后的模板处理中可以为表单中不同的域指定不同的行为。

要切换到符合XHTML的输出，你可以设置model/context变量xhtmlCompliant的值为true：

## for Velocity..
#set($springXhtmlCompliant = true)

<#-- for FreeMarker -->
<#assign xhtmlCompliant = true in spring>

在进行完这些处理之后，由Spring宏产生的所有标签都符合XHTML标准了。

类似地，可以为每个输入域指定HTML转码行为：

<#-- 该句覆盖默认HTML转码行为 -->

<#assign htmlEscape = true in spring>
<#-- next field will use HTML escaping -->
<@spring.formInput "command.name" />

<#assign htmlEscape = false in spring>
<#-- all future fields will be bound with HTML escaping off -->