FreeMarker & Velocity Views

A plain name such as title is resolved in this order, first match wins (ScopesHashModel.get): the entries of the data model above, the value stack, the action context, the request attributes, the session attributes, then the application attributes. That ordering is the reason ${book.title} needs no # prefix as <s:property value="#request.x"/> does in a JSP, and also the reason a request attribute named like an action property is hidden by the property.

Source: Apache Struts — FreeMarker, Servlet / JSP Scoped Objects

The same values reached through the s tag macros (OGNL-tag) use OGNL and the hash #request, while FreeMarker reads the hash models Request and Session. Mixing the two works, but choose one style per template. Note that filter-on-action only prints x because the action’s setFilter carries @StrutsParameter; the request parameter itself is always readable as Parameters.filter whether or not the action accepts it.

A FreeMarker tag call takes attributes in two forms, and they are evaluated differently. A quoted string is handed to the tag as a string, and the tag evaluates it as OGNL for the attributes it declares (value="title", list="books", test="title == 'Dune'", value="%{#request.wishlist}"), converting the result to the attribute’s type. An unquoted value is a FreeMarker expression, evaluated by FreeMarker before the tag sees it; FTL lists, hashes and numbers pass through as objects. The next examples show where the two meet.

Source: Apache Struts — FreeMarker Tags, Attribute Types

The documentation example list="%{1, 2, 3}" rendered an empty select on 7.4.0; use the OGNL form list="{1, 2, 3}" (no %) or an FTL sequence. Where the tag needs a number (size, rows, cols), both size="20" and cols=5 worked in the native macros; the "must be a number" rule that the Struts docs state applies to the JSP tag library bridge.

Inline attributes also replace the param tag for the tags that take parameters. The query-string builder url shows the four forms and a trap in the first:

Source: Apache Struts — FreeMarker Tags, Attributes and Parameters

Line A is the example from the documentation, and in 7.4.0 the %{...} is not evaluated for an inline parameter: the literal text is URL-encoded into the query string. Line B passes an FTL expression, which works; line C is the param tag, which evaluates OGNL; line D stores the URL in a variable, and printing the variable with ${u} escapes the already escaped ampersand a second time (&), so use ?no_esc there or print the URL by leaving var out (A to C print it directly).

The Struts control tags (iterator, if, else, set, property) exist as macros, but FreeMarker has its own directives that are faster and need no OGNL, and the performance-tuning guide of Struts recommends using the FreeMarker equivalent instead of the JSP tags. The two are interchangeable for the Bookshelf catalogue:

Source: Apache Struts — Performance Tuning, Use the FreeMarker equivalent

Inside <@s.iterator> the current element is on top of the value stack, so <@s.property value="title"/> (OGNL) and ${title} (the FreeMarker lookup of the stack) both read the book’s title; inside <#list> only the loop variable b is the book and ${title} would read the action’s title. That difference is the most common source of wrong output when a JSP is converted.

Since Struts 7.0 the tag templates read attributes where earlier versions read parameters, as the FreeMarker Tags page notes. A tag template is the FTL file that draws one tag (the xhtml theme’s controlfooter.ftl, for example); overriding it from the web application changes every form field. The extra, unknown attribute description of the form field below is reachable as ${attributes.description} in that template:

Source: Apache Struts — FreeMarker Tags, Using inline attributes with templates

Two details of the output are not in the documentation. The description attribute was also written into the <input> element as an HTML attribute, because every attribute the tag does not know becomes a dynamic attribute and dynamic attributes are copied to the element; and a dynamic attribute value is not evaluated for OGNL on a text field (foo="checked: %{title}" was printed as written), only the templates that set evaluate_dynamic_attributes do that. Hyphenated attribute names need the hash syntax, dynamicAttributes={"data-ajax":"false"}, which printed data-ajax="false".

Source: Apache Struts — FreeMarker Support, Dynamic attributes support

A freemarker.properties file on the classpath (typically src/main/resources) holds any setting that the FreeMarker Configuration understands. Struts reads it once, when the engine is created, and applies each key with Configuration.setSetting.

Source: Apache Struts — FreeMarker Support, FreeMarker configuration with recent releases

Source: Apache FreeMarker — Configuration settings

incompatible_improvements is 2.3.34 by default in Struts 7.4.0, which is behind the library’s own 2.3.35 so that FreeMarker’s newer behaviour changes are off. It is raised from web.xml, not from freemarker.properties:

Source: Apache Struts — FreeMarker, Incompatible Improvements

Source: Apache FreeMarker — Incompatible improvements

The comment in the Struts docs says a higher number can change the pages and the Struts tags, so a change needs the full set of views re-tested.

Source: Apache Struts 7.4.0 — default.properties

Source: Apache Struts — Performance Tuning, Enable FreeMarker template caching

The constant struts.freemarker.templatesCache is listed in default.properties only as a commented-out line and has no injection point in 7.4.0 (the FreeMarker page says the option was removed). The FreeMarker page also says the update delay defaults to 60 seconds; the verification showed otherwise. A template edited in the deployed WAR showed up between 4 and 6 seconds later with no constant set:

Source: Apache Struts — FreeMarker, Cache

Set struts.freemarker.templatesCache.updateDelay to a long time (3600 s) in production, where templates do not change, and to a short one in a development server.

Since 7.2.0 Struts compiles templates with whitespace stripping on. A line that contains only an FTL directive is removed together with its indentation, which shrinks the HTML. A template that shows the effect:

Source: Apache Struts — FreeMarker Support, FreeMarker Whitespace Stripping

Source: Apache Struts — Performance Tuning, Enable FreeMarker whitespace stripping

Source: Apache FreeMarker — White-space stripping

The $ is the end of the line (cat -e). Stripping removed the directive-only lines together with their blank leftovers; the first <li> keeps extra indentation, which does not change how the browser renders the list. The constant turns itself off in development mode so that the generated output stays easy to read.

FreemarkerManager.createTemplateLoader builds a MultiTemplateLoader. It searches, in this order: a directory or classpath location given as the TemplatePath context parameter (prefix file:// or class://), then the web application, then the classpath. That order is why an application can override a template that ships inside the Struts jar: the copy in the web application wins.

A file ext/ext.ftl under that directory was rendered by <result type="freemarker">/ext/ext.ftl</result> and printed external template: Dune / Bookshelf (the second value is explained in A Custom FreemarkerManager). A file at WEB-INF/views/hello.ftl under the same directory replaced the web application’s hello.ftl:

Source: Apache Struts — FreeMarker, Template Loading

Source: Apache FreeMarker — Template loading

The override appeared only after the application was redeployed: FreeMarker’s MultiTemplateLoader remembers which loader found a template last and asks it first, so a file added later to a loader that was not consulted is not noticed until the engine restarts. Add overrides before the first request, or restart. The Struts documentation notes that the template path is not relative to the application root.

FreeMarker wraps Java objects with an object wrapper. Struts uses StrutsBeanWrapper, which extends the BeansWrapper but changes maps. FreeMarker normally supports either friendly map built-ins (?keys, ?values) with String keys only, or no built-ins and any key type; the Struts wrapper gives both. The Bookshelf stock map in the layout example is printed key by key with ${stock[k]} and stock?keys. If the special behaviour causes trouble, the constant struts.freemarker.wrapper.altMap set to false restores the standard wrapper.

Source: Apache Struts — FreeMarker, ObjectWrapper Settings

The manager can be replaced to add variables to every template, change the template loader or extend the configuration. The constant struts.freemarker.manager.classname names a subclass; the method to override for shared variables is populateContext.

Every template can now print ${appName!"(no appName)"}; the external template of the previous section printed Bookshelf.

Source: Apache Struts — FreeMarker, Extending

Source: Apache Struts 7.4.0 — FreemarkerManager

The context holds the same built-ins as the FreeMarker model; the names verified on 7.4.0 are listed below, with the ones the older documentation mentions but that do not resolve.

Source: Apache Struts — Velocity

Properties of the action resolve with Velocity’s own reference syntax through the value stack ($title calls getTitle() on the action), and $struts is the helper VelocityStrutsUtil: $struts.findString('title'), $struts.getText('book.heading'), $struts.urlEncode('a b&c') (which printed a+b%26c) and $struts.translateVariables(...). Velocity 2.4 sets $foreach.count; the $velocityCount of older Velocity is not set.

Each Struts tag is a Velocity directive named #s plus the tag name, with the attributes as quoted name=value strings: #sform ("action=hello" "method=get"). The plugin registers 37 of them (read from its jar): #saction, #sactionerror, #sactionmessage, #sa, #sbean, #scheckbox, #scheckboxlist, #scombobox, #scomponent, #sdate, #sdoubleselect, #sfielderror, #sfile, #sform, #shead, #shidden, #si18n, #sinclude, #sinputtransferselect, #slabel, #soptgroup, #soptiontransferselect, #sparam, #spassword, #sproperty, #spush, #sradio, #sreset, #sselect, #sset, #ssubmit, #stextarea, #stext, #stextfield, #stoken, #surl and #supdownselect. There are no control-flow directives (iterator, if, else, generator, append, merge, sort, subset); Velocity’s #foreach and #if replace them.

Source: Apache Struts — Velocity Tags

A Velocity directive must say up front whether it is a block or an inline directive, so most tags have no #end and only #sform, #sa and #scomponent are blocks (the jar overrides getType for exactly those three). The #sa block printed its body before the <a> element in the test (Back<a href="..."></a>), so a link is safer written with #surl and plain HTML. The Struts tags print the same HTML as the FreeMarker macros, because the template engine that draws a UI tag is chosen by struts.ui.templateSuffix (ftl in default.properties): the tag templates are FreeMarker even in a Velocity page.

Source: Apache Struts — Velocity Tags, Block and Inline Tags

Velocity does not escape. Its engine ships an event handler that does, EscapeHtmlReference, and it is enabled in velocity.properties on the classpath; the match property is a regular expression that selects the references to escape, so a handler matching /.*/ escapes everything.

Source: Apache Velocity Engine 2.4 — EscapeHtmlReference

Source: Apache Velocity Engine 2.4 — Configuration, Event handlers

Use /.*/ unless a reference is known to hold safe markup; a Velocity template without a handler is the Velocity equivalent of <#noautoesc> everywhere.

If a velocity.properties is on the classpath it is loaded by Velocity; the default location is the constant struts.velocity.configfile. The Struts resource loaders (strutsfile for the web application, strutsclass for the classpath) are installed by default and the directives are registered for you. The file can add a macro library:

Source: Apache Struts — velocity.properties

(The title was escaped by the handler of the previous section.) #stext and $struts.getText(...) print the message as written when no parameter is given.

Two other constants extend the context. struts.velocity.contexts takes a comma-separated list of VelocityContext classes that are chained to the Struts context, so every template sees what they put:

Source: Apache Struts 7.4.0 — StrutsVelocityManager

The third constant, struts.velocity.toolboxlocation, names a Velocity Tools configuration file, and it is the one to avoid in 7.4.0.

Velocity Tools are the reusable helpers (EscapeTool, NumberTool, DateTool) that the earlier generation of Struts and Velocity integrations loaded in a toolbox. The plugin supports a toolbox through struts.velocity.toolboxlocation, with the optional jars struts2-velocity-tools-view-jakarta and velocity-tools-generic 3.1 on the classpath (neither is brought in by the plugin, since both are optional dependencies). The location is read from the classpath, and the configuration is validated: an application-scoped tool in a request toolbox is rejected.

The tool works, and the value stack is gone: $title and $stack are printed as written, and a Struts directive such as #stextfield fails with NullPointerException: Cannot invoke "org.apache.struts2.util.ValueStack.getContext()" because "stack" is null. The cause is in StrutsVelocityManager.createContext: when a toolbox is configured the context comes only from VelocityTools.createContext, a ToolContext with the default (request) toolbox, and the Struts context is never built. A toolbox therefore turns the integration into plain Velocity. Use struts.velocity.contexts (above) for helpers; put a Velocity Tools toolbox into a context class if a tool is needed. A /WEB-INF/tools.xml location gave Could not find any configuration at /WEB-INF/tools.xml because the file is read from the classpath.

Source: Apache Struts 7.4.0 — VelocityTools

Source: Apache Velocity Tools 3.1

The older way, the Velocity Tools VelocityViewServlet, still exists in the Struts fork jar (struts2-velocity-tools-view-jakarta) and renders templates outside Struts completely: mapped to *.vm in web.xml, it rendered a standalone.vm with #set($x = 40 + 2)$x and the request URI.

Source: Apache Velocity Tools 3.1 — Frameworks

That page has no action, value stack or Struts tags, so it is a plain Velocity template server, not a Struts view.