Tag Files & Layouts

A tag file is a source file with the extension .tag (JSP syntax) or .tagx (XML syntax) whose content is JSP: template text, EL, standard and custom actions, and, if you insist, scriptlets. It differs from a JSP page in four ways. It is called as a custom action, with attributes and an optional body. It has its own directives (tag, attribute, variable) instead of page. It has two actions a page does not (jsp:doBody and jsp:invoke). And it has its own page scope, so nothing leaks in or out unless the tag file declares it.

The specification leaves the implementation to the container: it may compile the file to a Java tag handler or interpret it, as long as the observable behaviour is the same. Jasper in Tomcat 11 compiles each tag file to a class that extends jakarta.servlet.jsp.tagext.SimpleTagSupport, which means a tag file is a simple tag handler whose doTag method contains the translated body of the file. The generated source of WEB-INF/tags/ui/button.tag below was found in the work directory as org/apache/jsp/tag/web/ui/button_tag.java (public final class button_tag extends SimpleTagSupport implements DynamicAttributes), which is where to look when a tag file misbehaves; the build and the generated sources are described in Compilation, Reloading and Where the Generated Code Is.

Source: Jakarta Pages 4.0 — Chapter 8 Tag Files

Source: Jakarta Pages 4.0 — 8.3 Semantics of Tag Files

Tag files are current and stable: they were added in JSP 2.0, gained deferred-expression attributes and implicit.tld in JSP 2.1, and the list of changes of the Pages 4.0 specification (Java 17 minimum) names nothing in their chapter. They are the right default for reusable markup in a JSP application. They are not a good place for business logic or data access, and the Bookshelf follows that rule: data comes from the servlet or a service, and a tag file only renders it.

The scratch application of this page is the Bookshelf of the getting started page with the three books loaded by a ServletContextListener into the application attribute books. A Book is a record, and EL 6 reads record components as properties (${book.title}).

Source: Jakarta Expression Language 6.0 — specification

The layout of the web application, with the tag files this page builds, is:

Source: Jakarta Pages 4.0 — 8.4.1 Location of Tag Files

The diagram shows the idea of the whole page: the catalogue page calls a layout tag file, which calls another, and each call is a new page scope.

The container recognises tag files in exactly two places: a directory tree under /WEB-INF/tags/ of the web application, or a tree under /META-INF/tags/ of a JAR in /WEB-INF/lib/. Only files with the extension .tag or .tagx count; the recommended extension for a segment included into a tag file is .tagf, the counterpart of .jspf. A tag file anywhere else is not a tag extension, and the container treats it as content to be served.

Source: Jakarta Pages 4.0 — 8.4.1 Location of Tag Files

Source: Jakarta Pages 4.0 — 8.4.3 Packaging Directly in a Web Application

The tagdir attribute of the taglib directive must start with /WEB-INF/tags. A directory elsewhere is rejected when the page is translated:

A directory that exists but holds no tag of the requested name gives the usual message of any library:

Source: Jakarta Pages 4.0 — 1.10.2 The taglib Directive

The smallest useful tag file in the Bookshelf prints a rating. It has no body, one required attribute and one line of markup.

Three things happened. The taglib directive with tagdir made every tag file of the directory available under the prefix ui. The attribute directive declared value, so the call is checked when the page is translated, not when it runs: a missing value or an unknown attribute stops the translation. And inside the tag file the attribute is a page-scoped variable named value, so ${value} finds it with the normal EL search.

Source: Jakarta Pages 4.0 — 8.2 Syntax of Tag Files

Source: Jakarta Pages 4.0 — 8.5.2 The attribute Directive

Table JSP.8-1 of the specification lists which directives a tag file may use: taglib and include behave as in a page, tag, attribute and variable exist only in tag files (using them in a JSP is a translation error), and page is not allowed in a tag file. The errors are:

Source: Jakarta Pages 4.0 — 8.5 Tag File Directives

The body-content of the tag directive says what the caller may put between the start and end tags.

Source: Jakarta Pages 4.0 — 8.5.1 The tag Directive

A fragment is a piece of JSP code, written by the caller, that the tag file can run zero or more times. The body of a tag is one; a tag can also receive named fragments through attributes declared with fragment="true". The caller writes a fragment attribute as a jsp:attribute child element, and when it does, the body has to be written inside jsp:body: the text between the tags may not contain anything else.

Source: Jakarta Pages 4.0 — 5.7 jsp:attribute

The mistake is to mix the two styles. With jsp:attribute present, text outside jsp:body is rejected:

Source: Jakarta Pages 4.0 — 5.8 jsp:body

A tag file exchanges values with its caller in two ways. IN parameters are attributes: a copy of the value is placed in the tag’s page scope and nothing is written back. OUT parameters are variables declared with the variable directive: a page-scoped variable of the tag file that the container copies to (or from) the calling page’s page scope at defined moments.

Source: Jakarta Pages 4.0 — 8.5.3 The variable Directive

The scope decides when the value crosses the boundary. In the table, "tag to page" means: if the variable exists in the tag file, create or update it in the caller; if it does not, remove it from the caller.

Source: Jakarta Pages 4.0 — 8.9.1 Synchronization Points

In practice: NESTED is a loop variable, visible only in the body and gone afterwards; AT_BEGIN is visible in the body and after the tag; AT_END is a result visible only after the tag. The three tag files below set x to 2, run the body, set x to 4, and each prints the value of x before and after the body. The page sets x to 1 and the body sets it to 3. The page and the output are the ones of the specification’s examples, run on Tomcat 11.0.26.

Source: Jakarta Pages 4.0 — 8.9.2.1 Example of AT_BEGIN

Source: Jakarta Pages 4.0 — 8.9.2.3 Example of NESTED

Source: Jakarta Pages 4.0 — 8.9.2.4 Example of AT_END

Source: Jakarta Pages 4.0 — 8.9.2 Synchronization Examples

Read the output once, slowly. In AT_BEGIN the body sees the tag’s x (2) because the value is copied before the body, and the page sees the tag’s final value (4) at the end. In NESTED the body sees 2 too, but after the tag the page’s own x (1) is back. In AT_END the body still sees the page’s x (1); only after the tag does the page see 4. The body’s own <c:set var="x" value="3"/> (the "3") is never copied back in any scope: the value flows from the tag file to the page, not the other way.

A fourth example from the specification shows that the synchronization can remove a variable: a NESTED variable that the tag file sets, calls the body, removes with c:remove, and calls the body again.

Called as <s:remove>'${x}'</s:remove> after x was set to 2, the output is 2, '1', '' and 2 again: the body saw 1, then nothing (the variable was removed from the caller), and the page’s own 2 returned at the end.

Source: Jakarta Pages 4.0 — 8.9.2.5 Example of Removing Parameters

Every call of a tag file gets a clean page scope: it holds the declared attributes and nothing else. The request, session and application scopes are the caller’s own, and a change to them is visible to the caller. A change to the page scope is not visible, except through a variable. The tag’s context object (the "JSP context wrapper") is what getJspContext() returns, and it is a PageContext when the caller’s context is one.

Source: Jakarta Pages 4.0 — 8.8 Implicit Objects

These are scripting variables, available in scriptlets and scripting expressions of the tag file. They are not EL identifiers: the EL implicit objects (pageContext, param, requestScope…​) are those of the implicit objects page. The tag file below prints values from both worlds.

The result confirms four things. The tag file does not see the caller’s page-scoped variable; it sees the request-scoped one. ${jspContext...} and ${request.method} are empty, because they are scripting variables and not EL names (a missing EL variable is not an error unless errorOnELNotFound is on). ${pageContext.request.contextPath} works: EL’s pageContext is available in a tag file. And what the tag stores in its own page scope (leak) is gone once the tag ends.

Source: Jakarta Pages 4.0 — 8.3 Semantics of Tag Files

A tag file can contain scriptlets, even though its callers' bodies cannot (body-content="scriptless" governs the caller’s body). A <% out.print("scriptlet"); %> in bad/scriptlet.tag printed scriptlet. Property groups, including scripting-invalid, never apply to tag files (see the configuration page), so a project that bans scriptlets should also search WEB-INF/tags for <% in code review.

The dynamic-attributes attribute of the tag directive turns on the acceptance of attributes the tag did not declare. It names a page-scoped variable that receives a Map of names to values; the generated handler implements jakarta.servlet.jsp.tagext.DynamicAttributes, and the container must not reject any name. Only attributes without a namespace URI are in the map.

The map is a hash map, so the order of data-id and class is not the order written. The values are escaped with c:out: a dynamic attribute is request data the moment it comes from an expression.

Source: Jakarta Pages 4.0 — Dynamic attributes

Source: Jakarta Pages 4.0 API — DynamicAttributes.setDynamicAttribute

A tag that does not declare dynamic-attributes is strict: <ui:rating value="1" extra="no"/> stops the translation with Attribute [extra] invalid for tag [rating] according to TLD.

A tag file whose extension is .tagx is in XML syntax, like a JSP document: it must be well formed, the jsp:root element may be present (in a .tag it may not), directives become jsp:directive.tag, jsp:directive.attribute and jsp:directive.variable, and the default is not to generate an XML declaration. A pageEncoding attribute in the tag directive of a .tagx is an error: the encoding follows the XML rules. If jsp:root carries a version, it must match the tag file’s JSP version. The JSP documents page covers the XML syntax in general.

It is called like any other tag; the call <ui:note level="warn">Beta & <b>bold</b></ui:note> gives <div class="note warn">Beta & <b>bold</b></div>. The XML view of a tag file, the form passed to tag library validators, is built the same way as for a page.

Source: Jakarta Pages 4.0 — 8.6 Tag Files in XML Syntax

Source: Jakarta Pages 4.0 — 8.7 XML View of a Tag File

To reuse tag files across applications, put them in a JAR under /META-INF/tags/ and describe them in a tag library descriptor in the same JAR. A tag file in a JAR that no descriptor lists is ignored. The descriptor’s tag-file element has a name and a path, which must start with /META-INF/tags; other elements of the element override the defaults of the file’s tag directive. A library can mix tag (Java) and tag-file elements, and both share one namespace of names, so a duplicate name makes the library invalid. The JSP version of a tag file in a JAR is the version of the descriptor.

Jasper compiled the tag into org/apache/jsp/tag/meta/... of the work directory, a separate tree from the tag/web/... of tag files in the web application. Tomcat finds the descriptor by scanning the JARs of WEB-INF/lib for TLD files, as the Tomcat JAR scanner page describes.

Source: Jakarta Pages 4.0 — 8.4.2 Packaging in a JAR

Source: Apache Tomcat 11 — The Jar Scanner Component

A third form, tag files compiled into Java classes and distributed as a binary tag library, is allowed but needs a tool that produces portable code; containers are not required to supply one. Precompiling with JspC at build time is a matter for the Jasper Configuration & Precompilation.

Source: Jakarta Pages 4.0 — 8.4.4 Packaging as Precompiled Tag Handlers

Every page of the Bookshelf has the same skeleton: a head, a navigation bar, a main area, an optional second column and a footer. In JSP the clean way to write that skeleton once is a tag file whose body is the page content and whose optional fragments fill the other slots. This is the pattern called Composite View, which the JSP world also implemented with Tiles and SiteMesh, and which Thymeleaf calls a layout.

Source: Jakarta Pages 4.0 — 5.9 jsp:invoke

Source: Jakarta Pages 4.0 — 5.10 jsp:doBody

The design decisions are all visible in that file. The page-specific content comes in through jsp:doBody. The optional slots are fragment attributes invoked with jsp:invoke, which does nothing for a slot the page did not fill. Everything the layout reads from the model comes from a scope (here books from application scope); a layout that needs a variable the page sets should ask for it as an attribute instead, since the caller’s page scope is not visible. The title is escaped with c:out because it is data. The navigation uses a component tag file (ui:navLink), a tag file calling a tag file from another directory through its own taglib directive.

A page uses the layout by wrapping its content:

Source: Jakarta Pages 4.0 — 5.7 jsp:attribute

The <head> fragment is optional: the about.jsp page of the application passes none and its response simply has an empty aside and no extra head markup.

A component tag file renders one concept of the application: a book card, a rating, a navigation link, a form field. The same rules produce good ones.

The Bookshelf’s ui directory shows the range: rating (no body, one attribute), navLink (no body, a boolean), bookCard (typed attribute, boolean, body), each (collection, two named variables), summary (an AT_END result), button (dynamic attributes), shout and raw (body transformation) and note (XML syntax).

Source: Jakarta Pages 4.0 — Chapter 8 Tag Files

The pieces assembled: the servlet or listener puts the books in a scope, the page calls the layout, the layout renders the skeleton, and component tags render the cards. The call chain for one request of index.jsp is: Jasper translates and compiles index.jsp, then each tag file it uses (layout/page.tag, ui/each.tag, ui/bookCard.tag, ui/rating.tag, ui/button.tag, ui/summary.tag, ui/navLink.tag) the first time it is reached. At run time layout:page receives three things from the page: the attributes title and active, the two fragments head and sidebar, and the body. It writes the head, calls navLink twice, runs the body (which calls each, which for every book runs its own body, which calls bookCard, whose body is the button), and finally the aside and the footer. summary sets total once, at the end of its call, and the paragraph that follows prints it.

The three matches are the three ratings of the three cards. A change to the layout file (<footer> to <footer data-v="2">) showed in index.jsp and in about.jsp six seconds later, so a tag file edit reaches every page that uses it.

Source: Apache Tomcat 11 — Jasper 2 JSP Engine How To, Configuration

Jasper translates a tag file to Java the first time a page that uses it is translated, compiles it, and keeps the class in the web application’s work directory: org/apache/jsp/tag/web/<directory>/<name>_tag.java and .class for a file in WEB-INF/tags, and org/apache/jsp/tag/meta/<uri>/... for a file in a JAR. The generated class extends SimpleTagSupport; its setJspContext creates the JspContextWrapper that holds the clean page scope and the variable synchronization state, and doTag calls syncBeforeInvoke before it invokes the body.

In development mode (the default, development is true) Jasper checks a page and its dependent files for modification at most once per modificationTestInterval (4 seconds by default), and the tag files a page uses are among its dependents, as the reload test above showed. In production mode (development false) the pages and tag files are checked at the checkInterval or never, and precompiling with JspC removes the first-request cost. Compile errors name the tag file and line, as in the messages of this page, and runtime errors from EL name the tag file too:

Source: Apache Tomcat 11 — Jasper 2 JSP Engine How To, Configuration

Source: Apache Tomcat 11 — Jasper 2 JSP Engine How To, Production Configuration

Source: Jakarta Pages 4.0 — 8.4.1 Location of Tag Files

Source: Jakarta Pages 4.0 — Chapter 8 Tag Files

Source: Jakarta Pages 4.0 — Appendix C Changes

The Pages and JSTL books of the bibliography are from the JSP 1.2 era, which predates tag files. The JSP 1.2 book builds custom tags only as classic Tag and BodyTag handlers in Java with a JSP 1.2 TLD DTD, and has nothing like jsp:doBody or a page scope for a tag; the JSTL book evaluates EL in custom tag attributes by hand with an ExpressionEvaluatorManager, and builds its portal layout with c:import. Everything the books do with those tools is today either an EL expression, a tag file or a simple tag handler. The Struts books use Tiles for layouts, with tiles:insert and definition inheritance; a layout tag file expresses the same composition with jsp:attribute and nested layouts, and Tiles itself has been retired. Where the books use a custom tag to reach a database or a feed, the modern answer is to load data before the view.

Source: Jakarta Pages 4.0 — Chapter 8 Tag Files