Faces library definitions for third-party JavaServer Faces controls

This article describes the new Faces Library Definition feature in IBM Rational Application Developer Version 7.5. With this feature, you can import an arbitrary third-party JSF (JavaServer Faces) component library and fine-tune the behavior of the JSF tools when you work with that library's UI components.



Java™Server Faces (JSF) technology is a popular Java™ framework for Web user interface components. IBM® Rational® Application Developer has included robust tools for developing JSF Web applications for the past several releases. Version 7.5 introduces new functionality for you (as a developer) to import and use arbitrary third-party JSF components with minimal effort. This article discusses the process of consuming a third-party component library, configuring metadata for the library, and sharing the resulting configuration for reuse across a development team.

Before we begin, let's expand on what it means to support third-party components in the development environment. If you have some new third-party JSF controls (either created from scratch or downloaded from the Web), what can you expect to be able to do?

  • The new components need to be available on the palette so that they can be dragged onto a page in the Java™ Server Pages (JSP™) editor.
  • When a component library is first added to a Web project, the appropriate resources need to be added into the project, and any necessary configuration steps should be performed to make the library usable.
  • There needs to be a way to see and configure the UI components after they've been added to Web pages.
  • You will also want control over a number of other details of both UI appearance and behavior.

All of the functionality just mentioned is already directly provided for the standard JSF controls and the IBM-supplied JavaServer Faces widget library (JWL) component libraries. You will now see how to expand this support to other JSF component libraries. This article demonstrates the new functionality using open-source MyFaces Tomahawk components as an example, but this same process applies to any valid JSF component library.

Creating a Faces Library Definition

Rational Application Developer V7.5 introduces the concept of a sharable configuration for third-party component libraries. You will create a Faces Library Definition (JLD), which is basically a configuration file plus any other file resources that the library needs. These files are all stored in a special type of workspace project called a Faces Definitions Project.

To follow along with this example, first download the Tomahawk component Java™ archive (JAR) file from the Apache MyFaces Web site (http://myfaces.apache.org/download.html), which is used as a representative third-party component library.

Start by creating a Faces Definition Project to contain the library's configuration metadata.

  1. Launch the wizard by selecting File > New > Project (you can find it under the Web category).
  2. The only thing to do in the wizard is to give the project a name (in this case, MyFaces Components), as shown in Figure 1.
Figure 1. Create a Faces Definitions Project
dialog with text entry field

Next, create a library definition for the Tomahawk library and examine its elements.

  1. Right-click the new project that you just created and select New > Faces Library Definition.
  2. Give the new definition a name (for example, tomahawk).
  3. Click the browse button next to the Jar file field. Select the location of the JAR file that you downloaded earlier from the Apache site, as shown in Figure 2.
  4. Click Finish.
Figure 2. Create a new Faces Library Definition
dialog to specify name, file, and project

After a short time spent analyzing the Tomahawk JAR file and generating files, the wizard will complete and open the new JLD configuration file (tomahawk.jld). You will look much more closely at this editor in the next sections, but for now just notice that the file contains information for configuring a Web application, and an item for each tag in the tag library.

Merely by having this library definition and its containing project in your workspace, you've already succeeded in making the tools aware of Tomahawk components. Next, explore how the tool uses this configuration and look at ways it can be fine-tuned.

Setting up a JSF Web project

Now you will create a JSF Web project to see how the new component library integrates with the JSF tools.

  1. Launch the project wizard by selecting File > New > Project > Dynamic Web Project.
  2. Supply a project name.
  3. In the Configuration dropdown, choose JavaServer Faces v1.1 Project.
  4. Click Finish.

Notice here that you selected the JavaServer Faces configuration, which is a subset of the more usual Faces Project configuration. This is because the Faces Project preset also includes the IBM JWL component library, which you probably would not be using in conjunction with third-party libraries. In general, you should use the more basic JSF configuration when you are including third-party components in your project.

Figure 3. Create a test Web project
Dialog to create a project or add it to an application

Next create a JSP page in this test project.

  1. Right-click the project name in the Enterprise Explorer.
  2. Select New > Web Page.
  3. Enter a name for the JSP in the wizard, as shown in Figure 4.
  4. Click Finish.
Figure 4. Create a test Web page
tree view on left, preview on right

Exploring a basic third-party component integration

  1. When the test page you just created opens in the editor, look at the palette view and notice the new tomahawk drawer, as shown in Figure 5. (Generally, you will find third-party component libraries at the bottom of the palette).
Figure 5. Palette with third-party components
open drawer with set of components

The drawer with Tomahawk components is displayed because the Faces Library Definition that you created previously is present in the workspace.

  1. Try closing the project that holds the definition (MyFaces Components) and notice that the palette drawer promptly disappears. Then reopen the project to bring the drawer back.
  2. Now drag the Tomahawk commandButton component from the palette into the test JSP. A prompt will appear asking to copy new project resources.
  3. Click OK to allow the tool to add Tomahawk into the test project (notice that the button tag was also added into the page).
  4. Using the Enterprise Explorer, look in the test project under the path /Web Content/WEB-INF/lib to find the tomahawk JAR file. Because this JAR file is referenced in the library definition, the tool automatically copied it into a Web project the first time that the Tomahawk components were used. You will see how to configure other project setup steps in the next section.
  5. Back in the test page (testPage.jsp), notice that the t:commandButton tag was automatically surrounded by a JSF form tag. Also notice that in the Design view of Page Designer, the tag is properly visualized as a button. These both occur because the tool is aware that the new tag represents a JSF UI component.
  6. Click the button in the page to select it. Using the Properties view, you can modify any of the button tag's attributes using the usual JSF tools. For example, find the value attribute of the button in the Properties view and click the icon next to it to bring up the familiar binding dialog to generate a JSF binding expression.

Setting up additional project configuration

You will now return to the Faces Library Definition to add additional metadata for setting up Web projects. If you previously closed the library definition editor, go to the Library Definitions Project that you made earlier (MyFaces Components) and open the tomahawk.jld definition file.

Take a brief look around the library definition editor (shown in Figure 6). You will notice that the editor is divided into configuration sections on the left-hand side. The right-hand side of the editor contains fields corresponding to the section that is selected on the left.

Figure 6. Faces Library Definition editor
Overview on left, Details on right

Click to enlarge

In Figure 6, the top-most Faces Library Definition section is selected, which lets you configure very general information about the library on the right-hand side. The next steps will concentrate on the Application Configuration section, which corresponds to any changes that are made to a Web project when a third-party library is first used (you will be defining the actions that occur when you click OK in the prompt dialog after the first palette drops).

Adding more files to a project

You have seen that by default Rational Application Developer will add the JAR file for a third-party library (for example, tomahawk.jar) into a Web project automatically. However, there is often substantially more configuration that must occur to make a component library fully-functional at runtime. For example, some of the Tomahawk components require additional Apache Commons code to work correctly, so you will add these additional resources into the configuration.

  1. Go to http://commons.apache.org/downloads/index.html and download the following packages:
    1. commons-fileupload
    2. commons-lang
  2. Unzip both downloads and copy the JAR file for each package into the workspace folder that contains the tomahawk component JAR (for example, /MyFaces Components/tomahawk).
  3. Refresh the workspace if necessary so that you see the new commons-* JAR files in the Enterprise Explorer.

Next, perform the following steps in the library definition editor to add these JAR files into the configuration.

  1. Select the Resources section in the editor and click the Add button to the right. The only choice for this section is File, so just click OK. (Alternately, you can right-click the Resources section and select Add > File.)
  2. On the right side of the editor, click the browse or ellipses (...) button next to the Source path field.
  3. Browse to find the commons-fileupload JAR file that you just added, as shown in Figure 7, and click Finish. Notice that by default, JAR files will be added into /WEB-INF/lib in a Web project.
  4. Repeat this process to create another Resource entry for the commons-lang JAR file.
Figure 7. Adding a new file resource to the library definition
the Select a file or a folder dialog

Click to enlarge

Additional Web application configuration

Some components in the Tomahawk library also require a filter to handle resource requests at runtime. To automatically set up the MyFaces Extensions Filter in Web projects, you will add more configuration elements in the library definition editor.

  1. Select the web.xml Updates section under Application Configuration in the Library Definition editor.
  2. Click Add and select Filter. Click OK.
  3. An empty filter configuration will appear on the right. Fill in the following values, as shown in Figure 8:
    1. Name: MyFacesExtensionsFilter
    2. Class: org.apache.myfaces.webapp.filter.ExtensionsFilter
    3. Select and edit the default value under URL Mappings and change it to: /faces/myFacesExtensionResource/*
    4. Click Add next to Servlet Mappings and enter: Faces Servlet
  4. The extensions filter also requires an initialization parameter. To add this parameter, select the new filter on the left side of the editor and click Add to create a blank Init Param file. Then fill in the following values:
    1. Name: maxFileSize
    2. Value: 20m
    3. Description: Set the size limit for uploaded files.
Figure 8. Adding a filter definition
Overview left, Filter definition and mappings right

Click to enlarge

In addition to defining new filters as just described, the web.xml Updates section also allows you to register new servlets, and to add additional context parameters to a Web application when a JSF component library is used.

In some cases, a library requires extra configuration elements in faces-config.xml to function properly. The Faces Configuration File section under Application Configuration is used to specify an additional faces-config file to add to a Web application's runtime configuration.

This file should be located in the same directory as the Faces Library Definition file. The file will be copied into a Web project's /WebContent/WEB-INF folder, and also referenced in web.xml to be used at runtime. The only restriction is that the new file cannot be named faces-config.xml, because that would collide with the default configuration file already present in a JSF Web project.

Testing application configuration changes

With the changes you just made, Web projects that use Tomahawk components will now have the additional Commons JAR files added to them, and the Extensions Filter will be registered automatically in web.xml. You could confirm this by creating another new test project and Web page. But at this point you will instead demonstrate updating the configuration of the test project that you created earlier.

Whenever a JSF tag library is installed in a Web project, the tool keeps track of the version of the library's configuration. This is true of both libraries that are supported directly in Rational Application Developer and third-party library definitions like what you have built for Tomahawk. When appropriate, the tool checks existing Web projects to see if any tag library updates are available, and provides a prompt to update a project's configuration accordingly. You will use this mechanism to update the Tomahawk tag library in your test project.

  1. Select the top-most Faces Library Definition section on the left side of the library definition editor.
  2. On the right-hand side, find the Version field and increase the value to a higher number (for example, change 1.0 to 1.0.1), as shown in Figure 9.
Figure 9. Changing the version of the library definition
Overview on left, Details on right

Click to enlarge

  1. Save the library definition.
  2. Switch to (or open) the Problems view. After a short time, a new Error should appear indicating that Faces Resources need to be updated for your test project.
  3. Select the Error in the Problems view, right-click, and choose Quick Fix.
  4. Click Finish on the Quick Fix dialog.
  5. A prompt for updating the Web project will now appear. You should see the tomahawk URI listed as a library that has newer configuration available. Click Yes on this dialog, as shown in Figure 10.
Figure 10. Update resources dialog for JSF component libraries
you can choose Yes, Later, or Never

Answering Yes to the resource update dialog causes the project configuration steps for Tomahawk to be run again. Examine your test project to confirm that the additional Commons JAR files have been added, and that the Extensions Filter has been defined in web.xml.

The steps that you just performed to update your existing Web project are the typical process when any configuration changes are made in the library definition for a JSF component library. In fact, any changes under the Application Configuration section in the library definition editor require a version number increase to propagate your changes to existing projects.

If the component library has not been used yet in any Web project, then no changes to the version are needed. Also, as you will see in the next section, other changes to a library definition outside of the Application Configuration area will be picked up right away by the tools, and do not require any version number changes or project resource updates.

Tag Library configuration

You will now explore other modifications to the Tomahawk library definition that affect the tool behavior on a tag-by-tag basis. There are a few settings that have an effect on all tags in the library, but most of the configuration from this point on will be focused on individual tags.

  1. Open the library definition editor and select the Tag Library section. Notice that most of the fields on the right side of the editor are concerned with the general appearance (labels, icons, and open/closed state) of the palette drawer for this library. The lists for CSS and JavaScript links are the exception, with both lists indicating references that should be added into a JSP page when any tag in this library is inserted into the page.
  2. To look at tag-specific settings, open up the Tag Library node in the editor and find the commandButton tag entry. Select it and examine the fields in this section. In the right-hand portion of the editor make these changes:
    1. For label, enter Tomahawk's Command Button
    2. Click the browse or ellipses (…) icon next to Small icon.
    3. In the dialog that is displayed, select the Command – Button icon under Standard Faces Components. This will reuse one of Rational Application Developer's built-in JSF component icons. Leave the check box selected to also set the associated large icon automatically.
    4. Click OK. Your configuration should look like that shown in Figure 11.
Figure 11. Configuring palette appearance for a single tag
referenced details
  1. Highlight the commandButton tag on the left side of the editor and click the Up button repeatedly to move it to the top of the list of tags. The ordering of the tags in the editor will be reflected in the palette.
  2. Save the library definition file.
  3. Now open the test JSP you created earlier. Find the Tomahawk library's drawer on the palette. You will notice the button now appears first in the drawer, the icon you just selected is shown, and your new text label is used instead of the tag name.

Tag-specific configuration

To look at other configuration areas besides the palette appearance, open the node for commandButton in the library definition editor and examine the related sections below it. The remainder of this article explores each of these areas and uses several different Tomahawk tags to demonstrate some of the different configuration options.

The Drop Properties section

The Drop Properties section under each tag is concerned with defining drag-and-drop behaviors. These configuration elements apply when you drag tags from the palette or Page Data View, and in some other tag-insertion scenarios.

The first checkbox in the section indicates whether a JSF form should surround the tag being dropped. The other check box called Allows children indicates whether a particular JSF tag should allow other JSF UI components to be dropped inside it. This selection does not apply to non-UI tags like JSF converters, validators, or facets, so you should leave it clear for most controls and only select it for panel-like controls that render their children.

Like many other configuration elements in the library definition, the values of these check boxes are set when the wizard initially inspects a tag library. Typically, most of the values will be defaulted correctly, but there may be some ambiguous situations where you need to fine-tune the settings. To look at an example, perform the following steps.

  1. Open the test Web page that you created earlier (testPage.jsp).
  2. From the Tomahawk palette drawer, drag a dataTable tag onto the page. It will simply appear as a gray box showing the t:dataTable tag name.
  3. Now drop a Tomahawk column tag onto the dataTable tag. You will notice that the t:column tag was automatically added inside the dataTable. This is because the default value for the Allows children check box for the dataTable tag was set correctly.
  4. Drag the Tomahawk Command Button tag from the palette and try to drop it directly onto the column tag, as shown in Figure 12.
Figure 12. Dropping a tag into a column
square icon with a plus sign in it
  1. You may notice that the button did not go into the column as intended. Instead, it landed inside the dataTable but next to a column, which is invalid, as shown in Listing 1. This occurred because the wizard that created the library definition cannot tell what the column tag represents, so it defaulted to prevent child tags inside a column.
Listing 1. Incorrect drop results for column
<t:dataTable styleClass="dataTable" id="table1">
	<t:commandButton styleClass="commandButton"id="button1"></t:commandButton>
	<t:column styleClass="column" id="column1"></t:column>
  1. Undo the incorrect button drop (type Ctrl-Z or go to Edit > Undo JSF tag insertion).
  2. Go back to the library definition editor for Tomahawk and find the column tag.
  3. In the Drop Properties section, select Allows children, as shown in Figure 13. Save your changes.
Figure 13. Modifying column drop properties
Drop Properties Details with referenced check box
  1. Return to your test page and try to drop the button onto the column tag again. This time, the button should be added inside the column, as shown in Listing 2. If you have trouble getting the drop to occur in the correct location, you can also drop into the source view of the editor, anywhere on the t:column tag. Disregard the odd appearance of the design page for now, because you will correct it shortly.
Listing 2. Corrected tag nesting
<t:dataTable styleClass="dataTable" id="table1">
	<t:column styleClass="column" id="column1">
		<t:commandButton styleClass="commandButton" id="button1">

The other fields on the Drop Properties section of the library definition editor define lists of strings that are used by the tools. The first two indicate any CSS and JavaScript links that need to be added to a JSP page for a component to be functional. These will only apply to a specific single tag. You should specify library-wide links on the Tag Library section instead.

The last field in this section specifies the names of any JSF facets that may be used with a component. The following example shows how facet names are used in the tool.

  1. Open the Tomahawk library definition and go to the Drop Properties section for the column tag.
  2. Click to Add a new item next to the Allowed Facets area.
  3. Change the item name to header.
  4. Save the library definition.
  5. Now return to your test page and find the t:column tag that you added in the earlier steps. Click to select it.
  6. Find or open the Properties view. The view is typically below the page editor in the Web perspective. You can always bring it up by selecting Window > Show View > Properties.
  7. On the Properties view for the column tag, click the button at the top of the view to add a child tag, as shown in Figure 14. Notice the header facet name is an available option (because of your library definition change previously).
Figure 14. Adding a facet via the Properties view
options are headerFacet, Parameter, and Attribute
  1. Select the header Facet option and notice that a corresponding f:facet tag is added underneath the column.

The Visualization section

As you saw earlier with the Tomahawk commandButton tag, the JSF tools in Rational Application Developer can often visualize third-party components correctly in the page editor without the need for you to configure anything. This is accomplished by running part of the JSF rendering logic to emit an HTML representation of the component.

Sometimes this pseudo-rendering process fails however, either because the component's rendering logic is too complex or because some necessary elements of a real server runtime are not present in the development environment. When this occurs, a generic gray icon is typically shown, as you saw previously with the dataTable and column tags.

To achieve a better development experience for components that cannot be automatically visualized, the library definition provides for a template-based approach to generating a visual representation of a particular tag. If a visualization pattern is provided in a library definition, the automatic rendering process will be bypassed, and the HTML pattern will be evaluated and used directly by the page editor.

There are several variables applicable to a visualization pattern. The best way to explore these options is to look at the sample templates provided in the tool. These samples represent some of the most common JSF control types. You will now create user-defined visualizations for Tomahawk's dataTable and column components, which will offer substantial improvement over the user experience that you saw previously.

Follow these steps:

  1. Find the dataTable tag in the library definition and select the Visualization section below it.
  2. Click the Edit button on the right side (the text area for the pattern is read-only).
  3. In the Modify Visualization dialog that is displayed, click Insert from Template.
  4. Select the Data table choice and click OK. You will now see some markup text in the visualization section.
  5. Repeat these steps for the column tag, choosing the Column in a data table template this time.
  6. Save the library definition.
  7. Find and close your test JSP page if it is currently open in an editor. Visualization changes will only take effect after a page is reopened.
  8. Open the test page again in the editor, and notice the dataTable and column now have a much more desirable appearance. The action of dragging new components is also much simpler with the new visualization, as shown in Figure 15.
Figure 15. Customized visualization for data table
Submit Query button

In Figure 15, the commandButton tag inside the column is now appearing correctly in the page. This is the result of the ${children} variable in the sample template that you used for the column tag. When the visualization is calculated, this variable is replaced with all the child tags of the column so that they appear in the correct positions in the page.

In addition, notice that the header facet that you added to the column in an earlier step is shown with the Drop a component here text. This is due to the ${facet:header} variable in the column template. This variable looks for a JSF facet tag of the specified name (header), and either substitutes the child tag found under the facet or, if there isn't one, the explanatory text shown previously. You can drop a new tag (for example, outputText) into the facet area, and you will see that it appears in the correct place above the column body.

There are a number of sample templates for other common component types. You can explore each of these to see more examples of substitution variables that you can use in a customized visualization.

The Tag Attributes section

Find the Tomahawk command button tag in the library definition editor and open the Tag Attributes section to see the list of attribute names. This attribute list was created when the library definition was created, and is a fixed list. However, you can adjust the order of these attributes in the library definition, and the order has an effect on the tool behavior. To see how, follow these steps:

  1. Open your test JSP page in the page editor.
  2. If there isn't already one on the page, drop a Tomahawk command button from the palette.
  3. While the button tag has focus in the page editor, go to the Properties view.
  4. Notice that the list of attributes is sorted alphabetically. This ordering was performed when the library definition was created.
  5. Now open the library definition editor for the Tomahawk library.
  6. Find the commandButton tag and open the Tag Attributes section.
  7. Select the dir attribute and click the Up button several times until it is the top-most attribute.
  8. Save the library definition.
  9. Return to your test JSP page. Select a JSF component other than the commandButton (drop a different one from the palette if necessary), and then select the button tag again to refresh the tools.
  10. Notice that the dir attribute is now listed first.

This ordering mechanism can be used to reorder the Properties view display, so the most important and common attributes are listed first. For example, the value and styleClass attributes might be often modified for many components.

Another aspect of configuring tag attributes is specifying what type the attribute represents. For example, in most cases onclick represents a JavaScript event, readonly is a Boolean, and styleClass specifies the name of a CSS class. Attributes that follow standard JSF naming conventions (like these preceding examples) are all preset to appropriate values.

The attribute types are reflected in the behavior of the Properties view. For example, if you click the edit area next to readonly for one of the Tomahawk tags, it shows a combo box giving you the choices of true, false, or a value expression that you can bind to application data.

Some third-party tags will have unique and specific attributes and possible values, which you can configure using the library definition. As an example:

  1. Go to the dataTable tag in the library definition editor and find the newspaperOrientation attribute.
  2. Click the edit button next to the Type element.
  3. In the dialog that appears, choose Enum as the type. This represents an enumeration of possible legal values.
  4. Click the Add button to add values for horizontal and vertical, which the attribute description text indicates as the allowed values.
  5. Click OK to set the new type, as shown in Figure 16.
Figure 16. Specifying an attribute type
the Select an Attribute Type dialog

Click to enlarge

  1. Return to your test JSP page. Select a Tomahawk dataTable tag (drop a new one from the palette if necessary) and go to the Properties view.
  2. Find the newspaperOrientation attribute and notice that when you click in the edit field the values that you just specified are shown as choices.

The Data Binding section

The Data Binding section in the library definition editor allows you to change some details of how the tools bind data to particular JSF components. As usual, the library definition is created with appropriate defaults for most cases, but there may be a few special cases or non-standard attribute names that will require changes.

Find the commandButton tag in the library definition and open the Data Binding section to look at the configurable values. You will see that, by default, the attribute value is used for binding. This choice specifies which attribute is modified when you drag data from the Page Data view onto a JSF tag in a page. In some cases, a different attribute is used for typical bindings, in which case the alternative choice can be selected in the dropdown.

Now look at the Data Binding section for the Tomahawk dataTable tag. You will notice that in this case, the check box specifying multi-valued data is selected. This indicates that the dataTable component expects a collection of data to iterate over when rendering its output. Selecting this box causes value expressions to be written in a slightly different form (omitting a [0] from the end of the binding string).

The last item on the Data Binding section specifies an attribute that is used when displaying a collection of data. You will see that for the Tomahawk dataTable it has been set to the standard JSF var attribute. This attribute is assigned when binding the dataTable tag and is also used to generate binding expressions for other JSF components nested inside the dataTable. It is generally specified in conjunction with the multi-valued check box discussed earlier.

The Tomahawk components should generally have been set up correctly, but you can explore the Data Binding functionality by changing the values in this section for a tag. Notice that dropping data from the Page Data view will alter different attributes as a result.

The Child Tags section

Child Tags is an optional section that may be added to a tag in a library definition. This section contains a pattern to generate new tags that are added inside of the selected tag, and provides a useful shortcut for some common page-editing operations. In the following example, you make it easier to add new columns to a Tomahawk data table.

  1. Select the dataTable tag in the Tomahawk library definition.
  2. Click the Add button in the editor. When the dialog appears, select Child Tags (the only choice) and click OK.
  3. Specify New Column as the pattern name.
  4. Type an optional description as desired.
  5. Add the text shown in Listing 3 to the Pattern field shown in Figure 17. Notice that the pattern is defining other JSF tags to make up a new column, and its header section inside the dataTable. All tag prefixes and some attribute values should use computed variables (the ${} expressions), which you can add into a pattern by using the Insert Variable button.
Listing 3. Pattern tags
<${t}:column styleClass=column id=${id}>
  <${f}:facet name=header>
    <${t}:outputText value=Column Name />
Figure 17. Creating a new Child Tags pattern
dialog with Name, Description, and Pattern fields
  1. Click OK to save the new Child Tags pattern.
  2. Save the library definition.
  3. Now go back to your test JSP page and drop a new dataTable component from the Tomahawk drawer of the palette.
  4. With the dataTable tag selected, go to the Properties view and click the button to add new child tags. Select New Column from the drop-down (this is the name that you just specified for the pattern above).
Figure 18. Adding a new column to a dataTable
New Column, Parameter, and Attribute menu options
  1. Notice that a new column tag has been added to the dataTable with appropriate values substituted for the tag prefixes and component ID.

The Data Templates section

Data Templates is an optional section under the top Faces Library Definition section that you can use to enhance the behavior of the Page Data view. When you drag a piece of data from the Page Data view onto a JSP page, a wizard is displayed to let you choose what types of UI controls to generate. By creating new data templates for tags in your component library you can offer more choices in this wizard.

There are two types of data templates available in the library definition editor. You use Property templates for most basic control types. For example, you could create a template for Tomahawk's inputDate component and associate it with a java.util.Date type. You use Iterative templates to generate more complex nested controls associated with collections of data. For example, you could create an iterative template to generate the Tomahawk dataTable and column tags when a list of data is dropped.

The templating system used in library definitions is the same as that used for the product-wide configuration, which is found under Window > Preferences > Web > JavaServer Faces Tools > Generation Templates. Putting data templates into a library definition merely provides a consistent way to share template choices for that library’s components with all of the users of the library.

Best practices

By now you have seen how to configure many of the common elements in a library definition to improve the development experience using third-party JSF components. After you configure a library definition to your satisfaction, you probably will want to share the library with other developers. This is best achieved by checking the library definitions project into a source control system, and having others check it out into their workspaces. Remember that the mere presence of the library definition in a workspace is all that's required to make the tools behave as you intended.

There are a few additional points to consider when you build a library definition:

  • If a JSF component library requires multiple JAR files, it is best to specify these directly in the Faces Library Definition wizard. For this Tomahawk example, you picked only the tomahawk JAR file in the wizard, and added the other Apache Commons JAR files to the configuration later. That process works fine for Tomahawk, but in some cases dependent JAR files need to actually be on the classpath in order to properly analyze JSF components while the tool generates a library definition. An example is the MyFaces Trinidad component library, for which you would point to the trinidad-impl jar file to define the component library, but you also need to add the trinidad-api jar file in the second page of the library definition wizard to avoid errors.
  • As you saw in an earlier section, the tools use the version number of a library definition to manage the updating of project resources if a newer definition becomes available. This mechanism results in several conventions that you should consider adopting:
    • Rename JAR files that make up a component library to use generic names. For example, use tomahawk.jar instead of tomahawk-1.1.8.jar. This makes future updates much easier because when tomahawk-1.1.9.jar (for instance) is released in the future, you can update the library definition and keep the same file name. Then any upgrades to existing Web projects will simply replace tomahawk.jar and no other steps will be necessary.
    • If multiple library definitions for the same tag library are in your workspace, the tools will ignore all except the one with the highest version number. For clarity, especially if you do change the JAR file names to remove version-specific information, it would be wise to set the version string in the library definition to something meaningful. The version is initially set to 1.0 but can be any number that matches the form a.b.c.d (the pattern matches Eclipse plug-in versioning rules). So in your example here, set the library version to 1.1.8 to represent which Tomahawk JAR file you used.


This article has explored new capabilities for using third-party JSF components in Rational Application Developer. Creating a library definition is an easy way to make the tools aware of new component libraries. A wealth of configuration parameters exists to help you fine-tune various behaviors. After you are finished configuring the library definition to your satisfaction, you can easily share that configuration with other developers so that everyone working with the components has the same experience.


Example project with a Faces Library Definitionrichfaces_libdef.zip79KB



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

ArticleTitle=Faces library definitions for third-party JavaServer Faces controls