Creating custom JavaServer Faces components in IBM Rational Application Developer Version 7.5

This article explains how you can use IBM® Rational® Application Developer V7.5 to create custom Java™Server Faces (JSF) components.


Yury Kats (, Advisory Software Engineer, IBM

Yury Kats photoYury Kats is a developer in the IBM Rational Application Developer team, working on JSF implementation, components, and tooling.

06 January 2009

Also available in Chinese Japanese Vietnamese

JSF components: what they are and who needs them

One of the strengths of the JSF framework is its component-based architecture. Components are the building blocks of any Web application built using JSF technology: they do all of the following:

  • Control UI rendering in the client
  • Control binding of UI widgets to the backend data
  • Control how request parameters are processed during postback to the server
  • Control how submitted values are converted and validated
  • Fire events in response to a user action
  • And so on

The JSF specification and its implementations offer a number of basic components that you (as an application developer) can use right away: a few input components (such as inputText), a few output components (such as outputText), a data table, a couple of layout panels (such as panelGrid), a button, a link, and an image.

It is possible to build a functional Web application using these components provided by the core JSF implementation. However, there are limitations to this component set. When you design modern Web applications, you strive to provide your users with a rich experience that calls for more complex components than what the JSF specification provides. You need components such as menus, rich text editors, file uploads, and calendars: functionality that users expect.

Luckily, JSF architecture is flexible, and it allows you to create your own components in addition to those that the JSF implementation provides. Therefore, developers created JSF component libraries to respond to the demands of other application developers. There are several great and popular component libraries in the market today, including the following:

  • IBM’s JSF Widget Library (JWL)
  • MyFaces’ Tomahawk
  • Trinidad and Tobago
  • JBOSS’s RichFaces
  • ICEFaces
  • And many more

However, as mighty as these libraries are, none of them can satisfy every developer. You might need a particular JSF component that does not exist in the library of your choice.

If so, you have probably thought to yourself, "should I build the component myself?"

In many cases, the answer is "yes." Building a custom JSF component is often the right thing to do. A custom component lets you encapsulate a lot of functionality in one JSF tag. You can then re-use that tag in many pages and applications, and share it with other developers in your organization. It also simplifies maintenance, because the functionality is kept in one place instead of being spread over many pages in your applications.

Imagine, for example, that your application needs to collect information about a user’s address. Very likely you need to do this more than once: you might be interested in the user’s home address, business address, shipping address, and billing address. You looked at all of the popular component libraries, and none of them had a component to handle addresses. So you use standard JSF components and quickly build an address form out of various input and output fields (Figure 1).

Figure 1. Address block
street, city, state, and zip code fields

Because you need such an address block on more than one page, you repeat it on various pages, and maybe even in different applications. Are your pages going to work correctly? Yes. Is this a lot of similar code to be repeated over and over? Sure. Is it a maintenance nightmare? Absolutely. What if a week later you needed to re-align the fields or to add another field for the country? You would need to make the change on every single page where you created this address block!

It would be much more convenient if instead you create your own component that wraps this entire block, and then use a single tag such as <my:inputAddress value="#{address}" /> everywhere. Your JSP source would be much shorter and clearer, and if you ever needed to change the address block, you would only need to do it in one place. You can also share your inputAddress component with your colleagues or online community, so that everybody who needs such a component can benefit from your work.

By now it should be clear that creating a custom component is a good thing, but what is the best way to create one? While JSF specification makes it possible to create new components, it does not make it particularly simple. If you want to create a component, you need to create three Java classes:

  • A component class
  • A renderer class
  • A tag handler class.

In addition to those classes, the information about the new component should be provided in a faces-config.xml file and in a tag library file. This is a tedious and error-prone job.

This is why Rational Application Developer V7.5 has a new feature to help JSF developers create custom components quickly and easily. As a component author, you can use familiar Rational Application Developer tools (such as drag-and-drop from the palette, WYSIWYG editor, Properties, and PageData views), and Rational Application Developer automatically creates all of the required Java classes and configuration files for you.

Of course, if you are an advanced user, you can still tweak the generated Java classes themselves to achieve even more power and flexibility. However, you do not need knowledge of the internal JSF architecture in order to create components in Rational Application Developer.

To demonstrate this new feature, you will create a simple custom JSF component for a very common case such as an input field with a label, as shown in Listing 1.

Listing 1. Input field with a label
	<h:outputText value=”Name:” / >
	<h:inputText value=”#{}” />

Such a pair can be found in pretty much any JSF application. Even the address block shown previously in Figure 1 has it three times. You will wrap these two tags into a single usable component, as shown in Listing 2.

Listing 2. Usable component
	<my:inputLabel value=”#{}” label=”Name:” />

Creating a custom JSF component

JSF components rarely exist independently. Instead, they are part of a component library, which is a collection of components that you can drop into any application, re-use, and share. A library is usually a single Java™ archive (JAR) file that contains a number of components, and all of the configuration files required for the library to be used. IBM’s JWL, MyFaces’ Tomahawk, and JBOSS’s RichFaces are examples of component libraries.

Therefore, to create a custom component, you first need to create a component library.

Creating a component library

To create a component library:

  1. Select File > New > Project.
  2. Under the Web category, select Faces Component Library Project.
  3. Click Next.

The New Faces Component Library wizard opens. Notice that it looks very much like the wizard you would use to create a new Web Project. The only difference is that the Configuration field is set to Faces Component Library, as shown in Figure 2. The entire custom JSF components tooling in Rational Application Developer was designed to be very similar to the standard Web and JSF tooling that you are already familiar with, so that your learning curve is minimal.

Figure 2. New Faces Component Library wizard
arrow pointing to selected Configuration
  1. Enter a name for your library (in this example, MyComponents) and click Finish.
  2. As an advanced user, you might want to click the Next button three times before hitting Finish. This allows you to tweak a couple of library settings, such as its URI, prefix, and the package name for the generated Java classes as shown in Figure 3.
Figure 3. Component Library settings dialog
dialog to configure component library

Creating a component

  1. With the Library project created, right-click the project’s name in the Enterprise Explorer view and select New > Faces Custom Component.

A New Custom Component wizard opens. Notice again, that the wizard is almost the same as if you were creating a regular Web page. The only difference is a special template that you select to identify the page as a Custom Faces Component, as shown in Figure 4.

Figure 4. New custom component
arrow pointing to template, preview on right
  1. Enter a name for the new component (in this example, inputLabel) and click Finish.

After you click Finish, Rational Application Developer will create a JSP file to enable you to design the component and open it in the editor. Notice that this is just a regular JSP file, and that all of the familiar Rational Application Developer tools are available to you when you work with it:

  • Palette
  • Properties
  • QuickEdit
  • PageData views

However, unlike the regular JSF page, the custom component does not have <BODY> or <f:view> tags. Instead, it uses a special <jsfc:component> tag that will contain other JSF tags that would constitute your custom component.

Examine your library project in the Enterprise Explorer view. Note that in addition to the component JSP file that you just created, Rational Application Developer generated a number of other files in the library, as shown in Figure 5.

Figure 5. Generated files
MyComponents expanded in tree view

Generated files include the following:

  1. Component class (
  2. JSP tag handler (
  3. Renderer class (
  4. Configuration files: faces-config and tag library (faces-config.xml)
  5. Library JAR file that contains all component artifacts (MyComponents.jar)
  6. Test page for the component (testInputLabel.jsp)

Whenever you make a change to the JSP file containing the component definition (inputLabel.jsp in this case), Rational Application Developer automatically regenerates all of the other files needed to the component library to function. It then packages them into a single JAR file. This JAR file effectively becomes your component library, which you can later use in other projects and share with others. Rational Application Developer also generates a test page for you to see how the custom component will behave when it is deployed to the server.

Configuring a Component

Now that you have created a new component, it is time to configure its attributes and properties.

  1. Go back to the component definition page (inputLabel.jsp) that is open in the editor, and then select the <jsfc:component> tag (either by clicking the tag in the Source view, or by clicking within the dashed rectangle in the Design view).

You can now configure this new component using the Properties view, as shown in Figure 6.

Figure 6. Component properties
specify name, attributes, description and behavior
  1. Using the Properties view, you can configure:
    • The Tag name for the component. By default, the tag name matches the name of the JSP that you created, but the two do not have to be same.
    • The component Description. The description should be helpful to other users of your component (if you decide to share it with others).
    • Specify what the Component behaves as. The JSF specification defines a few standard components that you might want your component to be similar to in behavior. In addition to Basic JSF component, options include an Input component, a Multi-Select component, and a Command component. When you select one of these options, Rational Application Developer will automatically generate attributes typical to the selected component type, and generate code in the component class to support selected behavior.
    • The component Attributes.
    • Lastly, you can instruct Rational Application Developer as follows: Do not overwrite generated Java classes when this JSP changes. This option is helpful to advanced users who, once the component class is generated, choose to manually adjust the class. In this case, you want to separate the component definition in the JSP from the component’s Java source.

For your inputLabel component, configure it to behave as an Input component and add two attributes: label and value.

  1. To add an attribute, click the Add button in the Properties view and enter the attribute Name and Class, as shown in Figure 7. Both attributes you add will be of Class java.lang.String.
Figure 7. Adding an attribute
Define component attribute dialog

Once configured, the Properties view for the inputLabel component should look like that shown in Figure 8.

Figure 8. Configured component
component property details

Notice that because you made the component behave as an Input component, Rational Application Developer automatically added immediate, required, and valueChangeListener attributes that are typical for Input components.

Creating component content

Now it is time to define the actual content of this inputLabel component. As you remember, you want it to be an outputText showing a label, followed by an inputText showing a value.

  1. From the Palette, drag an Output and an Input component onto the page.
  2. From the PageData view, bind the Output component to the label attribute, and the Input component to the value attribute, by dragging those attributes on top of the components in Design view, as shown in Figure 9.
Figure 9. Creating component content
explorer left, design page middle, palette right

Notice that the attributes of the custom component that you configured in the Properties view are also listed in the PageData view under the Faces component category.

When you bind a component attribute to another component, a special JSF expression is generated to access this attribute at runtime: #{component.attribute}, as shown in Figure 10.

Figure 10. Component source
code showing binding a component attribute to another component

What this means, is that if you later use the component as, for example, <my:inputLabel value=”#{}” label=”Name:” />, then the value of the outputText will become “Name:” and the value of the inputText will become #{}.

This is all you need to do to define the content of the new component. Once you save the page, Rational Application Developer will update all of the required artifacts, and the component library will be ready to be used.

Testing the component

Now that you have created a new component, you want to test how it behaves when run on a server, before using it in a real application or sharing it with others. For this purpose, Rational Application Developer has created a test page: testInputLabel.jsp. The test page is a regular JSP that contains the new component tag, and therefore you can deploy it to a server to see the new component in action.

  1. Open testInputLabel.jsp file. Notice that the source of this page contains a single <m:inputLabel> tag, yet the Design view shows the outputText and the inputText that the new component contains (see Figure 11). The Properties view lists all of the inputLabel component attributes (including label and value that you added earlier). The QuickEdit shows a Value Changed event, because you configured the new component to behave as an Input.
Figure 11. Component test page
page with multiple frames and tabs
  1. Using the Properties view, enter something for the label and value attributes, save the page and run it on the server.

Once the browser opens, you will see a label followed by an input field, both showing the values specified in the component’s attributes (Figure 12).

Figure 12. Run on server
Name shows Yury

You have now created a fully functional new JSF component using Rational Application Developer’s tooling.

Using custom components in Web applications

You now have a brand new JSF component library that you can use in your Web applications or share with your co-workers.

Rational Application Developer automatically packaged everything that belongs to your component library into a single JAR file that you can use yourself and distribute to others. To make full use of Rational Application Developer’s tooling features, however, you need to create a library definition for your library. For a brief description of Rational Application Developer’s support for custom component libraries, see the Resources section.

Creating a library definition

To create a library definition for the library that you just created:

  1. Right-click your library project (MyComponents) in the Enterprise Explorer view.
  2. Select New > Faces Library Definition.
  3. In the Create Faces Library Definition wizard that opens (Figure 13)
    1. Enter a library name (for example, MyLibrary).
    2. Notice that your library project is already pre-selected.
    3. Click Finish.
Figure 13. Library definition
enter name, select JAR, specify Faces project

After Rational Application Developer finishes processing your library, the editor opens. In it, you can customize all aspects of the tooling support for your new library and components:

  • What is shown on the Palette
  • How components are visualized
  • What happens during drag-and-drop operations
  • And much more
  1. Customizing a library definition goes beyond the scope of this article, so you can just accept what Rational Application Developer created for the definition. Close the editor.

Now that the Library Definition is created, you can start using the new library in regular Web projects, or you can share the Library Definition project (MyLibrary) with others.

Using the custom component in a Web application

  1. Create a new Dynamic Web project using the Faces project configuration, and then create a new Web page in it.

When the page opens in the editor, you will see that the new component library and the new component you created are available on the Palette, next to all of the regular Rational Application Developer palette drawers, as shown in Figure 14.

Figure 14. Palette
inputLabel under MyLibrary
  1. Drag the inputLabel component from the Palette onto your page. Because this is the first time that you are using the new library in this Web project, the JAR file containing your custom component needs to be copied into the project.
  2. Rational Application Developer will prompt you to confirm this. Click OK to confirm.

As with the test page earlier, you will see that an <m:inputLabel> tag was added to the source of the Web page. The tag is visualized in the Design view as a pair of outputText and inputText components, as shown previously in Figure 11. The tag’s attributes are available in the Properties view, and a Value Changed event can be scripted in the QuickEdit view.

  1. Run the page on the server, and you will see the component renderer in the browser, as shown previously in Figure 12.

You have successfully used your own custom JSF component in a Web project.


Sample projects and componentsSampleProjects.zip9412KB



Get products and technologies



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Rational software on developerWorks

Zone=Rational, Open source, Agile transformation
ArticleTitle=Creating custom JavaServer Faces components in IBM Rational Application Developer Version 7.5