Facelets (http://facelets.dev.java.net/ ) was designed by the as a way to make rendering JSF components in web pages more straightfoward than using JSP for a view technology. Discussing the differences and reasons to use Facelets over JSP with JSF is a discussion best saved for the article Improving JSF by Dumping JSP. Basically JSP and JSF collide with each other when it comes time to render the view to the user. Using Facelets is one way to avoid this. If you’re new to Facelets JSFCentral has an excellent primer on the subject; “Inside Facelets” (Part 1) – (Part 2).

Configuring MyEclipse to use Facelets actually fairly straightforward. The basic steps to accomplish this are:

  • Create a new Web Application
  • Add JSF capabilities to the new Web Application
  • Add the facelets libraries to it the application.
  • Update the XML configuration files to activate Facelets support.

This document borrows heavily from the Facelets Getting Started guide (https://facelets.dev.java.net/nonav/docs/dev/docbook.html#gettingstarted-setup) and you should also refer to this guide when possible.

First, you need to add the facelets libraries as a User Library in MyEclipse. Consult the Eclipse docs for how to add user libraries if you’re unsure of this.

Next, create a new MyEclipse web project. I called it NumberGuess for this since it uses the NumberGuess example from the Facelets developer kit. I left the J2EE spec level at 1.4 and left out the JSTL libraries for this.

Then you’ll have a basic Web project in MyEclipse. For this article I used Java 5, but I’ve done the same project in Java 1.4 with no issues.

Next add JSF capabilities to your project by right-clicking on the root project node and selecting MyEclipse | Add JSF Capabilities.

For this example I used the Sun JSF RI. But MyFaces works equally well. Please be sure to change your URL pattern to *.jsf for the purpose of this example.

Update the web.xml and face-config.xml files according to the Facelets Getting Started guide. I’ve included the listings below that are the end result from following the getting-started guide.

Create three new files in the WebRoot directory: guess.xhtml, response.xhtml and template.xhtml and update them as per the listings in the Getting Started guide.

At this point the basic layout for a Web project with Facelets is complete. From here you should be able to deploy to a Tomcat container.

To simplify things, I’ve included the NumberGuess project in this article as a sample. You’ll still need to create your own User Library for Facelets.

You can download it here.

web.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        version="2.4"
        xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee   http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
        <!-- Use Documents Saved as *.xhtml -->
        <context-param>
                <param-name>javax.faces.DEFAULT_SUFFIX</param-name>
                <param-value>.xhtml</param-value>
        </context-param>
        <!-- Special Debug Output for Development -->
        <context-param>
                <param-name>facelets.DEVELOPMENT</param-name>
                <param-value>true</param-value>
        </context-param>
        <!-- Optional JSF-RI Parameters to Help Debug -->
        <context-param>
                <param-name>com.sun.faces.validateXml</param-name>
                <param-value>true</param-value>
        </context-param>
        <context-param>
                <param-name>com.sun.faces.verifyObjects</param-name>
                <param-value>true</param-value>
        </context-param>

        <!-- Faces Servlet -->
        <servlet>
                <servlet-name>Faces Servlet</servlet-name>
                <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
                <load-on-startup>1</load-on-startup>
        </servlet>

        <!-- Faces Servlet Mapping -->
        <servlet-mapping>
                <servlet-name>Faces Servlet</servlet-name>
                <url-pattern>*.jsf</url-pattern>
        </servlet-mapping>
</web-app>



faces-config.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE faces-config PUBLIC "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.1//EN" 
                       "http://java.sun.com/dtd/web-facesconfig_1_1.dtd">
<faces-config>
        <!-- from project setup -->
        <application>
                <view-handler>com.sun.facelets.FaceletViewHandler</view-handler>
        </application>

        <!-- our NumberBean we just created -->
        <managed-bean>
                <managed-bean-name>NumberBean</managed-bean-name>
                <managed-bean-class>tutorial.NumberBean</managed-bean-class>
                <managed-bean-scope>session</managed-bean-scope>
                <managed-property>
                        <property-name>min</property-name>
                        <value>1</value>
                </managed-property>
                <managed-property>
                        <property-name>max</property-name>
                        <value>10</value>
                </managed-property>
        </managed-bean>

        <!-- going from guess.xhtml to response.xhtml -->
        <navigation-rule>
                <from-view-id>/guess.xhtml</from-view-id>
                <navigation-case>
                        <from-outcome>success</from-outcome>
                        <to-view-id>/response.xhtml</to-view-id>
                </navigation-case>
        </navigation-rule>

        <!-- going from response.xhtml to guess.xhtml -->
        <navigation-rule>
                <from-view-id>/response.xhtml</from-view-id>
                <navigation-case>
                        <from-outcome>success</from-outcome>
                        <to-view-id>/guess.xhtml</to-view-id>
                </navigation-case>
        </navigation-rule>

</faces-config>