Introduction to the JSF Framework

This document is the first in a series that will take you through the basics of using the JavaServer Faces framework to code web applications in NetBeans IDE. Over the series of tutorials, we will create a web application called jAstrologer that takes a user's name and birthday and returns information like the user's zodiac sign, birthstone, and horoscope.

The JavaServer Faces (JSF) framework is the standard Java API for building user interface components in web applications. Think of the JSF framework as a toolbox full of ready-to-use components that you can quickly and easily reuse in your web application. These components can be simple, like text input fields that get and store user data, to more complex components, like a formatted date field with a pop-up calendar. You embed the components into JSP pages and use the framework to handle navigation between different JSP pages.

In this section, you will learn to do the following:

• Create a web application with the JSF framework enabled.
• Create a simple JSP page that uses JSF components to get user input.
• Configure page navigation.
• Create a JSF managed bean and read and write user input to the bean's properties.

Creating a Web Application with the JSF Framework

The IDE lets you add JSF support to a web application when you create the application or add support to an existing application. The Sun Java System Application Server 9 already includes the JSF libraries so you do not need to download them or install them in the application server. In this example, we will add JSF support when creating the application.

1. Choose File > New Project (Ctrl-Shift-N), select Web Application from the Web category, and click Next.
2. Name the project jAstrologer, specify a location for the project, set the server to the Sun Java System Application Server, set the Java EE Version to Java EE 5, and click Next.
3. Select the JavaServer Faces checkbox and click Finish.

The IDE creates the web application. Expand the project's Libraries > Sun Java System Application Server node. Notice that the JSF libraries, like jsf-impl.jar, are added to the classpath. Expand Configuration Files and you will notice that the IDE has created a faces-config.xml file, which controls the behavior of JSF components in the web application. The IDE has also registered the Faces servlet in the web.xml deployment descriptor. The Faces servlet handles navigation between JSP pages that are controlled by the JSF framework.

Creating the JSP Pages

We will create a new JSP page, called greeting.jsp, that welcomes the user and collects their information. We will then create a success.jsp page that congratulates the user on registering.

Creating the Greeting Page

1. Right-click the project node and choose New > JSP. Name the file greeting, and click Finish. Make sure the JSP File (Standard Syntax) option is selected.
2. Now we need to declare the JSF tag libraries in the JSF file. Change the following code:

   <%--
   <%@taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c"%>
   --%>

   To the following:

   <%@ taglib prefix="f" uri="http://java.sun.com/jsf/core" %>
   <%@ taglib prefix="h" uri="http://java.sun.com/jsf/html" %>

   Notice that you can use the code completion to help add the tag name and attributes. The code completion can also help you add the URIs of the tab libraries.

3. Change the contents of both the title and h1 tags to Welcome to jAstrologer.
4. Now add a JSF form to the file. In the Palette, click the JSF Form button, drag it to below the h1 tag, and release the mouse button. In the dialog box, leave Empty Form selected and click OK. The IDE fills in the following code in bold:

       <h1>Welcome to jAstrologer</h1>
   
       <f:view>
           <h:form>
           </h:form>
       </f:view>
   
       </body>

5. We are going to use inputText components to get the user input and a commandButton component to submit the form. In the Source Editor, change the contents of the h:form element to the following:

       <f:view>
           <h:form>
               <p>Enter your name: <h:inputText value="name" /></p>
               <p>Enter your birthday: <h:inputText value="birthday" /></p>
               <h:commandButton value="Submit" action="submit" />
           </h:form>
       </f:view>

Creating the Success Page

Now we are going to create a page that simply says "Congratulations".

1. Create a new JSP file as described above. Name the file success.
2. Change the contents of the file to the following:

   <html>
       <head>
           <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
           <title>Congratulations</title>
       </head>
       <body>
   
       <h1>Congratulations</h1>
   
       <p>You've successfully registered with jAstrologer.</p>
   
       </body>
   </html>

   Notice that we are using plain HTML here, so there is no need to declare the JSF tag libraries yet.

Setting Page Navigation

Page navigation in the JSF framework is controlled by the faces-config.xml file, which is located under the Configuration Files node in the Projects window. For each page you set up a navigation rule which contains one or more navigation cases. For now, we will just map the submit action from the commandButton to success.jsp, so that the user sees a success message no matter what is entered in the fields.

1. Double-click faces-config.xml to open the file in the Source Editor.
2. Right-click anywhere in the file and choose Java ServerFaces > Add Navigation Rule. Type /greeting.jsp in the Rule from View field and optionally enter a description of the rule. Then click Add.

   

   The following code is entered in faces-config.xml:

       <navigation-rule>
           <description>
               handle user input
           </description>
           <from-view-id>/greeting.jsp</from-view-id>
       </navigation-rule>

3. Right-click inside faces-config.xml and choose Java ServerFaces > Add Navigation Case. Set the following:
   • From View: /greeting.jsp
   • From Outcome: submit
   • To View: /success.jsp

   

   Click Add. The IDE enters the following code in faces-config.xml:

       <navigation-rule>
           <description>
               handle user input
           </description>
           <from-view-id>/greeting.jsp</from-view-id>
           <navigation-case>
               <from-outcome>submit</from-outcome>
               <to-view-id>/success.jsp</to-view-id>
           </navigation-case>
       </navigation-rule>

Configuring and Running the Application

Now let's set the IDE to display greeting.jsp when it runs the application and, finally, test the application.

1. Right-click the project and choose Properties.
2. Click the Run node and type /faces/greeting.jsp in the Relative URL field. Then click OK.
3. Right-click the project and choose Run. The IDE builds the project, starts the application server, deploys the application, and shows the following page in the external browser:

   

   When you click the Submit button, you see the following:

   

Hooking up a Backing Bean

In the previous section we created a simple web application with JSF components. However, our web application does not really do anything interesting right now. In order to add rich functionality to your JSF web applications, you can associate your UI components with backing beans. A backing bean, also called a JSF managed bean, is a regular JavaBeans component whose bean properties and methods are available to the JSF components.

In our example, we will create a UserBean managed bean that will expose two bean properties: name and birthday.

1. Right-click the project and choose New > File/Folder. Under the Web category, select the JSF Managed Bean template and click Next.
2. Name the bean UserBean and put it in the astrologer.user package. Leave the rest of the settings at their default values and click Finish. The IDE opens UserBean.java in the Source Editor and adds the following bean declaration to faces-config.xml:

       <managed-bean>
           <managed-bean-name>UserBean</managed-bean-name>
           <managed-bean-class>astrologer.user.UserBean</managed-bean-class>
           <managed-bean-scope>request</managed-bean-scope>
       </managed-bean>

3. Add the following field declarations (shown in bold) to UserBean.java:

   public class UserBean {
   
       String name;
       String birthday;

4. Now let's generate getters and setters for the fields. Right-click anywhere in the file and choose Refactor > Encapsulate Fields. Click Next in the dialog, then Do Refactoring in the Refactoring window. The IDE switches the access level for the fields to private and creates the getter and setter methods.
5. In greeting.jsp, make the following changes shown in bold. Note that code completion is available for UserBeans.java and its properties:

       <f:view>
           <h:form>
               <p>Enter your name: <h:inputText value="#{UserBean.name}" /></p>
               <p>Enter your birthday: <h:inputText value="#{UserBean.birthday}" /></p>
               <h:commandButton value="Submit" action="submit" />
           </h:form>
       </f:view>

6. Add the JSF taglib declarations to success.jsp. You can copy and paste them from greeting.jsp.
7. Add an empty JSF form to success.jsp by clicking the JSF Form button in the Palette window and dragging and it to below the h1 tag in the Source Editor.
8. Make the following changes to success.jsp:

       <h1>Congratulations</h1>
       <f:view>
           <h:form>
               <p>You've successfully registered with jAstrologer.</p>
               <p>Your name is <h:outputText value="#{UserBean.name}" /></p>
               <p>Your birthday is <h:outputText value="#{UserBean.birthday}" /></p>
           </h:form>
       </f:view>

9. Right-click the project and choose Run Project. The same greeting.jsp page greets you when the application is deployed.

   

   When you enter values and click Submit, success.jsp also displays the values you entered, as shown in the following diagram:

   

That is all for this introductory guide to the JSF framework in web applications. You can learn more by continuing with the jAstrologer series of JSF tutorials:

• Validating and Converting User Input with the JSF Framework
• Working With Form Tags in the JSF Framework