Themes & Templates

The Tag Developer Guide defines three words, and the rest of the page depends on them:

Source: Tag Developer Guide — Themes and Templates, Definitions

The path of one tag from the page to the browser has five steps, shown in the figure below. The tag is a UIBean; it evaluates its attributes against the value stack, decides which theme applies, maps its own name to a template name (s:textfield to text, s:select to select, s:submit to submit), asks the template engine for /template/<theme>/<name>.ftl, and runs the template with all attributes available as the FreeMarker hash attributes. The Core Developer Guide’s statement that FreeMarker is the default engine regardless of the page format is the reason the same templates serve JSP, FreeMarker and Velocity pages: the JSP, FTL and Velocity tags are all rendered with FreeMarker internally.

Source: Tag Developer Guide — Template Loading, Template and Themes

Two consequences follow from the figure and are worth stating early. First, the theme decides what surrounds a control: the same s:textfield writes a table row in xhtml, a group of div elements in css_xhtml and a bare input in simple and html5. Second, because the markup lives in templates and not in Java, changing it never needs a recompilation: a template can be overridden by dropping a file into the web application, which is the subject of a later section.

All examples are classes, mappings and templates of one WAR, g10themes.war, deployed under the context path /g10themes on Tomcat 11.0.26 (a Maven project that imports the struts2-bom 7.4.0, with jakarta.servlet-api 6.1.0 and jakarta.servlet.jsp-api 4.0.0 as provided dependencies; the page Struts Getting Started explains the project layout and web.xml). One action class, ThemesAction, holds the form state; the JSPs take the theme from the request, so one action can show every theme:

Source: Struts Javadoc — SessionAware

Two details of 7.x show in the class. SessionAware lives in org.apache.struts2.action and its method is withSession, and every setter that request parameters may reach carries @StrutsParameter. The mapping sends form and save to one JSP, and the wildcard action *Page sends <name>Page to /WEB-INF/views/<name>.jsp, so every experiment below is one small JSP:

Source: Getting Started — Themes, Introduction

The form that is rendered in every theme is the same four controls, with the theme supplied as an OGNL expression so the request can choose it:

Source: Tag Developer Guide — Selecting Themes

Struts 7.4.0 ships four theme directories under template/ in struts2-core, and their relations are declared in a one-line theme.properties file in each directory. Listing the jar (unzip -l struts2-core-7.4.0.jar) gives the real sizes:

Source: Tag Developer Guide — Themes and Templates, More About Themes

Only four directories exist. The Tag Developer Guide and the Getting Started tutorial still mention an ajax theme; there is none in 7.4.0 (see "Where the Books Are Outdated" and "Inconsistencies in the Official Documentation").

A theme need not provide every template. css_xhtml has no text.ftl, select.ftl or form.ftl of its own: they are found by following parent = xhtml, and the xhtml ones in turn include the simple templates for the bare control. The same form, requested as form?themeName=<theme>, shows the difference. In the xhtml theme (the default), every control becomes a table row, the label is generated from the label attribute, and the checkbox gets its own cell layout:

Source: Tag Developer Guide — xhtml Theme, Wrapping the Simple Theme

The css_xhtml theme writes the same information with div elements that carry wwgrp, wwlbl and wwctrl classes and ids derived from the control id, so the layout is entirely a matter of CSS:

Source: Tag Developer Guide — css_xhtml Theme, CSS XHTML theme header

The simple theme produces only the controls. Notice what is missing: the label attribute of the tags produced no label at all, and the form has no table or division:

Source: Tag Developer Guide — simple Theme

The html5 theme extends simple and was observed to behave like it, with compact HTML5 output (no label, and a submit written as <input type="submit" ...> without the trailing slash):

Source: Tag Developer Guide — html5 Theme, Theme Configuration

Two points of the four outputs deserve a sentence each. The simple and html5 themes do not render the label attribute nor field errors; in those themes the labels and the messages are the page’s job (s:label, plain label elements, s:fielderror). And in all four outputs the required="true" of the first control appears as an HTML attribute on the input, not as the star next to the label: required is not a Struts attribute, it is passed through as a dynamic attribute (see the section on common attributes).

Struts picks the theme for a tag with the first of seven rules that matches:

Source: Tag Developer Guide — Selecting Themes

The order was verified with a JSP that sets scope attributes from request parameters and renders one s:textfield inside an s:form:

Source: Getting Started — Themes, Specifying The Theme Struts Should Use

An empty theme expression falls through to the next rule, which is why the form and tag levels can be driven from the query string here. The results, identified by the markup that came back (table, wwgrp division, or a bare input), were:

The table also exposes the trap of the last two levels. An attribute stored in application scope stays there until the application stops: after the experiment that set application to css_xhtml, a request with no parameters at all rendered css_xhtml too, and only a redeploy restored the default. A session attribute lasts as long as the session.

The session level is the standard way to give each user a theme of their own. The Bookshelf’s setTheme action stores the name in the session map and redirects; the next request of the same session rendered css_xhtml while a request without that session cookie still rendered xhtml:

Source: Tag Developer Guide — Selecting Themes, Tips

The scriptlet above is only the shortest way to set the scope attributes. Remember that every theme value is a string expression: write theme="css_xhtml" for a literal and theme="%{themeName}" for a property, and a name that matches no directory fails (see the pitfalls).

The behaviour above is configured by constants that belong in struts.xml (or struts.properties), documented in default.properties of the jar:

Source: Struts 7.4.0 source — default.properties

Source: Core Developer Guide — Performance Tuning, Enable FreeMarker template caching

Three of the constants were exercised in one deployment. A Bookshelf struts.xml with the following constants made the page without any theme attribute render the custom shelf theme (built below), moved the stylesheet link of s:head, and changed the token that the loader prints in its error messages:

Source: Tag Developer Guide — simple Theme, Head Tag

The s:head of a page with the xhtml theme then wrote <link rel="stylesheet" type="text/css" href="/g10themes/assets/xhtml/styles.css"/> and <script src="/g10themes/assets/utils.js">, and a theme with no parent failed with the path /template/@@@orphan/css.ftl. The struts.ui.templateDir constant was exercised with a copy of the simple and xhtml trees under a tpl2 directory of the web application: a label template with a marker in tpl2/xhtml/label.ftl took effect, while a request for css_xhtml failed because that theme had not been copied (Template not found for name "/tpl2/css_xhtml/head.ftl"). Changing the directory therefore moves every theme, the built-in ones included.

Source: Tag Developer Guide — Selecting Template Directory, Tips

Themes bring CSS and JavaScript with them, and s:head is the tag that emits the links. In the xhtml theme head.ftl writes a stylesheet link and then includes the simple head template, which loads utils.js; the css_xhtml theme does the same with its own stylesheet; the html5 theme loads only utils.js. With the Bookshelf’s form.jsp above the head of the page for each theme was:

The css_xhtml head replaces xhtml with css_xhtml in the stylesheet path, and the simple and html5 heads contain only the script line. The files are served by the framework from the jar (/static/xhtml/styles.css answered HTTP 200), so there is nothing to copy to the web application unless the stylesheet is to be customised. The s:head tag resolves its theme exactly like any other tag, which gives one more trap: a page with <s:head/> and a form that sets theme="css_xhtml" only on the form still linked /static/xhtml/styles.css, because the form attribute is not visible to a tag outside the form. Put the theme where both tags see it (a scope attribute, the constant), or give s:head the same theme attribute, as the Bookshelf’s form.jsp does.

The Getting Started tutorial shows the default styles that the xhtml theme defines and how a page overrides them by repeating the selectors in its own style element:

Source: Getting Started — Themes, Specifying The CSS Used By The Struts Tag

Source: Tag Developer Guide — simple Theme, Head Tag

The templates read the attributes of the tag through the hash attributes, so the attributes that a tag accepts are the ones the templates look at. The ones that matter for appearance are the same on every UI tag (the full list per tag is in the tag reference of the section on UI and form tags):

Source: Tag Developer Guide — Extending Themes, Special attributes

The attributes were exercised with a page of two forms. In the first, labelPosition="top" on the form moves the first label to its own row, requiredLabel="true" writes the star and labelPosition="left" on the second control overrides the form. Written with the camelCase names the result was:

Source: Tag Developer Guide — form Tag, Attributes

Spelling matters. The same attributes written in lowercase (labelposition, requiredposition), as many older pages and books write them, are not errors: they are unknown to the tag and are copied to the element as dynamic attributes, so the output contained <form id="save" ... labelposition="top"> and <input ... labelposition="left"/> and the layout did not change. For the same reason required="true" produced required="true" on the input and no star; the attribute that draws the star is requiredLabel.

The dynamic attributes are what lets the html5 theme use modern HTML without template changes. In a form with the html5 theme, type="email", placeholder, aria-label, data-role and a cssClass all reached the input, and the error class was merged in when the field had an error:

Source: Tag Developer Guide — html5 Theme, Using the html5 Theme

The same blank title in the xhtml theme produced the error row above the control (the default errorPosition) and a changed label class; with errorPosition="bottom" the row came after the control:

Source: Tag Developer Guide — xhtml Theme, XHTML Theme Header

The template for a tag is looked up in the application first and in the classpath second, in both cases at /<templateDir>/<theme>/<name>.ftl. The Tag Developer Guide gives the xhtml example: for the xhtml theme the two locations searched in order are /template/xhtml/<name>.ftl in the web application and the same path on the classpath (which is where struts2-core puts its own). The theme name is not the whole story, because of theme.properties.

The mechanism is FreemarkerThemeTemplateLoader, a FreeMarker template loader that wraps the real ones. When it sees the theme expansion token in a template name, it takes the theme after the token, searches the possible templates of that theme (web application, then classpath) and, if there is none, reads the parent entry of the theme’s theme.properties and repeats the search in the parent. When there is no parent entry, it gives up and the template is not found. The templates that came with Struts use this mechanism for every include. The xhtml text.ftl, shown here as it appears in the 7.4.0 jar, wraps the bare control with a header and a footer:

Source: Struts 7.4.0 source — xhtml/text.ftl

Source: Struts 7.4.0 source — FreemarkerThemeTemplateLoader

The first and third lines go through attributes.expandTheme, which is the current theme prefixed with the expansion token (~~~css_xhtml, ~~~xhtml and so on): the loader looks for controlheader.ftl in the current theme and then in its ancestors, so a child theme’s header and footer win. The second line names simple literally, so the wrapped control always comes from the simple theme (unless the application overrides simple/text.ftl). That is why a css_xhtml form, which inherits xhtml/text.ftl, still has div elements: the header and footer included by the inherited file are the css_xhtml ones.

The Tag Developer Guide lists the attributes that UIBean provides to templates for exactly this purpose:

Source: Tag Developer Guide — Extending Themes, Special attributes

The same page notes that since Struts 7 the objects handed to templates are named attributes, where older versions used parameters: a template written for Struts 2.x as ${parameters.name} becomes ${attributes.name}.

The most common customisation is the smallest one: one control that renders differently. The Tag Developer Guide’s recipe is to extract the template from the struts2-core jar, edit it and save it at /template/<theme>/<name>.ftl in the application, so that it is found before the one in the jar. Extracting is one command, and the file layout is the same inside the jar and in the web application:

Source: Tag Developer Guide — Template Loading, Overriding Templates

The Bookshelf overrides the xhtml template of s:label to wrap the value in a span with its own class. The file src/main/webapp/template/xhtml/label.ftl keeps the wrapping header and footer, and replaces the control:

Source: Tag Developer Guide — Template Loading, Overriding Templates

The override applies to every s:label that resolves to the xhtml theme, anywhere in the application, and to nothing else. Three behaviours of the loader were observed with this file:

Source: Core Developer Guide — Performance Tuning, freemarker.properties

Source: Core Developer Guide — Performance Tuning, Copy all necessary templates to the theme directory

The Tag Developer Guide also names an escape hatch, extending FreemarkerManager to load templates from the file system or a URL, which can be useful for results as well as for tags. It is an advanced option, and the guide recommends copying and modifying a FreeMarker template first.

Source: Tag Developer Guide — Template Loading, Altering Template Loading Behaviour

The Tag Developer Guide lists three ways to create a theme: from scratch (and says it is hard and rarely a good idea), by wrapping an existing theme, and by extending one with parent. In practice a custom theme is one of the last two, and the Bookshelf has one of each.

A tag can be told to use a template that is not its default, without writing a theme. The template attribute names the file (without its extension for a tag that has a default, and with it in the component examples), searched in the theme directory the tag resolved. In the shelf theme, a textfield-compact.ftl that includes only the simple template gave a text field without the wrapper:

Source: Tag Developer Guide — component Tag, templateDir and theme attribute

The s:component tag renders a custom UI widget with a template of your own, and passes objects to it with s:param. The final path is <templateDir>/<theme>/<template>, which is why the tag needs its three attributes when the template lives outside the standard tree. The Bookshelf’s badge component sits at components/x/badge.ftl:

The parameters reach the template as attributes.kind and attributes.text (parameters.kind before 7.0). The value of an s:param is an OGNL expression, so a string literal needs the single quotes; without them, the value stack is searched for a property called Dune.

Source: Tag Developer Guide — component Tag, Description

The engine is chosen by the file extension of the template, so a component can be a JSP as well. A components/x/note.jsp that prints <s:property value="%{attributes.text}"/> inside an em element was rendered by the same tag, with the page-scope attribute templateDir set to components instead of the tag attribute (the selection rules of the template directory are the same as for themes without the form level: tag, page, request, session, application and then the constant struts.ui.templateDir). The component page adds that a JSP template must be inside the web application, because, unlike FreeMarker and Velocity, it cannot be loaded from the classpath.

Source: Tag Developer Guide — Selecting Template Directory

FreeMarker is the default and, in practice, the only template language of the shipped themes. The constant struts.ui.templateSuffix selects the engine: ftl (the default), vm (Velocity) or jsp. The only set of templates shipped in the distribution is for FreeMarker; to use another engine you provide your own templates and themes. The guide’s advice for anyone tempted to switch is to copy and modify a FreeMarker template first, because most changes are obvious.

Source: Tag Developer Guide — Template Loading, Alternative Template Engines

For applications that use the simple theme without overriding templates, the Performance Tuning page suggests the javatemplates plugin, which renders the simple theme from Java code instead of FreeMarker. It is one of the plugins bundled with Struts 7.4.0, and is covered with the other plugins of this section.

The templates of the 7.4.0 jar are FreeMarker templates whose ${...} interpolations are escaped for HTML. Two requests showed what a Bookshelf page can rely on. A label of A <i>& B</i> and a value of <b>x</b> in the shelf theme, whose controlheader.ftl prints ${attributes.label}, came out as text:

In the xhtml theme, a label of <b>Raw</b> written in a JSP attribute came out as <b>Raw</b>: a JSP attribute is not HTML-decoded, so the ampersand is escaped once more. The practical rules are to write the plain text, to put markup in a page and not in a label, and, in a custom template, to keep the interpolation ${attributes.label} (which is escaped) instead of switching escaping off with noautoesc. A template is code that runs for every request of a page, so a careless one is a cross-site scripting hole that tests of the rest of the page will not find.

Source: Tag Developer Guide — Extending Themes, Wrapping a control

The pieces above combine into the form every web application ends up with: the same JSP, a default theme for the whole application, and a theme a signed-in user can change. The constant gives the default, the session attribute the choice, and s:head the matching stylesheet:

No tag carries a theme attribute. The page renders in css_xhtml for a user who has not chosen anything: the head links /g10themes/static/css_xhtml/styles.css and the title label carries the required star. After the setTheme action has stored shelf in the session, the same JSP wrote a head with only the utils.js script (the shelf theme inherits the simple head template, which has no stylesheet), the div layout of the theme above for the text field and the select, and the class wide on the input, for that user only. The theme draws no star, because its header does not print requiredLabel, and it leaves the checkbox and the button bare, because it has no templates for them: a custom theme takes over exactly the behaviour its templates write. A site that wants the user’s choice to be a trusted list, and not an arbitrary string, validates the value in the action before putting it in the session: the theme name becomes a path of a template, and the framework’s behaviour for a name that is not a directory is an error page (see "Names That Do Not Exist").

Source: Tag Developer Guide — Selecting Themes, Tips

Source: Tag Developer Guide — html5 Theme, Since

Source: Tag Developer Guide — xhtml Theme

The Struts 2 book of the section teaches themes in the Struts 2.0 style: tags produce FreeMarker templates, the themes simple, xhtml, css_xhtml and ajax, and custom templates and themes as a practice of the best-practices chapter. The idea is current; these details are not:

Collected while verifying this page; none changes behaviour, but each can mislead:

A Struts UI tag is a thin front for a FreeMarker template. The theme chosen by seven ordered rules (tag, form, page, request, session, application, constant) names a directory under template/; theme.properties links it to a parent; the loader finds each template in the web application before the classpath and in the theme before its parents; and the xhtml templates wrap a bare simple control with a header and a footer that a child theme can replace. Use xhtml for quick forms, css_xhtml when CSS carries the layout, simple or html5 when the page designs its own markup (and remember that they draw no label and no error). Override one template when one control must change, build a theme with parent when several must, keep the interpolations escaped, and give s:head the same theme as the forms.