On Java Development

All things related to Java development, from the perspective of a caveman.

Facelets Templating

without comments


This post is about Facelet templates that are used to define page composition. Templates makes it possible to reuse page segments such as the page’s banner or header. When used throughout the web application’s pages, Facelets simplifies the task of page design, provides the means to apply changes in a single place that can propagate across all pages and helps to ensure a consistent layout from page-to-page.


Facelets was originally created by Jacob Hookom in 2005 as a separate, alternative view declaration language for JSF 1.1 and JSF 1.2 which both used JSP as the default view declaration language. Starting from JSF 2.0, Facelets has been promoted by the JSF expert group to be the default view declaration language. JSP has been deprecated as a legacy fall back.

First, let’s go over a few of the Facelet UI tags.

  • ui:composition – The UI Composition tag is a templating tag that wraps content to be included in another Facelet. Any content outside of the UI Composition tag will be ignored by the Facelets view handler. Any content inside of the UI Composition tag will be included when another Facelets page includes the page containing this UI Composition tag. See also
  • ui:define – The Define tag is a templating tag that defines named content to be inserted into a template. The name attribute value must match that of a ui:insert tag in the target template for the named content to be included.
  • ui:include – The UI Include tag is a server-side include tag for Facelets. It simply includes the document pointed to by the “src” attribute as part of the current JSF page. The included document should use a component or composition tag to trim unnecessary markup, or it may simply contain a fragment of XHTML or XML to be included.
  • ui:insert – The UI Insert tag is a templating tag that declares a named content element to be defined by another Facelet. It can be used effectively with the ui:define tag to pass values between Facelets.

Shown below is a simple flow diagram that illustrates how the page request results in the presentation of a fully constructed web page.

The process begins with the URL placed into the browser to request page01.jsf. Using a mapping process defined by the developer, this resolves to the actual page source i.e. page01.xhtml, the beginning of which is shown below.


Lines 1-10 appear at the beginning of all xhtml-based web pages. They define the name spaces to be referenced when specifying a page component such as a drop-down listbox or a password field. Line 11 defines the title of the page. This text appears in the browser’s tab. Line 13 declares the body of the page itself. What follows is all about Facelets.

Line 15 references pageTemplate.xhtml and indicates it is to be used to describe the page’s composition.

Line 17 assigns content as the name of this composition. This name will be referenced by pageTemplate.xhtml that is presented next.

All HTML elements, whether they be from the Tomahawk, RichFaces or other libraries that are assembled to make up the page body is placed in the section, bounded by line 17 and 22. This is the content area that is inserted into the pageTemplate.xhtml.

Line 22 completes the <ui:define boundary.

This is the source for pageTemplate.xhtml It begins with the usual xml name space (xmlns) declarations as before.

Line 12 declares a Cascading Style Sheet (CSS) file that is used to help format text and other HTML elements.

Line 18 uses the ui:include to pull in another xhtml file that contains the page’s header element.

Line 22 references content, defined in page01.xml presented above. It tells the Facelets compiler to inject all of the code that appears between the ui:define tags here.

The source for header.xml is listed below in its entirety.

Lines 21-23 are used to establish the values for the three text fields that make up the page’s title section. The first title is to hold the value for the department name such as Policy Holder Services. The second is to hold the name of any sub-section or group within the department, if it exists. The third text field holds the name of the application. If the sub-section or group does not exist, simply comment it out and let the name of the application float up into the space.

Including a generic Wait Dialog
In this section, a generic wait dialog, built once, will be included into a page. This illustrates the potential to reuse dialogs and other page segments.

Shown below is the xhtml source for a wait dialog. For more information about the wait dialog and how it is used, see this post.

As before, the composition segment begins with the usual xmlns references. The body of the dialog begins on line 13. The source presented below shows how to include this into the main page that will use the dialog.

As can be seen, it’s really simple to include. There are a couple of benefits to this approach. The first is that the code for the wait dialog will not clutter the page being developed and maintained. The more valuable aspect is that if for any reason the wait dialog has to change, the change can occur once and all of the web pages of the project will be affected.

This completes the topic. Below are a couple of references for your reading pleasure.

Facelets Wiki
Facelets UI Tag Reference

Written by admin

February 1st, 2014 at 10:25 am

Leave a Reply

You must be logged in to post a comment.