JSF Facelets Tools Tutorial

In this tutorial we will build and execute a JSF Facelets application and highlight the features contributed by the JSF Facelets Tools Incubator Project.


In this tutorial we will create and execute a web application using the JSF Facelets technology. Facelets is an extension to JavaServer Faces(JSF) that uses XHTML syntax to define a JSF page. The JSF Facelets Tools project is a WTP incubator project that has provided features that simplifies building web applications using Facelets. The tool enables the current features of the JSF Tools Project to be used in a dynamic web project for Facelets. These include an enhanced HTML Source Editor that provides Content Assist and Validation for Facelets Tags.


Setup Apache Tomcat Server instance

Setup an instance of the Apache Tomcat Server using the information in 'Setup' section of this tutorial Building and Running a Web Application.

Register JSF libraries

This feature allows for a named sets of jars to be created for use with JSF Applications. We will be creating a library containing the Sun JSF RI
Select Windows->Preferences->Web and XML->->JavaServer Faces Tools->Libraries. Click on the New.. button to add a new library. Create the JSF Libraries as shown in the following figures. Check the is JSF Implementation check box when adding the Sun JSF RI library.

JSF Libraries-add

Create another JSF Library called JSTL that has the JavaServer Pages Standard Tag Library jar as shown below.

JSF Libraries

And finally, create another JSF Library called Facelets that has the Facelets jar as shown below.

JSF Libraries

Create a JavaServer Faces Project

Create a New Dynamic Web Application with the name of JSFFaceletsTutorial. Set the target runtime to the Apache Tomcat 6.0
In the configuration section, select the Facelet 1.0 Project. Skip the next panel to get to the JSF Capabilities page.

New Dynamic Web Application

On the JSF Capabilities page, select the radio button adjacent to the JSF Library JSF-RI-1.2. Add the JSTL and Facelets 1.1.14 libraries.

JSF Capabilities page

If you deploy the JSF web application to a server runtime that includes the JSF 1.2 reference implementation, then you should select the Server Supplied JSF implementation option.

On the Facelet page, select all the checkboxes.

Facelets Configuration page

Click on the Finish button to create the JavaServer Faces Application. You may be prompted to accept the license for the Web App DTD from Sun. You may also be asked to choose the J2EE perspective upon completion. In both cases accept.

Your JSF application has been created. Note that the web.xml file has been updated with the Faces Servlet and servlet-mapping, the default suffix for a JSF page has been set to XHTML. A JSF application configuration file (faces-config.xml) has been created and configured to use Facelets as the view handler.

Create Facelets template pages

You will now create a Facelets template page. Create a folder called templates under the WEB-INF folder. Use the HTML wizard to create a template page called, BasicTemplate.xhtml under this folder. Right-mouse click on the template folder, select New->HTML to launch the HTML wizard. In the Select Templates page of the wizard, select the New Facelet Template template. Click Finish.

Create Facelets Template

Edit the template file following the instructions in the template. You will create and include the header and footer templates. Your final template file should be as shown below.

Facelets Template

Create the header and footer templates under the template folder using the New HTML Wizard as described above. In the Select Template page of the wizard, choose the corresponding template files, New Facelet Header and New Facelet Footer. Make changes to the templates as shown below.

Facelets Template

Create a JSF Page

Create a JSF page with Facelets tags that will use the template created in the previous step. Use the HTML Page wizard to create a page called login.xhtml in the Web Content folder of the new application. In the Select Templates page of the wizard, select the New Facelet Composition Page template. Click Finish.

JSF Facelets Page

Facelets Tag Attribute Validation and Content Assist

The JSF Facelets Tools incubator project adds support for validating attributes of Facelets tags and also provides Content Assists on them. Note the warning on the template attribute of the <ui:composition tag.

Facelets Tag Attribute Validation

Position the cursor in between the double-quotes of the template attribute and hit Ctrl + spacebar to get Content Assist. You should see a pop-up listing the directories under the WebContent folder. Select /WEB-INF/templates/BasicTemplate.xhtml

Facelets Tag Attribute Content Assist

Complete the JSF page

Delete the <ui:define tags for the header and footer. The page will get the header and footer from the template. Add the tags for the login in the content section as shown below. Please note that the current release of the JSF Facelets Tools incubator project doesn't support the visual rendering of an XHTML page in the JSF Web Page Editor. However, all the productivity features available in the Source Page of the Web Page Editor for editing a JSP page are available in the HTML Source Editor for building a JSF Facelets page in XHTML.

Facelets Login page

Configure the Managed Bean

In the Project Explorer, expand the node, JSFFaceletsTutorial->WebContent. Double-click on faces-config.xml . This will launch the Faces Configuration editor. Select the ManagedBean tab.

Faces Config Editor Managed Bean

Click on the Add button. This will launch the New Managed Bean wizard. Select the option, Create a new Java class. In the next wizard panel, enter the package as, com.tutorial and the Name of the class as LoginBean . Click the Finish button.
This will create the Java class and register it as a managed bean. Save the Faces Configuration editor.To edit the Java class, click on the hyperlink, ManagedBean class in the Managed bean page as shown in the figure below. This will launch the Java editor.

Faces Configuration Editor - Managed Bean tab

Edit the Java class, com.tutorial.LoginBean. Add the following code and save.


Run the JSF Facelets Page

You will now execute the login.xhtml page against the Apache Tomcat server. Choose Run on Server using the context menu while selecting the login.xhtml page in the navigator. Choose your Apache Tomcat server and set it up as required if you had not already done so. Click Finish. You should see from the Console view that the Tomcat server starts and then you should see the executing login page appear in the Web Browser like below.

Congratulations! You have created and executed your first JSF Facelets application using the Eclipse WTP Incubator JSF Facelets Tools Project.