FreeMarker is a template Java template language that is a great alternative to JSP. FreeMarker is ideal for situations where your action results can possibly be loaded from outside a Servlet container. For example, if you wished to support plugins in your application, you might wish to use FreeMarker so that the plugins could provide the entire action class and view in a single jar that is loaded from the classloader.

For more information on FreeMarker itself, please visit the FreeMarker website.

FreeMarker is very similar to Velocity, as both are template languages that can be used outside of a Servlet container. The WebWork team recommends FreeMarker over Velocity simply because FreeMarker has better error reporting, support for JSP tags, and slightly better features. However, both are good alternatives to JSP.

Getting Started

Getting started with FreeMarker is as simple as ensuring all the dependencies are included in your project's classpath. This typically requires simply freemarker.jar. Other than that, webwork-default.xml already configures the FreeMarker Result needed to map your actions to your templates. You may now try out the following xwork.xml configuration:

<action name="test" class="com.acme.TestAction">
    <result name="success" type="freemarker">test-success.ftl</result>
</action>

Then in test-success.ftl:

<html>
<head>
    <title>Hello</title>
</head>
<body>

Hello, ${name}

</body>
</html>

Where name is a property on your action. That's it! Read the rest of this document for details on how templates are loaded, variables are resolved, and tags can be used.

Template Loading

WebWork looks for FreeMarker templates in two locations (in this order):

Web application
Class path

This ordering makes it ideal for providing templates inside a fully built jar, but allowing for overrides of those templates to be defined in your web application. In fact, this is how you can override the default UI tags and Form Tags included with WebWork.

Variable Resolution

In FreeMarker, variables are looked up in several different places, in this order:

The value stack
The action context
Request scope
Session scope
Application scope
Built-in variables

Note that the action context is looked up after the value stack. This means that you can reference the variable without the typical preceding has marker (#) like you would have to when using the JSP ww:property tag. This is a nice convenience, though be careful because there is a small chance it could trip you up.

<@ww.url id="url" value="http://www.yahoo.com"/>
Click <a href="${url}">here</a>!

The built-in variables that WebWork-FreeMarker integration provides are:

Name	Description
stack	The value stack itself, useful for calls like ${stack.findString('ognl expr')}
action	The action most recently executed
response	The HttpServletResponse
res	Same as response
request	The HttpServletRequest
req	Same as request
session	The HttpSession
application	The ServletContext
base	The request's context path

Tag Support

FreeMarker is a great template language because it has complete tag support. See the FreeMarker Tags documentation for information on how to use the generic Tags provided by WebWork. In addition to this, you can use any JSP tag, like so:

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

Where mytag.tld is the JSP Tag Library Definition file for your tag library. Note: in order to use this support in FreeMarker, you must enable the JSPSupportServlet documented in web.xml 2.1.x compatibility.

Tips and Tricks

There are some advanced features that may be useful when building WebWork applications with FreeMarker.

Extending

Sometimes you may with to extend the FreeMarker support provided with WebWork. The most common reason for doing this is that you wish to include your own Tags, such as those that you have extended from the built in WebWork Tags.

To do so, write a new class that extends com.opensymphony.webwork.views.freemarker.FreemarkerManager and overrides it as needed. Then add the following to webwork.properties:

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

ObjectWrapper Settings

Once you get familiar with FreeMarker, you will find certain subtleties with it that may become frustrating. The most common thing you'll likely run in to is the BeansWrapper provided by FreeMarker. If you don't know what this is, don't worry. However, if you do, know this: the default FreeMarkerManager provided by WebWork uses a default BeansWrapper instance with one change: setSimpleMapWrapper() is set to false.

This means that when referencing maps, you must use map.size() rather than map?size. Also, you may have to get map values by calling map.get(foo) rather than mapfoo, especially if foo is not a String.

Syntax Notes

As of FreeMarker 2.3.4, an alternative syntax is supported. This alternative syntax is great if you find that your IDE (especially IntelliJ IDEA) makes it difficult to work with the default syntax. You can read more about this syntax here.

Child pages

FreeMarker