FreeMarker is a "template engine"; a generic tool to generate text output (anything from HTML to auto generated source code) based on templates.
Configure your action to use the "freemarker" result type
The "freemarker" result type is defined in struts-default.xml
. To create pages using FreeMarker, set the result type of the actions to "freemarker".
<include file="struts-default.xml"/> ... <action name="test" class="package.Test"> <result name="success" type="freemarker">/WEB-INF/views/testView.ftl</result> </action> ...
Using properties
FreeMarker uses the ${...} notation to access properties. They are called interpolations. Properties on the actions (getter methods) will automatically be available on the FreeMarker templates. If an action has a "getName()" method, then its value can be inserted on the template like:
Your name is: ${name}
Property resolution
When a property is referenced in a FreeMarker template, the following scopes will be searched in order, until a value is found:
- variables defined on the template
- value stack (Action properties will be found on this step)
- request attributes
- session attributes
- servlet context attributes
If a property is defined on the template with the same name as a property on the action, FreeMarker will use the property defined locally, on the template.
Be Careful
By default, FreeMarker will throw an error if it finds a variable that is not defined, or has a null value. See this FAQ for details.
Provided objects
The following variables are provided by Struts to the FreeMarker templates:
req
- the current HttpServletRequestres
- the current HttpServletResponsestack
- the current OgnlValueStackognl
- the OgnlTool instance- This class contains useful methods to execute OGNL expressions against arbitrary objects, and a method to generate a select list using the <s:select> pattern. (i.e. taking the name of the list property, a listKey and listValue)
struts
- an instance of StrutsBeanWrapperaction
- the current Struts actionexception
- optional the Exception instance, if the view is a JSP exception or Servlet exception view
FreeMarker configuration
To configure the FreeMarker engine, just add a file freemarker.properties
to the classpath. The supported properties are those that the FreeMarker Configuration object expects, see FreeMarker's documentation for more details.
default_encoding=ISO-8859-1 template_update_delay=5 locale=no_NO
Using Struts tags
Tags distributed with Struts are automatically available to FreeMarker templates. To use any tag add "@s.
" in front of the tag name. Like:
<@s.if test="printName"> <@s.property value="myBeanProperty" /> </@s.if>
Using JSP tags
To use JSP tags that are not part of Struts you have to import the tld. There are two ways of making a tld available to FreeMarker templates:
- Declare the tld on web.xml
- Use FreeMarker's "
assign
" directive. When using the "assign
" directive, provide the full path to the tld file, like:
<#assign ex=JspTaglibs["/WEB-INF/example.tld"] /> <@ex.mytag text="hello" />
FreeMarker alternative syntax
FreeMarker by default uses the "<#directive />" syntax. FreeMarker supports an alternative syntax, where [ and ] are used instead of < and >. To enable the alternative syntax, add #ftl at the beginning of the template. The alternative syntax makes it easier to differentiate between FreeMarker directives, and JSP or HTML tags.
[#ftl] <html> <head>FreeMarker Example</head> <body> <h1>Alternative Syntax</h1> [@s.if test="printName"] [@s.property value="myBeanProperty" /] [/@s.if] </body> </html>
String and Non String Values on tags
In FreeMarker it is incorrect to quote non string values. If a value is quoted, then an string will be passed, instead of the expected object, causing an exception. For example, the "textarea" tag expects the attributes "rows" and "cols" of type Integer:
<@s.textarea label="'Details'" name="'details'" rows=5 cols=40 />