Tiles & Page Layouts

Tiles is a composite-view framework. A page is not written once as a whole but assembled: a definition in an XML file names a layout template and gives values for its slots, and an action result renders that definition. The values can be paths of JSP fragments, plain strings, lists or other definitions. The same idea is called a layout or a template in other frameworks, and the tag-file page already has a comparison table of the ways to build a skeleton in JSP; this table is its Struts counterpart.

For a new application on JSP the plain answer is the tag-file layout: one file, no framework, and the Jakarta Pages specification defines it. For an application that already has tiles.xml files and a tiles result, nothing forces a migration. Struts 7.4.0 ships the plugin and keeps fixing it, as the next sections show, but the project’s own documentation of the 2.5 line says the older plugin generation was dropped, and the plugin’s dependencies (the Tiles code is bundled) will not receive upstream fixes.

Source: Apache Attic — Apache Tiles

Source: Apache Struts — Tiles Plugin

The plugin has four moving parts. A servlet context listener, org.apache.struts2.tiles.StrutsTilesListener, builds a Tiles container when the web application starts and reads every tiles*.xml file it finds. The package tiles-default, which extends struts-default, registers the result type tiles (org.apache.struts2.views.tiles.TilesResult). An action result of that type names a definition. And the JSP that the definition names as its template uses the Tiles tags to insert the attributes of the definition into its slots.

The diagram shows the two facts that matter in practice. The container is application-wide and built once, so a definition is shared by every request. But the template JSP runs inside the normal request, so the Struts tags work in it, and the S2: evaluator reads the value stack of that request.

Source: Apache Struts — Tiles Plugin, Usage

All examples below are one WAR, g10tiles.war, deployed under the context /g10tiles on Tomcat 11.0.26. It is the Struts Bookshelf of the page Struts Getting Started with these changes: two dependencies were added, the plugin struts2-tiles-plugin (version managed by the Struts BOM) and commons-beanutils 1.11.0, the web descriptor declares the listener, the actions live in a package that extends tiles-default, and the views are Tiles templates under WEB-INF/tiles. The page BookAction offers a list of titles and a page title:

Source: Apache Struts — Tiles Plugin, Example

Three things are needed, and the plugin documentation lists them in this order: the dependency, the listener and the result type.

A definition has a name, usually a template, and a list of attributes. The plugin loads every file matching tiles*.xml from the classpath or from WEB-INF since Struts 2.3.28, so no DEFINITIONS_CONFIG parameter is needed; that parameter is still the way to name the files explicitly in a restricted environment, and a WAR that uses Tomcat’s ## version mechanism must list its definition files explicitly, because of a limitation of the URL class.

Source: Apache Struts — Tiles Plugin, Usage

The vocabulary, in the order the file uses it:

The type attribute was exercised in the Bookshelf by a definition that sets the header to a plain string, the footer to another definition and the body to a template; the page rendered Plain text header as bare text, the footer definition as its JSP and the body as the usual list:

Source: Apache Tiles — Nesting and Extending Definitions

The template named by baseLayout is an ordinary JSP that uses the Tiles tag library and, where it is useful, the Struts tags. tiles:insertAttribute writes the value of a named attribute, rendering it according to its type; tiles:getAsString writes it as text; tiles:importAttribute copies one or all of the attributes into a scope so that other tags and EL can read them (a list attribute imported this way is a list the Struts iterator can walk).

Source: Apache Struts — Tiles Plugin, Example

Requesting /g10tiles/books produced the assembled page (blank lines trimmed):

The title came from the action (S2:pageTitle), the header and footer from baseLayout, the body from the child definition and the menu from the list attribute. The s:url output carries a ;jsessionid only on the first request of a session, as always with URL rewriting.

The Tiles tag library has eleven tags, listed here from the plugin’s TLD; the tutorial pages of Tiles document each of them.

Source: Apache Tiles — insertAttribute tag

Source: Apache Tiles — importAttribute tag

The tiles result is optional. Any JSP, whether it was reached by a dispatcher result or by a forward, can insert a definition, and can override attributes while doing so. This is the way to use Tiles components in an application that renders its pages some other way:

The first call rendered the full Bookshelf page with the title Overridden in the JSP and a menu that had lost its about entry (the override replaced the inherited list, it did not add to it); the second rendered the layout with the title Ad hoc and a body that is not part of any definition. Both ran inside the action’s request, so the Struts tags in the layout saw the action as before.

Source: Apache Tiles — insertDefinition tag

Source: Apache Tiles — insertTemplate tag

A definition name can contain wildcards, so one definition serves many result names. In the plugin the name must carry the prefix WILDCARD:; the Tiles tutorial says the prefix is not needed when wildcards are the only pattern syntax in use, and that is not what the Struts container did. The container the plugin builds registers two pattern syntaxes, WILDCARD and REGEXP, and a name with no prefix is treated as a literal (verified: a definition named page-* was never matched). The matched parts are available as {1}, {2} in the attribute values:

With this definition the result <result type="tiles">bookshelf.about</result> rendered Bookshelf - about and the body /WEB-INF/tiles/about-body.jsp, with no bookshelf.about entry anywhere. The explicit definitions still win: a name that exists literally (bookshelf.books) is found first, and the wildcard is the fallback for the rest. A wildcard that is too greedy hides mistakes; the result bookshelf.nope did not report a missing definition, it matched and failed later with a Jasper error about the missing /WEB-INF/tiles/nope-body.jsp at line 14 of layout.jsp.

Source: Apache Tiles — Wildcard support

An attribute can take its value from an expression instead of a literal. The prefix of the expression selects the evaluator. The plugin registers four of them.

Source: Apache Struts — Tiles Plugin, Accessing Struts attributes

The plugin ships annotations that keep a one-off definition next to the action that uses it, instead of in tiles.xml. The annotation @TilesDefinition has the members name, extend, template, templateExpression, templateType, preparer, role, putAttributes and putListAttributes; the nested annotations are @TilesPutAttribute, @TilesPutListAttribute, @TilesAddAttribute, @TilesAddListAttribute and @TilesDefinitions for more than one. The action’s result is a tiles result with no body: the plugin builds a definition from the annotation and registers it for the action.

The request answered the layout with the title Annotated and the list Hyperion. The definition baseLayout it extends still lives in tiles.xml: the annotation only describes the part that differs. The plugin documentation shows the same construction with a @Result(name = "success", type = "tiles") of the Convention plugin.

Source: Apache Struts — Tiles Plugin, Usage

Source: Struts Javadoc — TilesDefinition

The same Bookshelf frame without Tiles needs two files and no configuration. The layout is a tag file whose slots are attributes and fragments, and the page that uses it wraps its content in the tag. The tag-file mechanics (the tag and attribute directives, jsp:invoke, jsp:doBody) are on the Tag Files & Layouts page; the point here is that the Struts tags and the value stack work inside it.

The action’s result is the plain dispatcher result for /WEB-INF/views/tagfile.jsp. The response was the framed page with the title Bookshelf - Bookshelf - catalogue; the doubled prefix is a slip of the example (the page adds one and the action’s pageTitle already has it), but it proves the interesting fact: the EL expression ${pageTitle} inside the page read the action’s property, because Struts wraps the request so that EL attribute lookups fall back to the value stack.

The costs of the tag-file route are small: pages repeat the one-line wrapper, and the layout lives in the page rather than in a central registry. Its gains are that nothing is retired, the page is checked at translation time and a missing slot is a compile error instead of a blank place. SiteMesh 3, used directly as a servlet filter, is the other alternative when the layout must be applied to finished pages of any origin; the plugin for it is not published for 7.4.0, so the filter is a dependency of the application, not of Struts.

Source: Jakarta Pages 4.0 — Chapter 8 Tag Files

Apache Tiles retired in December 2018, and the Attic move was completed in November 2019. The plugin documentation of the Tiles 3 generation still exists on the Struts site, with the notice that the plugin was dropped in 2.5 and the Tiles plugin should be used instead, and the portlet Tiles plugin has the notice that it is deprecated since 2.6.

Source: Apache Struts — Tiles Plugin

Source: Apache Struts — Tiles 3 Plugin (dropped)

Source: Apache Struts — Portlet Tiles Plugin (deprecated)

The two Struts books of the section’s bibliography teach Tiles in the form of their day, and the vocabulary is the best map for a reader who inherits such an application.