JSF Central - Inside Facelets Part 2: Using Facelets
JSF Central

 Articles & Books 
Inside Facelets
Inside Facelets Part 2: Using Facelets
by Jacob Hookom
22 Sep 2005 02:45 EDT

This is the second of a series of articles about Facelets, an alternative view technology for building JSF applications. The first article provided an introduction to Facelets. In this article, Jacob explains how you can begin using Facelets in your JSF applications today.

Facelet Compilation

As mentioned in the previous article, Facelets compiles valid XML. These files could be one or three lines long, again the only point is that they are valid XML.

Facelets uses SAX to compile the document into a stateless tree of TagHandlers contained within a Facelet object. Facelets are thread-safe and can easily be used in large scale deployments by multiple requests at once. Facelets will provide warning messages at compilation time along with information on libraries used and view handling within JSF.

Executing Facelets compilation is simple, as shown below:

// grab our FaceletFactory and create a Facelet
FaceletFactory factory = FaceletFactory.getInstance();
Facelet f = factory.getFacelet(viewToRender.getViewId());

// populate UIViewRoot
f.apply(context, viewToRender);

More information about Facelet's architecture will be provided in a later article.

Exceptions & Debugging

Great care was taken with Facelets and it's error handling. Lets say for a moment that you mistyped an expression in an attribute. Facelets will generate an error like this at compilation:

greeting.xhtml @18,97 <input action="#{success[}"> Error Parsing: #{success[}

As you can see above, Facelets provides you with error message that tell you what file, line, and column number the error occured. More specifically it also provides the element and attribute that was errant.

Facelets also uses the java.util.logging package to handle output of debug messages. You can read more here on setting up logging with your JRE.

Custom Components

Facelets allows you to use an XML file or Java code to define your component libraries, although I will only go through the XML configuration option in this article as it is the preferred choice.


That's all you need to integrate your component into Facelets. These XML files can be refrenced in two ways:

  1. Reference them in a ";" delimitted list within your web.xml under the init-param "facelets.LIBRARIES". These files are relative to your application, just like referencing Struts configuration files.
  2. Package them in your JAR's META-INF folder with a file extension of ".taglib.xml". Facelets will automatically pick these up for compilation just as with JSP tld files.

Within a facelet-taglib file, you can also specify converters, validators, and custom TagHandlers for ultimate control over document processing.

Custom Validators & Converters

Validators and Converters can also be represented in a Facelet via the same facelet-taglib file.


Again, Facelets works closely with JavaServer Faces's existing API and this is all you have to define. Facelets will automatically wire all properties on your Converter or Validator objects.

Custom Tags

Okay, I haven't thought of it yet and you want to add your own custom tag to Facelets. This includes cases where you want unique behavior for wiring properties and attributes to UIComponents, Validators, or Converters.

Facelets provides many foundation classes you can extend in order to make your job simpler. Let's first take a look at source for <c:if> to give you an idea:

public final class IfHandler extends TagHandler {

    protected final TagAttribute test;
    protected final TagAttribute var;

    public IfHandler(TagConfig config) {
        this.test = this.getRequiredAttribute("test");
        this.var = this.getAttribute("var");

    public void apply(FaceletContext ctx, UIComponent parent)
            throws IOException, FacesException, ELException {
        boolean b = this.test.getBoolean(ctx);
        if (this.var != null) {
            ctx.setAttribute(var.getValue(ctx), new Boolean(b));
        if (b) {
            this.nextHandler.apply(ctx, parent);

That's it! You will notice that Facelets uses the "good citizen" principle and constructor injection when the document is compiled. Facelets and all tags are stateless, unlike JSP (which also pools tag handler objects). More technical details are provided in a separate article, so lets describe what's going on in the tag.

TagHandler, which <c:if> extends, is a great example of the foundation classes you can use to develop custom tags. Think of TagHandler as JSP's TagSupport or BodyTagSupport.

At construction, the representation of the Tag is passed (TagConfig) which conveys the structure of the document including: location, child tags, and attributes.

TagAttributes are representations of the attributes specified in the XML document. They have many methods for handling EL expressions and coercions to the types you need. They too are stateless and their methods require passing the FaceletContext to provide the current state.

The last point of interest is that the children are represented by the member variable nextHandler. You can apply the children as many times as you want or not at all as in the case of <c:if>.

Once your custom tag is written, you can go ahead and add it to a facelet-taglib file like so:



This was just a short introduction to using the Facelets framework. More articles will follow that will go into greater detail with templating, features, and customizing Facelets.

RSS feed(all feeds)

The Editor's Desk
Inside Facelets
In the Trenches

Site version 1.83  Report web site problems

Copyright (C) 2003-2015 Virtua, Inc. All Rights Reserved. Java, JavaServer Faces, and all Java-based marks are trademarks or registered trademarks of Oracle Corporation. in the United States and other countries. Virtua, Inc. is independent of Oracle Corporation. All other trademarks are the sole property of their respective owners.