Installing the Software

Before you begin, you need to install the following software on your computer:

• Java Standard Development Kit (JDK™) version 1.4.2 (download) or 5.0 (download)
• NetBeans IDE 5.5 or above. (This tutorial was written and tested under NetBeans IDE 5.5.)
• The NBM files that constitute the Facelets Support Module for NetBeans IDE (download)

  After downloading and unzipping the ZIP file, you will have a set of NetBeans module (NBM) files. Next, use the Update Center wizard under the Tools menu to install them in the IDE. Choose "Install Manually Downloaded Modules (.nbm Files)" in the first page of the Update Center wizard, browse to the downloaded NBM files, and complete the wizard.

Directory Structure and Project Setup

The source structure of our application must include the Facelets JAR files, the registration of the Facelets servlet in the web.xml file, as well as some standard artifacts such as the home page. Since we are using an IDE, we shouldn't need to create all these files by hand. Instead, we have a wizard to do the work for us. Specifically, the final panel of the Web Application wizard will be very useful in the context of our Facelets application.

1. Choose File > New Project. Under Categories, select Web. Under Projects, select Web Application. Click Next.
2. In the Name and Location panel, type NumberGuess in Project Name. Change the Project Location to any directory on your computer.

3. Make sure that you select the Sun Java System Application Server in the Server drop-down list.

4. Leave all the other settings unchanged. Or, if you like, you can change them. Facelets supports J2EE 1.4 as well as Java EE 5. Click Next.

5. In the Frameworks panel, choose Facelets. You will see the following options:

   The fields in the Configuration panel above provide the following:

   • Debug. Specifies that the FaceletViewHandler will print out debug information in an easy to use screen, whenever an error occurs during the rendering process.
   • Create Example Facelets Files. Specifies that two Facelets template files will be created when Finish is clicked.
   • Skip Comments. Tells the compiler to skip comments, which is true by default. Even if you comment out code in your page, the tags will not be compiled but expressions (EL) will be treated as if they were inlined and are still compiled and evaluated for output in the document. Skipping comments will remove all comments completely from the document.
   • Faces Suffix. Displays the suffix that will be used for Facelets files.
   • Faces Servlet Mapping. Displays the servlet mapping as it will appear in the web.xml file.

   The fields in the Libraries panel above provide the following:

   • Registered Libraries. Specifies that a specific library, registered in the Library Manager, will be put on the application's classpath by the wizatd.
   • Create New Library. Lets you browse to a folder containing the Facelets JAR files.
   • Don't append any new library. Specifies that no JAR files will be added to the application's classpath by the wizard. As a result, you will need to attach JAR files to the classpath yourself, after the source structure is created, by using the Library Manager.

6. Leave all the defaults unchanged. Click Finish.

   The IDE creates the NumberGuess project. The project contains all of your sources and project metadata, such as the project's Ant build script. The project opens in the IDE. You can view its logical structure in the Projects window (Ctrl-1):

7. Without any programming whatsoever, you can already run your application. Right-click the project node and choose Run Project. The server starts, if it is not running already, and the application is deployed. The IDE's default browser starts up, showing you the overview page.

The NumberBean

In this section, we refer to the The NumberBean section in the Facelets Developer Documentation. We create a JavaBean as a controller for our application, copied from the Facelets Developer Documentation.

1. Create a Java source file called NumberBean.java in a package called tutorial. Replace the content with the following; to understand the code below, read the comments that are embedded within it:

   package tutorial;
   import java.io.Serializable;
   import java.util.Random;
   import javax.faces.application.FacesMessage;
   import javax.faces.component.UIComponent;
   import javax.faces.context.FacesContext;
   import javax.faces.validator.ValidatorException;
   public class NumberBean implements Serializable {
     protected final static Random rand = new Random();
     protected int min;
     protected int max;
     protected int guess;
     protected int actual;
     // Default Constructor:
     public NumberBean() {
       this.min = 1;
       this.max = 10;
     }
     // called by JSF to validate user input:
     public void validate(FacesContext context, UIComponent component, Object value)
         throws ValidatorException {
       // coerce the value to an int:
       try {
         int param = Integer.parseInt(value.toString());
         // validate param:
         if (param > this.max || param < this.min) {
             FacesMessage msg = new FacesMessage("Guess must be between "+this.min+" and "+this.max);
             throw new ValidatorException(msg);
         }
       } catch (NumberFormatException e) {
         FacesMessage msg = new FacesMessage("Must be a number");
         throw new ValidatorException(msg);
       }
     }
     // lazy generate our actual value:
     public synchronized int getActual() {
       if (this.actual == 0) {
           this.actual = rand.nextInt(this.max-this.min);
           this.actual += this.min;
       }
       return this.actual;
     }
     // our message for the response:
     public String getMessage() {
       if (this.guess == this.getActual()) {
         return "Sweet, you got it right!";
       } else if (this.guess < this.getActual()) {
         return "Sorry, try something higher";
       } else {
         return "Too bad, go lower";
       }
     }
     // other bean properties:
     public int getMin() { return this.min; }
     public int getMax() { return this.max; }
     public int getGuess() { return this.guess; }
     public void setMin(int min) { this.min = min; }
     public void setMax(int max) { this.max = max; }
     public void setGuess(int guess) { this.guess = guess; }
   }

2. Expand the Configuration Files node and open the faces-config.xml file. Right-click in the file and choose JavaServer Faces > Add Managed Bean, as shown below:

3. Next, fill the following values in the dialog box:

   When you complete the wizard, you should see the following entries added to the faces-config.xml file:

   <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-bean>

Creating Web Pages

In this section, we refer to the Creating Web Pages section in the Facelets Developer Documentation.

1. In the template-client.xhtml file, replace the <ui:composition> section with the following:

   <ui:composition template="/template.xhtml">
       This text will not be displayed.
       <ui:define name="title">
           I'm thinking of a number from #{NumberBean.min} to #{NumberBean.max}.  Can you guess it?
       </ui:define>
       This text will also not be displayed.
       <ui:define name="body">
           <h:form id="helloForm">
               <h:inputText type="text" id="userNo" value="#{NumberBean.guess}" validator="#{NumberBean.validate}"/>
               <br/>
               <h:commandButton type="submit" id="submit" action="success" value="Submit" />
               <br/>
               <h:message showSummary="true" showDetail="false" style="color: red; font-weight: bold;" id="errors1" for="userNo"/>
           </h:form>
       </ui:define>
       This text will not be displayed.
   </ui:composition>

2. Right-click the project, choose New > File/Folder and then choose Facelets Template from the Web category. Click Next.

3. In the Name and Location panel, notice that you can select a layout style for your template, as shown below:

4. Name the template response. In the Folder field, browse to the web folder. Accept the other default setting and click Finish.

5. Replace the default content of response.xhtml with the following:

   <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
       <body>
           <ui:composition template="/template.xhtml">
               <ui:define name="title">
                   #{NumberBean.message}
               </ui:define>
               <ui:define name="body">
                   <form jsfc="h:form">
                       <input jsfc="h:commandButton" type="submit" id="back" value="Back" action="success"/>
                   </form>
               </ui:define>
           </ui:composition>
       </body>
   </html>

Handling Navigation

In this section, we refer to the Handling Navigation section in the Facelets Developer Documentation. Here, we need to connect our pages together, via the faces-config.xml file.

1. Right-click inside the faces-config.xml file and choose Add Navigation Case. Define the case as follows:

   When you complete the dialog box, you should see the following in the editor:

   <navigation-rule>
       <from-view-id>/template-client.xhtml</from-view-id>
       <navigation-case>
           <from-outcome>success</from-outcome>
           <to-view-id>/response.xhtml</to-view-id>
       </navigation-case>
   </navigation-rule>

2. Right-click inside the faces-config.xml file and choose Add Navigation Case. Define the case as follows:

   When you complete the dialog box, you should see the following in the editor:

   <navigation-rule>
       <from-view-id>/response.xhtml</from-view-id>
       <navigation-case>
           <from-outcome>success</from-outcome>
           <to-view-id>/template-client.xhtml</to-view-id>
       </navigation-case>
   </navigation-rule>

3. Hold down the Ctrl key and move the mouse over a reference to one of the documents in your application as shown below, while noticing that the reference to the document becomes a hyperlink:

   When you click the hyperlink, the referenced document opens in the Source Editor, so that you can begin editing it without needing to look for it.

Deployment

In this section, we refer to the Deployment section in the Facelets Developer Documentation. Deployment of our application means that we want to make it available to the server, that the server should start if it is not already running, and that the web browser should open to display the web application's welcome page.

1. At this stage, your project should look as shown in the screenshot below:

   Note: In the screenshot above, the highlighted files are the only ones added to the original generated project structure.

2. Right-click the project and choose Run Project.

   The application is built, the server starts, if it is not already running, the application is deployed to the server, and the browser specified in the IDE opens, displaying the link to the Facelets Example Page. Click it and you should see the application's client page, as shown at the start of this document:

Next Steps

This is the end of the introduction to web development using Facelets in NetBeans IDE. Note that the Facelets Support Module offers a lot more functionality than is described here.

You are encouraged to continue your journey in the Facelets framework by working through other tutorials described on the Facelets Home Page.