Facelets Templating

The Facelets templating tag library has eleven tags. The last column was measured: a page that used every tag was built on both implementations and the component tree of the view was printed. A tag that is only a tag handler runs while the view is built and leaves nothing in the tree except the text it produced; a tag that is a component stays in the tree and is evaluated again on every request.

The measured tree of a page that used ui:include, ui:decorate, ui:define, ui:component, ui:fragment, ui:remove, ui:repeat and ui:debug in a template client contained, below the body, only UIInstructions for the text produced by the includes, defines and decorations, two components of the implementation’s ComponentRef class (one for the ui:component and one for the ui:fragment), a UIRepeat and a UIDebug; the h:outputText inside ui:remove was not there. ComponentRef is an implementation class, so a page should only rely on the tag, never on the class.

Source: Jakarta Faces 4.1 VDL documentation: the ui tag library and Jakarta Faces 4.1 specification, 10.4.3 Facelet Templating Tag Library

A template is an ordinary XHTML Facelets file that contains one or more <ui:insert name="..."> elements. Each is an insertion point (a slot) with a name. A template client is a view whose root is a <ui:composition> with a template attribute holding the template’s path. Inside the composition, one <ui:define name="..."> per slot supplies the content for that slot. When the view is built, Facelets loads the template, and each ui:insert is replaced by the ui:define of the same name, or keeps its own body when the client defines nothing for it.

The Bookshelf keeps its template under /WEB-INF/templates/layout.xhtml. Files under WEB-INF can never be requested directly by a browser, so a template can only be reached through the views that use it, which is the point:

The template declares four slots. title, nav and footer have default content between their tags; content has none. A page that uses it:

Requesting that view returned the composed page, with the client’s title and content and the template’s defaults for nav and footer:

Three behaviours are worth remembering:

MyFaces 4.1.4 produced the same markup. In the Development project stage it also appends an empty div with the id jakarta_faces_developmentstage_messages before </body>, a container for development-time messages that Mojarra writes only when it has a message to show.

The template named by template is itself resolved when the view is built. If the path does not exist, the request fails with an error page instead of rendering without the layout: Mojarra reported Invalid path : /WEB-INF/templates/missing.xhtml with the file and column of the ui:composition, and MyFaces reported /WEB-INF/templates/missing.xhtml Not Found in ExternalContext as a Resource. The same holds for a ui:include whose src does not exist.

Source: Jakarta EE Tutorial: Using Facelets Templates and Jakarta Faces 4.1 specification, 10.4 Standard Facelet Tag Libraries

The name attribute of ui:insert is optional. According to the VDL, when no name is given the whole template client is inserted. That makes a template that wraps whatever the client puts inside its ui:composition, with no ui:define at all:

Both implementations answered with <div class="wrap">[, a line break and the client’s paragraph, then ]</div>. Use it for small wrappers (a boxed region, a card) where one slot is enough; as soon as a layout needs two regions, named slots are clearer.

Source: Jakarta Faces 4.1 VDL: ui:insert

The body of a ui:insert is its default. It is used exactly when the client has no ui:define of that name. This lets a template evolve without breaking its clients: add a new slot with a sensible default and every existing page keeps working; a page opts in by defining it.

A slot can hold any Facelets content, including components and further ui:insert tags, and defaults are not limited to text. The nav slot above defaults to a link. The same page defined that way rendered Home unchanged until a client defined its own nav.

Two limits to keep in mind. A slot is filled by name only: a template with two inserts of the same name, [<ui:insert name="x">d1</ui:insert>][<ui:insert name="x">d2</ui:insert>], rendered [DEF][DEF] for a client with one <ui:define name="x">DEF</ui:define>, on both implementations, so the definition is copied into every insert of that name. And the definition cannot be partly overridden: a ui:define replaces the whole body of the slot, default included, which is why a template that wants "default plus something" should expose a second, smaller slot instead.

Source: Jakarta EE Tutorial: Using Facelets Templates

A template can itself be a template client. A second-level template names the site template with <ui:composition template="...">, fills some of its slots with ui:define, and leaves room for its own clients by putting new ui:insert elements inside those definitions. The Bookshelf uses this for every catalogue page, which share a filter sidebar:

The result: the title slot of the site template received Catalogue - Fiction, the content slot received the sidebar and a section holding Dune, and the footer slot was filled with custom footer even though the middle template never mentions it. Slots of the outermost template are therefore reachable from any depth: the client defines footer and it flows through the second level. The slots heading and main exist only in the middle template. A page that defines nothing renders the defaults of every level (Catalogue - Books, No books and (c) Bookshelf).

Keep the chain shallow. Two levels, a site layout and a section layout, covers nearly every application; deeper chains make it hard to tell which file a slot comes from.

Source: Jakarta EE Tutorial: Using Facelets Templates

<ui:include src="..."> inserts another Facelets file at that point. It is the right tool for a repeated piece of markup that has no slots of its own, such as one row of the catalogue. The included file is normally a <ui:composition> (or <ui:component>), whose content is what gets included. <ui:param name="..." value="..."/> inside the ui:include passes a variable into it:

This rendered <li>Book 1: Dune</li> and <li>Book 2: Emma</li>. A few rules:

Source: Jakarta EE Tutorial: Using Facelets Templates and Jakarta Faces 4.1 VDL: ui:include

<ui:decorate template="..."> applies a template to a part of a page instead of to a whole page. Unlike ui:composition, it does not discard what surrounds it: the markup around the tag stays, and only the tag’s own content is replaced by the template’s rendering. Its ui:define children fill the template’s slots just as in the page case.

The output was <div class="box"><h3>Decorated</h3>inside box</div>, inside the page’s surrounding markup. The comparison that sticks:

A ui:composition with no template attribute is useful for the files meant to be included, as book-line.xhtml above: only the content of the composition is used, so the file can contain a full html wrapper, or a comment, for the editor’s benefit.

The output of the decorated region was identical on Mojarra and MyFaces. The VDL defines ui:decorate as identical to ui:composition except that it does not discard the content around it.

Source: Jakarta Faces 4.1 VDL: ui:decorate and Jakarta Faces 4.1 VDL: ui:composition

<ui:component> is a ui:composition that also creates a component, and, like ui:composition, it discards everything outside the tag. It is used as the root of an included file when the fragment needs an id, a binding or a rendered condition for its whole content:

A page that wrote before, <ui:include src="/WEB-INF/includes/comp.xhtml"/>, after and a <ui:fragment id="frag">fragment body</ui:fragment> produced, on both implementations:

The two differences from the other tags are visible: discarded before and discarded after are gone, and the ui:fragment kept its surroundings. Neither tag renders an element of its own; the component they create is a place in the tree to which id, binding and rendered apply, so rendered="#{...}" on a ui:component is the way to switch off a whole included file at render time. Binding either tag to a bean property follows the rule of every component binding: the bean must be request scoped or narrower.

Source: Jakarta Faces 4.1 VDL: ui:component

<ui:fragment> wraps a region in a component, so that the region can be given an id, a binding and, most usefully, a rendered condition:

Only the second line reached the output. This is a render-time condition evaluated on every request; contrast it with the tags that decide at view build time, discussed on the page about JSTL tags and build time against render time. The VDL also requires the bean behind a binding on a ui:fragment or ui:component to have a scope no wider than request scope, as for any component.

<ui:repeat> is the template-level loop. It iterates over a List, array, DataModel, Map or other Iterable, exposing each item as var. Its varStatus has the read-only properties index, first, last, even, odd, begin, end and step; over ['a','b','c'] the status read 0/true/false/true, 1/false/false/false and 2/false/true/true for index, first, last and even. There is no count property: asking for #{status.count} gave 0 on Mojarra and a PropertyNotFoundException on MyFaces, so a one-based number is #{status.index + 1}:

The attributes begin, end, step, offset and size limit the range, and the implementations disagree on several of them. begin and end are zero-based and end is inclusive. When begin, end or step is not set, the matching status property is an empty string on Mojarra and, on MyFaces, 0, the number of items and 1. The table lists what each implementation rendered for a four-item list a, b, c, d:

So set begin and end together, treat size as implementation-specific, and never ask for a range larger than the collection. In a range, first is true for the first item rendered and even counts from it: with begin="1" the item b read first=true and even=true on both implementations. The iteration, its rowStatePreserved attribute (documented in the 4.1 VDL and absent from the 4.0 one) and the differences with h:dataTable are covered in depth on the data tables and iteration page.

ui:repeat is a component, not a tag handler: it renders its children once per item and re-evaluates value on each request, so it works with h:inputText and f:ajax inside it, using the item index as a part of the client id. The component tree and the identifiers of repeated components are explained on the architecture page. The tag handler alternative, c:forEach, builds the view once and is a different tool with different consequences, explained on the JSTL page.

Source: Jakarta Faces 4.1 VDL: ui:repeat and Jakarta Faces 4.1 VDL: ui:fragment

<ui:remove> deletes its content at view build time. Nothing inside is rendered, and nothing inside is evaluated: in the scratch application the body was mock text #{nonsense.boom}, an expression that would fail with a property-not-found error if it were evaluated, and the page rendered normally without a trace of it. That makes it the right place for design-time mock content or notes that should not leave the server, unlike an XML comment, which does reach the browser unless FACELETS_SKIP_COMMENTS is set (see the comments section of the Facelets page):

<ui:debug hotkey="d"/> adds a debugging aid to the page. With the tag present, the rendered page contains a short script that listens for a keyboard shortcut (Ctrl+Shift plus the hotkey letter, d when omitted; the value cannot be an expression) and opens a window that shows the component tree, the scoped variables and the request information of that request. The rendered attribute turns it on and off. The VDL says the tag works only in the Development project stage, but the script was rendered in the Production stage as well on both implementations, so guard it so that it never ships:

Use it only in development. In the scratch application the tag with hotkey="x" rendered an inline script that opens the debug window on Ctrl+Shift+X (the script tests the upper-case letter together with the Shift and Control keys). With the guard above the script was present in the Development stage, and an expression comparing the stage with 'Production' removed it, on both implementations. The measurement of the debug window in the Production stage, and the reason to put the guarded tag in the one template that every view uses, are on the project stages page.

Source: Jakarta Faces 4.1 VDL: ui:debug and Jakarta Faces 4.1 VDL: ui:remove

Pages that take view parameters or view actions declare them in f:metadata, which must be a direct child of f:view (see the core tags page and the view parameters page). In an application with a template, the question is where that block lives. The portable answer, run on both implementations, is to put f:view in the template, leave a named slot for the metadata inside it, and let each client fill the slot:

A request for /tpl-good.xhtml?isbn=978 printed isbn=978 on Mojarra and MyFaces: the view parameter reached the bean and the preRenderView listener ran. Two other placements were tried and are not portable:

The slot costs nothing for clients that need no metadata: a ui:insert without a definition renders nothing.

Source: Jakarta Faces 4.1 VDL: f:metadata

All the ui tags except ui:repeat, ui:fragment, ui:component and ui:debug are tag handlers. They run while the view is built: on the first request (a GET) inside Render Response, and on a postback in Restore View, before any submitted value reaches the model (see the lifecycle page). Four consequences follow.

A subtle point from the specification: a UIComponent tag does not create a second component when one with its id is already in the tree, and it removes a child that is not rendered on this display of the page, as a tag nested in a c:if whose condition turned false. The rule and a measurement are in the Facelets page.

A template does not have to be a file of the WAR. Any file under META-INF/resources of a JAR in WEB-INF/lib is served as if it were in the web application root, and template and src can name it with an absolute path. A JAR with META-INF/resources/shared/jar-layout.xhtml:

The response was <div class="from-jar">JAR layout: client content</div> on Mojarra and MyFaces. A shared module can therefore ship a layout, and the applications that depend on it choose their pages. The price is that the file name becomes part of the module’s contract with its users; give shared templates a prefix directory (shared/ above) so that they do not clash with the application’s own files.

Source: Jakarta Faces 4.1 specification, 10 Facelets and its use in Web Applications

A template does not have to live in the WAR. A resource library contract is a directory under META-INF/contracts in a JAR (or under contracts in the web application root) that bundles templates, their CSS and scripts. A client names a template of the contract in the usual way, <ui:composition template="/topNav_template.xhtml">, and the runtime looks the file up in the contracts that are active for the view. Replacing the JAR therefore restyles every client without touching their markup, provided the template names and slot names (the contract’s declaration) stay the same. Contracts are the way to ship a theme as a reusable library; for everything inside one application, a plain template under WEB-INF/templates, as above, is simpler. The directory layout, the selection of a contract per view or per URL with f:view contracts or faces-config.xml, the default contract and multi-tenant themes are the subject of the Resource Library Contracts page; the VDL asks for an absolute path in src when the included file comes from a contract.

Source: Jakarta Faces 4.1 specification, 10 Facelets and its use in Web Applications

Everything above was run on both implementations. Where they differ, the page uses the portable form; the differences are:

Source: the scratch runs described at the top of this page.

Nothing else in the ui library changed between 4.0 and 4.1; every example on this page runs unchanged on both. The version history of the project as a whole is on the versions page.

Facelets Essentials: Guide to JavaServer Faces View Definition Framework by Bruno Aranda and Zubin Wadia (Apress, 2008) is a short, readable introduction to the same ideas, and its templating chapters are still conceptually right: ui:composition, ui:define, ui:insert, ui:include, ui:param, ui:decorate, ui:fragment, ui:repeat, ui:remove and ui:debug mean what they meant then. What changed is everything around them, because the book describes Facelets 1.x, a standalone open-source library that was added to JSF 1.1 and 1.2 applications in place of JSP:

Use the book for the explanation of why templating works the way it does, and this page and the specification for the syntax to type today.

Source: Bruno Aranda and Zubin Wadia, Facelets Essentials (Apress, 2008, ISBN 978-1-4302-1049-8), and Jakarta EE Tutorial: What Is Facelets?