JBoss.orgCommunity Documentation

JSF Tools Reference Guide

Version: 3.3.0.M5

1. Introduction
1.1. Key Features of JSF Tools
1.2. Other relevant resources on the topic
2. JavaServer Faces Support
2.1. Facelets Support
2.1.1. Creating a JSF project with Facelets
2.1.2. Facelets components
2.1.3. Code assist for Facelets
2.1.4. Open On feature
3. Projects
3.1. Creating a New JSF Project
3.2. Importing Existing JSF Projects with Any Structure
3.3. Adding JSF Capability to Any Existing Project
3.4. Adding Your Own Project Templates
3.5. Relevant Resources Links
4. Web.xml Editor
5. JSF Configuration File Editor
5.1. Diagram view
5.2. Tree View
5.3. Source View
5.4. Editor Features
5.4.1. Open On
5.4.2. Code Assist
5.4.3. Error Reporting
6. Managed Beans
6.1. Code Generation for Managed Beans
6.2. Add Existing Java Beans to a JSF Configuration File
7. Creation and Registration
7.1. Create and Register a Custom Converter
7.2. Create and Register a Custom Validator
7.3. Create and Register Referenced Beans
8. JSF Project Verification

JSF Tools are especially designed to support JSF and JSF-related technologies. JSF Tools provide extensible tools for building JSF-based applications as well as adding JSF capabilities to existing web projects, importing JSF projects and choosing any JSF implementation while developing JSF application.

This guide provides the information on JSF tooling you need to allow you to quickly develop JSF applications with far fewer errors.

JSF Tools does not lock you into any one JavaServer Faces implementation. You can always specify the desired JavaServer Faces implementation while creating a new JSF project (see Section 3.1, “Creating a New JSF Project”), adding JSF capability to any existing Eclipse project (see Section 3.3, “Adding JSF Capability to Any Existing Project”), or importing existing JSF projects (see Section 3.2, “Importing Existing JSF Projects with Any Structure”).

At this point the special wizard will prompt you to specify an appropriate JSF environment. It may be JSF 1.1.02 RI, JSF 1.2 or JSF 2.0. The wizard also lets you select JSF implementation with a component orientation such as JSF 1.2 with Facelets or MyFaces 1.1.4.

After specifying an appropriate JSF environment, all the required libraries associated with the selected version will be added to your project.

In this section we will focus all the concepts that relate to working with Facelets.

Facelets extend JavaServer Faces by providing a lightweight framework that radically simplifies the design of JSF presentation pages. Facelets can be used in a variety of ways that we will consider further in this section.

To take an advantage of JSF you will need to perform one of the next steps:

  • Create new JSF projects

  • Import (open) existing JSF projects

  • Add JSF capability to any existing Eclipse project

  • Import and add JSF capability to any existing project created outside Eclipse.

This section will go into more detail for each step.

It is easy to create a new project that contains all the JSF libraries, tag libraries and JSF configuration file with the aid of a special wizard. To get it, select FileNewOtherJBoos Tools WebJSFJSF Project and click the Next button.

On the next page you will be prompted to enter the Project Name and select a location for the project (or just leave a default path).

The JSF Version option also allows you to specify the JSF implementation to use.

There are a number of predefined project templates that are both flexible and easily customizable. You can pick a different template on which the projects Importing Existing should be based on. Almost all templates come in two variations: with and without JSF libraries.

The table below provides description for each possible JSF template.

On the next page you need to select which Servlet version to use, and specify whether or not to register this application with JBoss AS (or other server) in order to run and test your application.

The Context Path option defines the name under which the application will be deployed.

The Runtime value tells Eclipse where to find the Web libraries necessary to build (compile) the project. It is not possible to finish the project creation without selecting a Runtime. If you do not have any values, click the New... button to add new Runtime.

The Target Server option allows you specifying whether or not to deploy the application. The Target Server corresponds to the Runtime value selected above. If you do not want to deploy the application, uncheck this option.

When you are all done, you should see that the project has appeared in the Package Explorer view:

At this point you can open the faces-config.xml file and start working on your application. There are a lot of features available when developing JSF applications. These features will be discussed in more detail later in this document.

A template is a set of files that is provided as a basis when creating a new project. Project templates provide content and structure for a project.

JSF Tools provides powerful template capabilities which allow you to create new templates and import existing Struts and JSF projects. This templating facility has a variety of aspects to consider. Let's start with the most straightforward case and consider the process of creating a template from your existing JSF project.

Let's say you have a project that you want to use as the basis for a new template. The following steps will show you how to achieve this:

  • In the first dialog box, you can specify a name for the template (it will default to the project name) and confirm what run-time implementation of the project technology will be used.

  • When you click the Next button a dialog box will be presented with your project structure displayed, along with a number of check boxes. Here you can select only those parts and files in your project directory that should be part of the template.

  • At this point, unless you want to designate some extra files as having Velocity template coding inside them, you should click the Finish button.

That's it. This template can be used with any new or imported project that uses the same run-time implementation as the project you turned into a template.

At this point you have a fully configured project. Now you can add some additional logic to it starting with the JSF configuration file.

The web.xml file inside the WEB-INF folder is a deployment descriptor file for a Web Application. It describes the servlets and other components and deployment properties that make up your application.

JBoss Tools add the web.xml file to created JSF project automatically and provides a special editor for its editing. See the Visual Web Tools guide for more information on the web.xml editor.

First, we should mention that JSF configuration file (faces-config.xml) is intended for registering JSF application resources such as Converters, Validators, Managed Beans and page-to-page navigation rules.

Now, let's look at how you can easily configure this file by means of a special graphical editor for the JSF configuration file. The editor has three main views:

  • Diagram

  • Tree

  • Source

They can be selected via the tabs at the bottom of the editor.

You can find it more convenient to edit your JSF Configuration file in the Tree view of the VPE.

The view displays all JSF application artifacts referenced in the configuration file in a tree format. By selecting any node on the left, you can view and edit its properties which will appear in the right-hand area. Let's look at the structure of this tree more closely.

  • The Components node is for registering custom JSF components. Right-click and select NewComponent or just click the Add button in the right-hand area to add a new component to the JSF Configuration file.

In the Add Component wizard you should set a component type and point to a component class by using the Browse button or create a new class for this component by using the Component-Class link.

  • Use the Render Kit node to create and register a set of related renderers for custom JSF components.

  • Use the Navigation Rules node to configure a navigation between the pages in your application. Here you can create a new navigation rule and adjust necessary properties for it in the right-hand area.

  • The Extensions node is for setting extensions in your faces-config.xml file.

In the Tree view you can also edit the properties of the selected element with the help of the Properties view as shown below:

JSF Tools provides a number of useful features when working with managed beans, such as:

  • Adding and generating code for new managed beans

    • Generating code for attributes and getter/setter methods

  • Adding existing managed beans to a JSF configuration file

This guide will look at each of these features in more detail.

In this chapter we'll discuss a possible verification that you can take advantage of.

Many different rules are checked for a JSF project that can be configured by selecting WindowPreferences from the menu bar, selecting JBoss ToolsWebJSFValidation.

Suppose you are working in the Source viewer for a JSF configuration file as shown below:

While typing a class name, you might make a minor typo (like "demo.Person9" instead of "demo.Person" ). After saving the file, verification checks to make sure everything is correct and finds the error below:

Notice that the Package Explorer View shows a marked folder and a marked file where the error is.

You can place the cursor over the line with an error message and get a detailed error message:

Verification also checks navigation rules:

If you provide a page name that does not exist, verification will let you know about that:

In summary, this document highlights all the JSF-specific features of JBoss Tools meant for enhancing the development of rich Web applications based on JSF technology. The reference introduces you to wizards for creating and importing JSF projects, JSF Configuration File editor features, functionality for enabling JSF capabilities and etc.