Installing the Facelets Support Module

Before you begin, you need to install the NBM files that constitute the Facelets Support Module for NetBeans IDE. There are different versions of the NBMs for NetBeans IDE 6.1 FCS, build 200804211638 (download) and for NetBeans IDE 6.1 ML (Multilingual), build 200805300101 (download). After you download and unzip the ZIP file, you will have a set of NetBeans module (NBM) files.

The NBM files for the ML release are available as a plugin from the NetBeans IDE 6.1 Beta Update Center. To download and install the plugin, go to Tools > Plugins and browse for Facelets Support in the Available Plugins tab.

To install the unzipped NMB files:

1. Start the IDE and go to Tools > Plugins.
2. Open the Downloaded tab and click Add Plugins. The Add Plugins dialog opens.
3. Browse for the unzipped NBM files. Select all the files and click Open. The Add Plugins dialog closes and the NBM files appear in the Downloaded tab.
4. Click Install. You will be warned that the plugins are not signed, but continue installing them.

The facelets plugin on the Update Center and the plugins linked from this tutorial cannot be installed if you have installed the latest update to the JSP Parser (org-netbeans-modules-web-jspparser.jar). If you try to install the plugin, you will get an error message stating which version of the JSP Parser you need. Please see the engineer's blog for suggested workarounds. This problem will be solved in NetBeans IDE 6.5.

Directory Structure and Project Setup

The source structure of your 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 you are using an IDE, you shouldn't need to create all these files by hand. Instead, you have a wizard to do the work for you. Specifically, the final panel of the Web Application wizard will be very useful in the context of your 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 GlassFish v2 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):

   

Without any programming whatsoever, you can already run your application. Right-click the project node and choose Run. 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

This section refers to The NumberBean section in the Facelets Developer Documentation. You create a JavaBean as a controller for your 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 your 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;
     }
   
     // your 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 Web Pages > WEB-INF node and open the faces-config.xml file. Open the XML view of the file. Right-click in the file and choose JavaServer Faces > Add Managed Bean, as shown below:
   
3. In the Add Managed Bean dialog, type NumberBean for the Bean Name and tutorial.NumberBean for the Bean Class. Select "session" from the Scope drop-down menu. Click Add when done.
   

   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, you 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 > Other and then choose Facelets Template from the Java Server Faces category. Click Next. The New Facelets Template wizard opens.
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, or type "web." Accept the other default settings and click Finish.

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

   <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   <html xmlns="http://www.w3.org/1999/xhtml"
         xmlns:ui="http://java.sun.com/jsf/facelets"
         xmlns:h="http://java.sun.com/jsf/html">
       <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, you refer to the Handling Navigation section in the Facelets Developer Documentation. Here, you need to connect your pages together, via the faces-config.xml file.

1. Right-click inside the faces-config.xml file and choose Java Server Faces > Add Navigation Case. The Add Navigation Case dialog opens.
2. In the From View field, browse to template-client.xhtml. In the To View field, browse to response.xhtml. Type "success" in the From Outcome field. Click Add when done.
   

   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>

3. Right-click inside the faces-config.xml file and again choose Add Navigation Case. This time, in the From View field, browse to response.xhtml. In the To View field, browse to template-client.xhtml. Type "success" in the From Outcome field. Click Add when done.
   

   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>

4. Hold down the Ctrl key and move the mouse over a reference to one of the documents in your application as shown below. Note 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, you refer to the Deployment section in the Facelets Developer Documentation. Deployment of your application means that you 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:
   

   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.

   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. For details, see http://nbfaceletssupport.dev.java.net/.

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