Faces controls Introduction Faces library definitions for ......Java™Server Faces (JSF) technology is a popular Java™ framework for Web user interface components. IBM® Rational®

© Copyright IBM Corporation 2009 TrademarksFaces library definitions for third-party JavaServer Faces controls Page 1 of 21

Faces library definitions for third-party JavaServerFaces controls

Scott Paxton June 18, 2009

This article describes the new Faces Library Definition feature in IBM Rational ApplicationDeveloper 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 youwork with that library's UI components.

IntroductionJava™Server Faces (JSF) technology is a popular Java™ framework for Web user interfacecomponents. IBM® Rational® Application Developer has included robust tools for developing JSFWeb 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. Thisarticle discusses the process of consuming a third-party component library, configuring metadatafor 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 thedevelopment environment. If you have some new third-party JSF controls (either created fromscratch 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 apage in the Java™ Server Pages (JSP™) editor.

• When a component library is first added to a Web project, the appropriate resources needto be added into the project, and any necessary configuration steps should be performed tomake the library usable.

• There needs to be a way to see and configure the UI components after they've been added toWeb 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 andthe IBM-supplied JavaServer Faces widget library (JWL) component libraries. You will now seehow to expand this support to other JSF component libraries. This article demonstrates the newfunctionality using open-source MyFaces Tomahawk components as an example, but this sameprocess applies to any valid JSF component library.

http://www.ibm.com/legal/copytrade.shtml

https://www.ibm.com/developerworks/ibm/trademarks/

developerWorks® ibm.com/developerWorks/

Faces library definitions for third-party JavaServer Faces controls Page 2 of 21

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 aconfiguration file plus any other file resources that the library needs. These files are all stored in aspecial 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 usedas 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 Webcategory).

2. The only thing to do in the wizard is to give the project a name (in this case, MyFacesComponents), as shown in Figure 1.

Figure 1. Create a Faces Definitions Project

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

3. Right-click the new project that you just created and select New > Faces Library Definition.4. Give the new definition a name (for example, tomahawk).

http://myfaces.apache.org/download.html

ibm.com/developerWorks/ developerWorks®


5. Click the browse button next to the Jar file field. Select the location of the JAR file that youdownloaded earlier from the Apache site, as shown in Figure 2.

6. Click Finish.

Figure 2. Create a new Faces Library Definition

After a short time spent analyzing the Tomahawk JAR file and generating files, the wizard willcomplete and open the new JLD configuration file (tomahawk.jld). You will look much more closelyat this editor in the next sections, but for now just notice that the file contains information forconfiguring 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 alreadysucceeded in making the tools aware of Tomahawk components. Next, explore how the tool usesthis configuration and look at ways it can be fine-tuned.

Setting up a JSF Web projectNow you will create a JSF Web project to see how the new component library integrates with theJSF 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 moreusual Faces Project configuration. This is because the Faces Project preset also includes theIBM JWL component library, which you probably would not be using in conjunction with third-partylibraries. In general, you should use the more basic JSF configuration when you are includingthird-party components in your project.



Figure 3. Create a test Web project

Next create a JSP page in this test project.

5. Right-click the project name in the Enterprise Explorer.6. Select New > Web Page.7. Enter a name for the JSP in the wizard, as shown in Figure 4.8. Click Finish.



Figure 4. Create a test Web page

Exploring a basic third-party component integration

1. When the test page you just created opens in the editor, look at the palette view andnotice the new tomahawk drawer, as shown in Figure 5. (Generally, you will find third-partycomponent libraries at the bottom of the palette).



Figure 5. Palette with third-party components

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

2. Try closing the project that holds the definition (MyFaces Components) and notice that thepalette drawer promptly disappears. Then reopen the project to bring the drawer back.

3. Now drag the Tomahawk commandButton component from the palette into the test JSP. Aprompt will appear asking to copy new project resources.

4. Click OK to allow the tool to add Tomahawk into the test project (notice that the button tagwas also added into the page).

5. 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 librarydefinition, the tool automatically copied it into a Web project the first time that the Tomahawkcomponents were used. You will see how to configure other project setup steps in the nextsection.

6. Back in the test page (testPage.jsp), notice that the t:commandButton tag wasautomatically surrounded by a JSF form tag. Also notice that in the Design view of PageDesigner, the tag is properly visualized as a button. These both occur because the tool isaware that the new tag represents a JSF UI component.

7. Click the button in the page to select it. Using the Properties view, you can modify any of thebutton tag's attributes using the usual JSF tools. For example, find the value attribute of thebutton in the Properties view and click the icon next to it to bring up the familiar binding dialogto 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 Webprojects. If you previously closed the library definition editor, go to the Library Definitions Projectthat 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 theeditor is divided into configuration sections on the left-hand side. The right-hand side of the editorcontains fields corresponding to the section that is selected on the left.

Figure 6. Faces Library Definition editor

Click to enlarge

In Figure 6, the top-most Faces Library Definition section is selected, which lets you configurevery general information about the library on the right-hand side. The next steps will concentrateon the Application Configuration section, which corresponds to any changes that are made to aWeb project when a third-party library is first used (you will be defining the actions that occur whenyou 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 oftensubstantially more configuration that must occur to make a component library fully-functional atruntime. For example, some of the Tomahawk components require additional Apache Commonscode 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 followingpackages:

a. commons-fileuploadb. commons-lang

2. Unzip both downloads and copy the JAR file for each package into the workspace folder thatcontains 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 theEnterprise Explorer.

image006_lg.jpg

http://commons.apache.org/downloads/index.html



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

4. Select the Resources section in the editor and click the Add button to the right. The onlychoice for this section is File, so just click OK. (Alternately, you can right-click the Resourcessection and select Add > File.)

5. On the right side of the editor, click the browse or ellipses (...) button next to the Source pathfield.

6. 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 Webproject.

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

Click to enlarge

Additional Web application configuration

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

1. Select the web.xml Updates section under Application Configuration in the LibraryDefinition 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:a. Name: MyFacesExtensionsFilterb. Class: org.apache.myfaces.webapp.filter.ExtensionsFilterc. Select and edit the default value under URL Mappings and change it to: /faces/

myFacesExtensionResource/*

d. Click Add next to Servlet Mappings and enter: Faces Servlet

image007_lg.jpg



4. The extensions filter also requires an initialization parameter. To add this parameter, select thenew filter on the left side of the editor and click Add to create a blank Init Param file. Then fillin the following values:

a. Name: maxFileSizeb. Value: 20mc. Description: Set the size limit for uploaded files.

Figure 8. Adding a filter definition

Click to enlarge

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

In some cases, a library requires extra configuration elements in faces-config.xml to functionproperly. The Faces Configuration File section under Application Configuration is used tospecify 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 becopied into a Web project's /WebContent/WEB-INF folder, and also referenced in web.xml to be usedat runtime. The only restriction is that the new file cannot be named faces-config.xml, becausethat would collide with the default configuration file already present in a JSF Web project.

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

Whenever a JSF tag library is installed in a Web project, the tool keeps track of the version ofthe library's configuration. This is true of both libraries that are supported directly in Rational

image008_lg.jpg



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 areavailable, and provides a prompt to update a project's configuration accordingly. You will use thismechanism 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 definitioneditor.

2. On the right-hand side, find the Version field and increase the value to a higher number (forexample, change 1.0 to 1.0.1), as shown in Figure 9.

Figure 9. Changing the version of the library definition

Click to enlarge

3. Save the library definition.4. 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.5. Select the Error in the Problems view, right-click, and choose Quick Fix.6. Click Finish on the Quick Fix dialog.7. 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 inFigure 10.

Figure 10. Update resources dialog for JSF component libraries

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

image009_lg.jpg



The steps that you just performed to update your existing Web project are the typical processwhen 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 editorrequire 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 versionare needed. Also, as you will see in the next section, other changes to a library definition outside ofthe Application Configuration area will be picked up right away by the tools, and do not requireany version number changes or project resource updates.

Tag Library configuration

You will now explore other modifications to the Tomahawk library definition that affect the toolbehavior on a tag-by-tag basis. There are a few settings that have an effect on all tags in thelibrary, 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 thefields 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 JavaScriptlinks are the exception, with both lists indicating references that should be added into a JSPpage 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 thecommandButton tag entry. Select it and examine the fields in this section. In the right-handportion of the editor make these changes:

a. For label, enter Tomahawk's Command Buttonb. Click the browse or ellipses (…) icon next to Small icon.c. 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 JSFcomponent icons. Leave the check box selected to also set the associated large iconautomatically.

d. Click OK. Your configuration should look like that shown in Figure 11.

Figure 11. Configuring palette appearance for a single tag

3. Highlight the commandButton tag on the left side of the editor and click the Up buttonrepeatedly to move it to the top of the list of tags. The ordering of the tags in the editor will bereflected in the palette.

4. Save the library definition file.



5. 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 configurationTo look at other configuration areas besides the palette appearance, open the node forcommandButton in the library definition editor and examine the related sections below it. Theremainder of this article explores each of these areas and uses several different Tomahawk tags todemonstrate some of the different configuration options.

The Drop Properties sectionThe 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, andin some other tag-insertion scenarios.

The first checkbox in the section indicates whether a JSF form should surround the tag beingdropped. The other check box called Allows children indicates whether a particular JSF tagshould allow other JSF UI components to be dropped inside it. This selection does not apply tonon-UI tags like JSF converters, validators, or facets, so you should leave it clear for most controlsand 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 boxesare set when the wizard initially inspects a tag library. Typically, most of the values will be defaultedcorrectly, 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 theAllows 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 thecolumn tag, as shown in Figure 12.

Figure 12. Dropping a tag into a column

5. You may notice that the button did not go into the column as intended. Instead, it landedinside the dataTable but next to a column, which is invalid, as shown in Listing 1. Thisoccurred because the wizard that created the library definition cannot tell what the column tagrepresents, 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></t:dataTable>

6. Undo the incorrect button drop (type Ctrl-Z or go to Edit > Undo JSF tag insertion).7. Go back to the library definition editor for Tomahawk and find the column tag.8. In the Drop Properties section, select Allows children, as shown in Figure 13. Save your

changes.

Figure 13. Modifying column drop properties

9. Return to your test page and try to drop the button onto the column tag again. This time, thebutton should be added inside the column, as shown in Listing 2. If you have trouble gettingthe 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"> </t:commandButton> </t:column></t:dataTable>

The other fields on the Drop Properties section of the library definition editor define lists of stringsthat are used by the tools. The first two indicate any CSS and JavaScript links that need to beadded to a JSP page for a component to be functional. These will only apply to a specific singletag. 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 acomponent. 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 columntag.

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 ofyour library definition change previously).

Figure 14. Adding a facet via the Properties view

8. Select the header Facet option and notice that a corresponding f:facet tag is addedunderneath the column.

The Visualization section

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

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

To achieve a better development experience for components that cannot be automaticallyvisualized, the library definition provides for a template-based approach to generating a visualrepresentation of a particular tag. If a visualization pattern is provided in a library definition, theautomatic rendering process will be bypassed, and the HTML pattern will be evaluated and useddirectly by the page editor.

There are several variables applicable to a visualization pattern. The best way to explore theseoptions is to look at the sample templates provided in the tool. These samples represent someof 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 overthe 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 muchsimpler with the new visualization, as shown in Figure 15.

Figure 15. Customized visualization for data table

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 columntag. When the visualization is calculated, this variable is replaced with all the child tags of thecolumn 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 shownwith the Drop a component here text. This is due to the ${facet:header} variable in the columntemplate. This variable looks for a JSF facet tag of the specified name (header), and eithersubstitutes the child tag found under the facet or, if there isn't one, the explanatory text shownpreviously. You can drop a new tag (for example, outputText) into the facet area, and you will seethat it appears in the correct place above the column body.

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



The Tag Attributes section

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

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 refreshthe 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 mostimportant and common attributes are listed first. For example, the value and styleClass attributesmight 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 namingconventions (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 clickthe edit area next to readonly for one of the Tomahawk tags, it shows a combo box giving you thechoices 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 canconfigure using the library definition. As an example:

1. Go to the dataTable tag in the library definition editor and find the newspaperOrientationattribute.

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

Click to enlarge

6. Return to your test JSP page. Select a Tomahawk dataTable tag (drop a new one from thepalette if necessary) and go to the Properties view.

7. Find the newspaperOrientation attribute and notice that when you click in the edit field thevalues that you just specified are shown as choices.

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

Find the commandButton tag in the library definition and open the Data Binding section to lookat the configurable values. You will see that, by default, the attribute value is used for binding. Thischoice specifies which attribute is modified when you drag data from the Page Data view onto aJSF tag in a page. In some cases, a different attribute is used for typical bindings, in which casethe 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 thiscase, the check box specifying multi-valued data is selected. This indicates that the dataTablecomponent expects a collection of data to iterate over when rendering its output. Selecting this boxcauses value expressions to be written in a slightly different form (omitting a [0] from the end ofthe binding string).

The last item on the Data Binding section specifies an attribute that is used when displaying acollection of data. You will see that for the Tomahawk dataTable it has been set to the standard

image016_lg.jpg



JSF var attribute. This attribute is assigned when binding the dataTable tag and is also usedto generate binding expressions for other JSF components nested inside the dataTable. It isgenerally 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 theData Binding functionality by changing the values in this section for a tag. Notice that droppingdata from the Page Data view will alter different attributes as a result.

The Child Tags sectionChild Tags is an optional section that may be added to a tag in a library definition. This sectioncontains a pattern to generate new tags that are added inside of the selected tag, and provides auseful shortcut for some common page-editing operations. In the following example, you make iteasier 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 thedataTable. 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 /> </${f}:facet></${t}:column>

Figure 17. Creating a new Child Tags pattern



6. Click OK to save the new Child Tags pattern.7. Save the library definition.8. Now go back to your test JSP page and drop a new dataTable component from the

Tomahawk drawer of the palette.9. 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 specifiedfor the pattern above).

Figure 18. Adding a new column to a dataTable

10. Notice that a new column tag has been added to the dataTable with appropriate valuessubstituted for the tag prefixes and component ID.

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

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

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

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



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 theFaces Library Definition wizard. For this Tomahawk example, you picked only the tomahawkJAR file in the wizard, and added the other Apache Commons JAR files to the configurationlater. That process works fine for Tomahawk, but in some cases dependent JAR files needto actually be on the classpath in order to properly analyze JSF components while the toolgenerates a library definition. An example is the MyFaces Trinidad component library, forwhich you would point to the trinidad-impl jar file to define the component library, but you alsoneed to add the trinidad-api jar file in the second page of the library definition wizard to avoiderrors.

• As you saw in an earlier section, the tools use the version number of a library definition tomanage the updating of project resources if a newer definition becomes available. Thismechanism 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 easierbecause when tomahawk-1.1.9.jar (for instance) is released in the future, you can updatethe library definition and keep the same file name. Then any upgrades to existing Webprojects 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 willignore all except the one with the highest version number. For clarity, especially if you dochange the JAR file names to remove version-specific information, it would be wise to setthe version string in the library definition to something meaningful. The version is initiallyset to 1.0 but can be any number that matches the form a.b.c.d (the pattern matchesEclipse plug-in versioning rules). So in your example here, set the library version to 1.1.8to represent which Tomahawk JAR file you used.

Summary

This article has explored new capabilities for using third-party JSF components in RationalApplication Developer. Creating a library definition is an easy way to make the tools awareof new component libraries. A wealth of configuration parameters exists to help you fine-tunevarious 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 thecomponents has the same experience.



Downloadable resources

Description Name SizeExample project with a Faces Library Definition richfaces_libdef.zip 79KB

© Copyright IBM Corporation 2009(www.ibm.com/legal/copytrade.shtml)Trademarks(www.ibm.com/developerworks/ibm/trademarks/)

http://www.ibm.com/developerworks/apps/download/index.jsp?contentid=394820&filename=richfaces_libdef.zip&method=http&locale=

http://www.ibm.com/legal/copytrade.shtml

https://www.ibm.com/developerworks/ibm/trademarks/

Documents

Faces controls Introduction Faces library definitions for ......Java™Server Faces (JSF) technology is a popular Java™ framework for Web user interface components. IBM® Rational®