Facelets & XHTML Views

Facelets is the view declaration language (VDL) of Jakarta Faces: the language in which a view is written. The specification defines a VDL as the thing that knows how to create a view from a view identifier, how to build the component tree of that view and how to render it, and it defines Facelets as the VDL that must be present in every implementation. Pages are authored in XHTML; a Facelets page is not a program, and it is not sent to the browser as it is written. It is compiled into a tree of objects, and that tree, when it is run, creates the UIComponent tree of the view and so describes it.

Three properties of that pipeline explain most of what follows.

The Jakarta EE Tutorial lists what Facelets offers on top of that: XHTML pages, Facelets tag libraries in addition to the Faces and JSTL ones, Expression Language, templating for components and pages, code reuse through templates and composite components, compile-time validation of EL and a faster compilation than Jakarta Server Pages.

Source: Jakarta Faces 4.1 specification: Facelets and its use in Web Applications and Jakarta EE Tutorial: What Is Facelets?

Jakarta Faces 1.x used Jakarta Server Pages (JSP) as its view technology, and the two did not fit together well. A JSP page is compiled to a servlet that runs once per render, and the component tree is built by the order in which the tag handlers of the servlet execute, interleaved with the template text; Facelets compiles to a tree that builds the component tree and so has the whole tree in hand. The specification lists the differences itself:

The consequence that matters most when you read old code: in JSP, an EL expression in template text was evaluated by the JSP engine, not by Faces, and was evaluated before the components it referred to existed. In Facelets, template text containing an expression becomes an h:outputText component, as The XHTML Rules shows.

Jakarta Server Pages views were deprecated in JSF 2.0 and are removed in Faces 4.0. A migration therefore turns every .jsp view into a Facelets view; there is no option to keep both in a 4.x application.

Source: Jakarta Faces 4.1 specification: Differences between Jakarta Server Pages and Facelets (10.1.1)

The smallest useful page of the Bookshelf shows a book title that comes from a CDI bean. The bean is the one used for all the examples on this page.

The title deliberately contains & and angle brackets, because the interesting question about any output is what happens to them (Escaping). Here is the page.

Reading it from the top:

Running the page on Mojarra 4.1.17 produces this response:

The h: and f: prefixes are gone, h:head and h:body became head and body, the xmlns:h and xmlns:f declarations were removed, and the XML declaration was passed through. Because the bean text was Dune & <Messiah>, both the template text and the component print Dune & <Messiah>: the output is escaped by default, in template text as well as in h:outputText. The two forms differ only in that the second is a component in the tree and so can carry an id, a rendered condition, a converter and a style.

Source: Jakarta Faces 4.1 specification: XHTML Specification for Facelets (10.3)

The specification requires the runtime to accept every page that conforms to the XHTML 1.0 Transitional DTD, and the Jakarta EE Tutorial says the same. In practice that means these rules, each checked on Mojarra 4.1.17:

A tag means something only through its namespace. The prefix is a local alias and is conventional, not mandatory: xmlns:composite="jakarta.faces.composite" is as good as xmlns:cc=.... The current namespaces, which are plain URNs without a scheme and are the ones to use since Faces 4.0, are:

The conventional p: prefix of jakarta.faces.passthrough is also the conventional prefix of PrimeFaces (xmlns:p="http://primefaces.org/ui", see the PrimeFaces setup page). A prefix is only an alias, so when both appear in one page give one of them another prefix, pt: for example. The HTML5-friendly markup page covers pass-through markup.

Every element in a Facelets file is one of four things, and which one decides when it takes effect.

The distinction matters for three recurring questions. A rendered attribute exists only on component tags, because only they stay in the tree to be asked at render time. A c:if can hide a helper tag such as f:ajax or f:validator, which has no rendered attribute, because it decides whether the helper exists at all. And an expression in a tag handler attribute (test of c:if, src of ui:include) is evaluated before the submitted values have reached the model on a postback; the JSTL page shows the measurement. The templating tags and the components they create are listed one by one in the templating page, and a library of your own tags is the subject of the tag files and tag libraries page.

Source: Jakarta Faces 4.1 specification, 9.1 UIComponent Tags and Jakarta Faces 4.1 specification, 10.4 Standard Facelet Tag Libraries

h:head and h:body render the HTML head and body elements, and they are not interchangeable with the plain elements. Faces keeps the resources of a view — the style sheets and scripts added by h:outputStylesheet, h:outputScript, f:ajax (which needs the Faces JavaScript library) and component libraries — and puts them in the right place when it renders: those with target="head" (the default for style sheets) go into the rendered h:head, and target="body" ones go to the end of the h:body.

If the page has a plain head instead of h:head, the resource has nowhere to go. A page with this body:

was rendered with the text x, no style sheet link and, in the Development stage, a warning block at the end saying that one or more resources have the target head but no head component is defined in the view. The same applies to a missing h:body when a resource asks for the body. MyFaces 4.1.4 rendered the same page, again without the style sheet, but without the warning block, so there the symptom is only the missing resource.

Use h:head and h:body in every page that is not a fragment, and put them in the template when a template is used so that the pages that fill it do not repeat them. In a template client page that supplies only a fragment of a layout there is no html element at all, which is the topic of the templating page.

Source: Jakarta Faces 4.1 VDL documentation: h:head, h:body, h:outputStylesheet, h:outputScript

Two tags of the core library describe the view as a whole rather than a part of it.

f:view is the root of the component tree. It is optional in Facelets, because the UIViewRoot always exists, but it is the place to set properties of the view as a whole: locale (a literal or an expression), contentType, encoding, renderKitId, beforePhase and afterPhase for phase listeners on this view, contracts for resource library contracts and transient for a stateless view. It may wrap the content of the html element, as the example below does.

f:metadata declares the view metadata: parameters read from the request (f:viewParam), actions run on the initial request (f:viewAction) and system events (f:event). The point of the tag is that the metadata of a page can be read without building the rest of the page, which is how a bookmarkable URL such as /book.xhtml?isbn=... fills the bean before the page is rendered. The view parameters page covers them; here it is enough to know where the tag goes. In a template, the tag cannot be written in the template itself; the portable pattern is a slot inside the template’s f:view, explained in the templating page.

A request for /d.xhtml?q=1 rendered

so the view’s locale is de and the parameter reached the bean. The f:viewParam writes to a bean property, never to a read-only expression: pointing it at #{param.q}, which cannot be written, fails with a PropertyNotWritableException at the position of the tag.

Source: Jakarta Faces 4.1 VDL documentation: f:view, f:metadata, f:viewParam and Jakarta Faces 4.1 specification: Jakarta Faces Core Tag Library

An XML comment in a Facelets page is not a Facelets comment. It is markup like any other, and in the default processing modes it is passed through to the browser. Worse, expressions inside the comment are still evaluated. This page

was sent as

MyFaces 4.1.4 evaluated the expression too, but wrote its result into the comment without escaping it (<!-- note: Dune & <Messiah> -->), where Mojarra escaped it as shown above. That has two consequences. Every visitor can read your comments in the page source, and the bean method behind the expression runs even though nothing is visible. In a run of a page with the comment, the paragraph and one more attribute that used the same expression, the bean getter was called three times, once for each place. If the expression reads a lazily loaded collection or calls a service, the cost is paid on every request, and if it throws, the page fails because of a comment.

There are two remedies, and they are not equivalent.

With the parameter set, the book.xhtml comment line above came out as an empty line in the response, and the Evaluated: paragraph was unchanged. The specification wording is that "any XML comments in the Facelets source page are not delivered to the client". The specification does not say whether expressions inside a skipped comment are still evaluated. They were not: with the parameter set, the same page called the getter twice (paragraph and attribute) instead of three times, on both implementations.

Two cases need care. The old Internet Explorer conditional comments (<!--[if IE]> ... <![endif]-->) are comments and are dropped by the switch; they are historical and no current browser needs them. Without the switch Mojarra 4.1.17 did not deliver such a comment intact: the evaluated text was escaped, giving <!--[if IE]&gt; ie &lt;![endif]-->, while MyFaces delivered it unchanged. And a comment inside an inline script element is not safe from the switch either: with the parameter set, <script>/* <!-- in script --> */ var a = 1;</script> was sent as <script>/* */ var a = 1;</script> by both implementations, so the switch also removes the <!-- --> pairs that old scripts used to hide code from browsers.

Source: Jakarta Faces 4.1 specification: context parameter FACELETS_SKIP_COMMENTS and Jakarta Faces 4.1 VDL documentation: ui:remove

Three kinds of escaping meet in a Facelets page, and they are applied at different times.

Three details are worth knowing.

Output is escaped by default, and escape="false" is how you lose that. This page

is sent as <b>bold</b>, which is the intended effect for text you control. With a value that comes from a user, the same attribute is a stored cross-site scripting hole. Escape-free output belongs only on markup produced by the application, and a user-supplied rich text must pass through a sanitiser first.

A CDATA section survives, but its content is escaped. In both the html5 and xhtml modes the start and end tags of a CDATA section are passed through, and the text inside is escaped like any other text, so

is sent as <p>Cdata: <![CDATA[ a &lt; b ]]></p>. A browser parsing the output as HTML does not treat <![CDATA[ as a CDATA section, so the markers appear as a (bogus) comment or as text depending on the browser. Do not use CDATA to put script or style into a page that is served as HTML. Move the script to a file and load it with h:outputScript, which is also what the content security policies of a modern application require, or write < where a < is needed.

The jspx mode does not escape inline text. This is the only mode of the four in which the text is passed through raw, as the table in The XML declaration and the doctype shows, and only for files you have mapped to that mode on purpose.

Source: Jakarta Faces 4.1 VDL documentation: h:outputText (escape) and Jakarta Faces 4.1 specification: processing modes (Table 17)

A Facelets file is run again every time its view is built, and a postback builds the view again (the Restore View phase runs the same tag handlers, then applies the saved state). The Faces specification says what the component tags do when the view they build into already contains components, in the section on deleting components on redisplay:

The first rule keeps the tree stable; the second is the reason a build-time condition and the rendered attribute are not interchangeable. The measurement uses a view-scoped bean with a flag and two outputs, one under c:if and one with rendered, and prints the client ids of the components that are in the tree:

The tree paragraph on the initial GET, after a postback of the noop button, after hide and after another noop:

The two implementations gave identical results. f:byRendered stayed in the tree throughout and was skipped by the renderer; f:byTag was deleted. For a plain output the difference is invisible. For an input it is not: a deleted input loses its submitted value, its validation state and the listeners and Ajax behaviors that were attached to it, and an Ajax request that names it in render or execute can no longer find it. So, for anything that the user can show and hide, use rendered, or ui:fragment with rendered, and keep c:if for decisions that do not change while the view lives (see the decision table).

Source: Jakarta Faces 4.1 specification, 9.2.4 Deleting Components on Redisplay and 9.2.3 Creating Components and Overriding Attributes

The parameters below are specified for every implementation. They are set as context-param entries in web.xml.

During development on Mojarra 4.1.17, setting jakarta.faces.FACELETS_REFRESH_PERIOD to 1 was needed to see an edit of an XHTML file without a restart; the project setup page explains the edit-and-reload loop.

Source: Jakarta Faces 4.1 specification: Faces context parameters (Facelets)

The examples of this page were run on Mojarra 4.1.17 and, except for the items named under the table, on MyFaces 4.1.4. Most behaviour is identical: the XHTML rules and error messages, the doctype and processing modes, the old and new namespaces, f:view, escaping and comment handling all matched. The differences found:

Not repeated on MyFaces: the context-parameter table, the jspx processing mode and the behaviour of the FACELETS_BUFFER_SIZE and FACELETS_DECORATORS parameters, whose descriptions come from the specification.

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

Three of the books consulted for this section discuss Facelets as a view technology. They are useful for the concepts and wrong in the details of every file you would type from them.

On a discrepancy the official documentation linked on this page wins.