在Servlet中使用FreeMarker

作为基础了解，在web应用程序范畴内使用 FreeMarker 和其它并没有什么不同； FreeMarker将它的输出写入传递给 Template.process 方法的 Writer 对象，它不关心 Writer 将输出写入控制台，文件或是 HttpServletResponse 的输出流。 FreeMarker 并不知道什么是servlet和web；它仅仅是使用模板文件来合并Java对象，之后从它们中间生成输出文本。从这里可知，如何创建一个Web应用程序都随你的习惯来。

但是，你可能想在已经存在的Web应用框架中使用FreeMarker。许多框架都是基于"Model 2"架构的，JSP页面来控制显示。如果你使用了这样的框架(比如Apache Struts)，那么可以继续阅读本文。对于其他框架请参考它们的文档。

在"Model 2"中使用FreeMarker

许多框架依照HTTP请求转发给用户自定义的"action"类，将数据作为属性放在 ServletContext， HttpSession 和 HttpServletRequest 对象中，之后请求被框架派发到一个JSP页面中(视图层)，使用属性传递过来的数据来生成HTML页面，这样的策略通常就是所指的Model 2模型。

使用这样的框架，你就可以非常容易地用FTL文件来代替JSP文件。但是，因为你的Servlet容器(Web应用程序服务器)，不像JSP文件，它可能并不知道如何处理FTL文件，那么就需要对Web应用程序进行一些额外的配置：

复制 freemarker.jar (从FreeMarker发布包的lib目录中) 到Web应用程序的 WEB-INF/lib 目录下。
将下面的部分添加到Web应用程序的 WEB-INF/web.xml 文件中 (调整部分内容是否需要)：

<servlet>
  <servlet-name>freemarker</servlet-name>
  <servlet-class>freemarker.ext.servlet.FreemarkerServlet</servlet-class>
    
  <!-- FreemarkerServlet settings: -->
  <init-param>
    <param-name>TemplatePath</param-name>
    <param-value>/</param-value>
  </init-param>
  <init-param>
    <param-name>NoCache</param-name>
    <param-value>true</param-value>
  </init-param>
  <init-param>
    <param-name>ContentType</param-name>
    <param-value>text/html; charset=UTF-8</param-value> <!-- Forces UTF-8 output encoding! -->
  </init-param>
    
  <!-- FreeMarker settings: -->
  <init-param>
    <param-name>incompatible_improvements</param-name>
    <param-value>2.3.22</param-value>
    <!-- Recommended to set to a high value. For the details, see the Java API docs of
         freemarker.template.Configuration#Configuration(Version). -->
  </init-param>
  <init-param>
    <param-name>template_exception_handler</param-name>
    <!-- Use "html_debug" instead during development! -->
    <param-value>rethrow</param-value>
  </init-param>
  <init-param>
    <param-name>template_update_delay</param-name>
    <!-- ATTENTION, 0 is for development only! Use higher value otherwise. -->
    <param-value>0</param-value>
  </init-param>
  <init-param>
    <param-name>default_encoding</param-name>
    <!-- The encoding of the template files. -->
    <param-value>UTF-8</param-value>
  </init-param>
  <init-param>
    <param-name>locale</param-name>
    <!-- Influences number and date/time formatting, etc. -->
    <param-value>en_US</param-value>
  </init-param>
  <init-param>
    <param-name>number_format</param-name>
    <param-value>0.##########</param-value>
  </init-param>

  <load-on-startup>1</load-on-startup>
</servlet>

<servlet-mapping>
  <servlet-name>freemarker</servlet-name>
  <url-pattern>*.ftl</url-pattern>
</servlet-mapping>

...

<!--
  Prevent the visiting of MVC Views from outside the servlet container.
  RequestDispatcher.forward/include should, and will still work.
  Removing this may open security holes!
-->
<security-constraint>
  <web-resource-collection>
    <web-resource-name>FreeMarker MVC Views</web-resource-name>
    <url-pattern>*.ftl</url-pattern>
  </web-resource-collection>
  <auth-constraint>
    <!-- Nobody is allowed to visit these directly. -->
  </auth-constraint>
</security-constraint>

在这之后，你可以像使用JSP(*.jsp) 文件那样使用FTL文件(*.ftl)了。 (当然你可以选择除 ftl 之外的扩展名；这只是惯例)

Note:

它是怎么工作的？让我们先来看看JSP是怎么工作的。许多servlet容器处理JSP时使用一个映射为 *.jsp 的servlet请求URL格式。这样servlet就会接收所有URL是以 .jsp 结尾的请求，查找请求URL地址中的JSP文件，内部编译后生成 Servlet，然后调用生成好的serlvet来生成页面。这里为URL类型是 *.ftl 映射的 FreemarkerServlet 也是相同功能，只是FTL文件不会编译成 Servlet，而是给 Template 对象，之后 Template 对象的 process 方法就会被调用来生成页面。

比如，代替这个JSP页面 (注意它使用了Struts标签库来保存设计，而不是嵌入可怕的Java代码)：

<%@ taglib uri="/WEB-INF/struts-bean.tld" prefix="bean" %>
<%@ taglib uri="/WEB-INF/struts-logic.tld" prefix="logic" %>

<html>
<head><title>Acmee Products International</title>
<body>
  <h1>Hello <bean:write name="user"/>!</h1>
  <p>These are our latest offers:
  <ul>
    <logic:iterate name="latestProducts" id="prod">
      <li><bean:write name="prod" property="name"/>
        for <bean:write name="prod" property="price"/> Credits.
    </logic:iterate>
  </ul>
</body>
</html>

你可以使用这个FTL文件(使用 ftl 扩展名而不是 jsp)：

<html>
<head><title>Acmee Products International</title>
<body>
  <h1>Hello ${user}!</h1>
  <p>These are our latest offers:
  <ul>
    <#list latestProducts as prod>
      <li>${prod.name} for ${prod.price} Credits.
    </#list>
  </ul>
</body>
</html>

Warning!

在 FreeMarker 中，<html:form action="/query">...</html:form> 仅仅被视为是静态文本，所以它会按照原本输出出来了，就像其他XML或HTML标记一样。 JSP标签也仅仅是FreeMarker的指令，没有什么特殊之处，所以你可以 使用FreeMarker语法 形式来调用它们，而不是JSP语法： <@html.form action="/query">...</@html.form>。注意在FreeMarker语法中 不能像JSP那样在参数中使用 ${...}，而且不能给参数值加引号。所以这样是错误的：

<#-- WRONG: -->
<@my.jspTag color="${aVariable}" name="aStringLiteral"
            width="100" height=${a+b} />

但下面这样是正确的：

<#-- Good: -->
<@my.jspTag color=aVariable name="aStringLiteral"
            width=100 height=a+b />

在这两个模板中，当你要引用 user 和 latestProduct 时，首先它会尝试去查找已经在模板中创建的同名变量 (比如 prod；如果你使用JSP：这是一个page范围内的属性)。如果那样做不行，它会尝试在 HttpServletRequest 对象中查找那个名字的属性，如果没有找到就在 HttpSession 中找，如果还没有找到那就在 ServletContext 中找。FTL按这种情况工作是因为 FreemarkerServlet 创建数据模型由上面提到的3个对象中的属性而来。那也就是说，这种情况下根哈希表root不是 java.util.Map (正如本手册中的一些例子那样)，而是 ServletContext+HttpSession+HttpServletRequest ；FreeMarker 在处理数据模型类型的时候非常灵活。所以如果你想将变量 "name" 放到数据模型中，那么你可以调用 servletRequest.setAttribute("name", "Fred")；这是模型2的逻辑，而 FreeMarker 将会适应它。

FreemarkerServlet 也会在数据模型中放置3个哈希表，这样你就可以直接访问3个对象中的属性了。这些哈希表变量是：Request， Session，Application (和ServletContext对应)。它还会暴露另外一个名为 RequestParameters 的哈希表，这个哈希表提供访问HTTP请求中的参数。

FreemarkerServlet 也有很多初始参数。它可以被设置从任意路径来加载模板，从类路径下，或相对于Web应用程序的目录。你可以设置模板使用的字符集。你还可以设置想使用的对象包装器等等。

通过子类别，FreemarkerServlet 易于定制特殊需要。那就是说，如果你需要对所有模板添加一个额外的可用变量，使用servlet的子类，覆盖 preTemplateProcess() 方法，在模板被执行前，将你需要的额外数据放到模型中。或者在servlet的子类中，在 Configuration 中设置这些全局的变量作为共享变量。

要获取更多信息，可以阅读该类的Java API文档。

包含其它Web应用程序资源中的内容

你可以使用由 FreemarkerServlet (2.3.15版本之后) 提供的客户化标签<@include_page path="..."/> 来包含另一个Web应用资源的内容到输出内容中；这对于整合JSP页面 (在同一Web服务器中生活在FreeMarker模板旁边) 的输出到FreeMarker模板的输出中非常有用。使用：

<@include_page path="path/to/some.jsp"/>

和在JSP中使用该标签是相同的：

<jsp:include page="path/to/some.jsp">

Note:

<@include_page ...> 不能和 <#include ...>搞混，后者是为了包含FreeMarker模板而不会牵涉到Servlet容器。使用 <#include ...> 包含的模板和包含它的模板共享模板处理状态，比如数据模型和模板语言变量，而 <@include_page ...> 开始一个独立的HTTP请求处理。

Note:

一些Web应用框架为此提供它们自己的解决方案，这种情况下你就可以使用它们来替代。而一些Web应用框架不使用 FreemarkerServlet，所以 include_page 是不可用的。

路径可以是相对的，也可以是绝对的。相对路径被解释成相对于当前HTTP请求 (一个可以触发模板执行的请求)的URL，而绝对路径在当前的servlet上下文 (当前的Web应用)中是绝对的。你不能从当前Web应用的外部包含页面。注意你可以包含任意页面，而不仅仅是JSP页面；我们仅仅使用以 .jsp 结尾的页面作为说明。

除了参数 path 之外，你也可以用布尔值 (当不指定时默认是true)指定一个名为 inherit_params 可选的参数来指定被包含的页面对当前的请求是否可见HTTP请求中的参数。

最后，你可以指定一个名为 params 的可选参数，来指定被包含页面可见的新请求参数。如果也传递继承的参数，那么指定参数的值将会得到前缀名称相同的继承参数的值。params 的值必须是一个哈希表类型，它其中的每个值可以是字符串，或者是字符串序列(如果你需要多值参数)。这里给出一个完整的示例：

<@include_page path="path/to/some.jsp" inherit_params=true params={"foo": "99", "bar": ["a", "b"]}/>

这会包含 path/to/some.jsp 页面，传递它的所有的当前请求的参数，除了"foo"和"bar"，这两个会被分别设置为"99"和多值序列"a"，"b"。如果原来请求中已经有这些参数的值了，那么新值会添加到原来存在的值中。那就是说，如果"foo"有值"111"和"123"，那么现在它会有"99"，"111"，"123"。

事实上使用 params 给参数传递非字符串值是可能的。这样的一个值首先会被转换为适合的Java对象 (数字，布尔值，日期等)，之后调用它们Java对象的 toString() 方法来得到字符串值。最好不要依赖这种机制，作为替代，明确参数值在模板级别不能转换成字符串类型之后，在使用到它的地方可以使用内建函数 ?string 和 ?c。

在FTL中使用自定义JSP标签

FreemarkerServlet 将一个哈希表类型的 JspTaglibs 放到数据模型中，就可以使用它来访问JSP标签库了。自定义JSP标签库将被视为普通用户自定义指令来访问，自定义EL函数 (从 FreeMarker 2.3.22 版本开始)视为方法。例如，这个JSP文件：

<%@ page contentType="text/html;charset=ISO-8859-2" language="java"%>
<%@ taglib prefix="e" uri="/WEB-INF/example.tld" %>
<%@ taglib prefix="oe" uri="/WEB-INF/other-example.tld" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<%@ taglib prefix="fn" uri="http://java.sun.com/jsp/jstl/functions" %>

<%-- Custom JSP tags and functions: --%>

<e:someTag numParam="123" boolParam="true" strParam="Example" anotherParam="${someVar}">
  ...
</e:someTag>

<oe:otherTag />

${e:someELFunction(1, 2)}


<%-- JSTL: --%>

<c:if test="${foo}">
  Do this
</c:if>

<c:choose>
  <c:when test="${x == 1}">
      Do this
  </c:when>
  <c:otherwise>
      Do that
  </c:otherwise>
</c:choose>

<c:forEach var="person" items="${persons}">
  ${person.name}
</c:forEach>

${fn:trim(bar)}

基本一致的FTL是：

<#assign e=JspTaglibs["/WEB-INF/example.tld"]>
<#assign oe=JspTaglibs["/WEB-INF/other-example.tld"]>

<#-- Custom JSP tags and functions: --#>

<@e.someTag numParam=123 boolParam=true strParam="Example" anotherParam=someVar>
  ...
</@e.someTag>

<@oe.otherTag />

${e.someELFunction(1, 2)}


<#-- JSTL - Instead, use native FTL constructs: -->

<#if foo>
  Do this
</#if>

<#if x == 1>
  Do this
<#else>
  Do that
</#if>

<#list persons as person>
  ${person.name}
</#list>

${bar?trim}

Note:

参数值没有使用引号，而且 "${...}" 和JSP中使用的一样。后面会详细解释。

Note:

JspTaglibs 不是 FreeMarker 的核心特性；它只存在于通过 FreemarkerServlet 调用的模板。这是因为JSP 标签/函数假定一个servlet环境(FreeMarker不会)，加上一些Servlet概念被模仿成 FreemarkerServlet 创建的特定Freemarker数据模型。很多现代开发框架以纯净的方式使用FreeMarker，而不是通过 FreemarkerServlet。

因为自定义JSP标签是在JSP环境中来书写操作的，它们假设变量 (在JSP中常被指代"beans")被存储在4个范围中：page范围，request范围， session范围和application范围。FTL没有这样的表示法(4种范围)，但是 FreemarkerServlet给自定义标签提供仿真的环境，这样就可以维持JSP范围中的"beans"和FTL变量之间的对应关系。对于自定义的JSP标签，请求request，会话session和应用application是和真实JSP相同的： javax.servlet.ServletContext，HttpSession 和 ServletRequest 对象中的属性。从FTL的角度来看，这三种范围都在数据模型中，这点前面已经解释了。page范围和FTL全局变量(参见global指令)是对应的。那也就是，如果你使用 global 指令创建一个变量，通过仿真的JSP环境，它会作为page范围变量对自定义标签可见。而且，如果一个JSP标签创建了一个新的page范围变量，那么结果和用 global 指令创建的是相同的。要注意在数据模型中的变量作为page范围的属性对JSP标签是不可见的，尽管它们在全局是可见的，因为数据模型和请求，会话，应用范围是对应的，而不是page范围。

在JSP页面中，你可以对所有属性值加引号，这和参数类型是字符串，布尔值或数字没有关系。但是因为在FTL模板中自定义标签可以被用户自定义FTL指令访问到，你将不得不在自定义标签中使用FTL语法规则，而不是JSP语法。所以当你指定一个"属性"的值时，那么在 = 的右边是一个 FTL 表达式。因此， 你不能对布尔值和数字值的参数加引号 (比如：<@tiles.insert page="/layout.ftl" flush=true/>)，否则它们将被解释为字符串值，当FreeMarker试图传递值到期望非字符串值的自定义标记中时，这就会引起类型不匹配错误。而且还要注意，这很自然，你可以使用任意FTL表达式作为属性的值，比如变量，计算的结果值等。(比如：<@tiles.insert page=layoutName flush=foo && bar/>)

Servlet容器运行过程中，因为它实现了自身的轻量级JSP运行时环境，它用到JSP标签库，而 FreeMarker 并不依赖于JSP支持。这是一个很小但值得注意的地方：在它们的TLD文件中，开启 FreeMarker 的JSP运行时环境来分发事件到JSP标签库中注册时间监听器，你应该将下面的内容添加到Web应用下的 WEB-INF/web.xml 文件中：

<listener>
  <listener-class>freemarker.ext.jsp.EventForwarding</listener-class>
</listener>

请注意，尽管servlet容器没有本地的JSP支持，你也可以在 FreeMarker 中使用JSP标签库。只是确保对JSP 1.2版本(或更新)的 javax.servlet.jsp.* 包在Web应用程序中可用就行。如果你的servlet容器只对JSP 1.1支持，那么你不得不将下面六个类(比如你可以从Tomcat 5.x或Tomcat 4.x的jar包中提取)复制到Web应用的 WEB-INF/classes/...目录下： javax.servlet.jsp.tagext.IterationTag， javax.servlet.jsp.tagext.TryCatchFinally， javax.servlet.ServletContextListener， javax.servlet.ServletContextAttributeListener， javax.servlet.http.HttpSessionAttributeListener， javax.servlet.http.HttpSessionListener。但是要注意，因为容器只支持JSP 1.1，通常是使用较早的Servlet 2.3之前的版本，事件监听器可能就不支持，因此JSP 1.2标签库来注册事件监听器会正常工作。

在撰写本文档时，JSP已经升级到2.1了，许多特性也已经实现了，除了JSP 2(也就是说JSP自定义标记在JSP语言中实现了)的"标签文件"特性。标签文件需要被编译成Java类文件，在 FreeMarker 下才会有用。

JspTaglibs[uri] 会去找到URI指定的TLD，就像JSP的 @taglib 指令所做的。它实现了JSP规范中所描述的TLD发现机制。这里可以阅读更多，但简而言之，它会在 WEB-INF/web.xml taglib 元素中，在 WEB-INF/**/*.tld 文件中，还有 WEB-INF/lib/*.{jar,zip}/META-INF/**/*.tld 文件中寻找TLD。此外，当设置了 FreemarkerServlet 的初始化参数(从 2.3.22版本开始) MetaInfTldSources 和/或 ClasspathTlds，即便是在WAR结构之外，它也会发现对于类加载器可见的TLD。参考 FreemarkerServlet 的Java API文档来获取更多描述。它也可以从Java系统属性中来设置，当你想在Eclipse运行配置中来修改而不去修改 web.xml时，就可以随手完成；再强调一点，请参考 FreemarkerServlet API 文档。 FreemarkerServlet 也会识别 org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern servlet 上下文属性，并且将它中间的配置项添加到 MetaInfTldSources。

在JSP页面中嵌入FTL

有一个标签库允许你将FTL片段放到JSP页面中。嵌入的FTL片段可以访问JSP 的4种范围内的属性(Beans)。你可以在 FreeMarker 发布包中找到一个可用的示例和这个标签库。

Previous Next

在Servlet中使用FreeMarker

在"Model 2"中使用FreeMarker

包含其它Web应用程序资源中的内容

在FTL中使用自定义JSP标签

在JSP页面中嵌入FTL

Overview

Handy stuff

Community