Customized data binding to third-party JavaServer Faces controls in Rational Application Developer

This article shows you how to use IBM® Rational® Application Developer to customize data binding behavior to third-party Java™ Server Faces controls. You can also create your own data templates for third-party tag libraries and personalize your experience with Rational Application Developer.

Christie Rice (ricec@us.ibm.com), Software Engineer, IBM  

Christie RiceChristie Rice is a developer on the Rational Application Developer team who works on JavaServer Faces tools.



10 August 2010

Also available in Chinese Spanish

Introduction

IBM® Rational® Application Developer Version 7.5.5 has extensive built-in support for the standard Java™Server Faces (JSF) tag libraries. In addition, Rational Application Developer also provides support for third-party tag libraries. By using a Faces Library Definition, you can customize Rational Application Developer's interaction with these controls and align the tooling with your personal needs. Faces Library Definitions contain features for specifying how a particular control can bind to data. This article demonstrates those features and discusses strategies for configuring various types of controls. In addition, you will see how Rational Application Developer's data templates can be used with Faces Library Definitions and third-party controls.

There are two main ways to design your web page and connect components to data. You can either place the controls on the page first and then bind them to data, or you can set up data templates that will automatically create the controls for you based on the data that you have selected. This article looks at both approaches, and you will learn how easy they are, even with a third -party tag library.

You begin by creating a web project and a Faces Library Definition based on the MyFaces Tomahawk tag library. Next, you will edit the Faces Library Definition to give Rational Application Developer more information about these controls. Then you will create data templates based on some sample data and generate Tomahawk controls bound to that data. Finally, you will add individual Tomahawk controls to a web page and then bind them to our sample data.

Over the course of this article, you will create:

  • A Faces Library Definition based on Tomahawk
  • A web project containing two pages:
    • A page that contains controls generated from data templates
    • A page that has controls placed on it first and then bound to data

Both web pages will display basic information about a fictitious employee at MyCompany: her name and the positions that she held at the company.

Prerequisites

These previous developerWorks articles provide background information. You should read both of them before reading this article.

  1. An introduction to Faces Library Definitions and an overview of Rational Application Developer's support for third-party libraries
  2. An introduction to JavaServer Faces Data Templates

Setup

Create a web project

Begin by creating a web project. This is a simple project that allows you to test and configure Rational Application Developer's interaction with the Tomahawk controls.

  1. Select File > New > Dynamic Web Project from the menu.

The New Dynamic Web Project wizard is displayed. Select the following options, as shown in Figure 1.

  1. Name the project MyWebProject.
  2. Target a server of your choice.
  3. In the Configuration combo box, select JavaServer Faces v1.2 Project.
  4. Click Finish.
Figure 1. New Dynamic Web Project wizard
Completed New Dynamic Web Project wizard

Now, create two web pages.

  1. Right-click MyWebProject in the Enterprise Explorer and select New > Web Page.
  2. In the New Web Page wizard, name the page createControls, as shown in Figure 2.
  3. Click Finish.
Figure 2. New Web Page wizard
Template on left, Preview on right

A new Faces JSP (JavaServer Page) named createControls will be created and opened for you.

Create the second web page.

  1. Right-click MyWebProject in the Enterprise Explorer and select New > Web Page.
  2. In the New Web Page wizard, name the page existingControls.
  3. Click Finish.

A second Faces JSP named existingControls is created and opened for you.

Now, import some sample data into the project. This data will describe the test employee and give some basic information about her.

  1. Download the Employee.zip file attached to this article.
  2. In the Enterprise Explorer, expand MyWebProject > Java Resources.
  3. Right-click src and select Import.
  4. In the Import wizard, expand General and select Archive File.
  5. Click Next.
  6. Browse to the .zip file's location on your computer
  7. Click Finish.

A new package with three JavaBean classes will be imported into the project. These contain a simple employee record.

Now that the sample beans are in the project, make them available to your web pages.

  1. Go to createControls.jsp. If this page is not already open, expand MyWebProject > WebContent and double-click createControls.jsp.
  2. In Page Data view, right-click Faces Managed Beans and select New > Faces Managed Bean.
  3. In the Add JavaBean wizard, enter emp for the Name and com.MyCompany.TestEmployee for the Class, as shown in Figure 3.
  4. Click Finish.
  5. Save the page by selecting File > Save.
Figure 3. Add a new Faces Managed Bean
Options on top, Initialize Properties button below

Create a library definition

Now, create a Faces Library Definition. As described in the first article mentioned in the Prerequisites section, Faces Library Definitions allow you to customize Rational Application Developer's interaction with a third-party JSF tag library.

This article uses the Tomahawk tag library as an example third-party JSF tag library, so you will need to obtain a copy of the Tomahawk component Java™ archive (JAR) file. You can download the file from the Apache MyFaces website.

  1. Download the Tomahawk JAR file.
  2. Go to File > New > Other.
  3. Expand Web and select Faces Library Definition.
  4. Click Next.
  5. Name the library Tomahawk, as shown in Figure 4.
  6. In the Select a JAR file section, click the Browse button and navigate to your copy of the JAR file.
  7. Click Finish.

The Faces Library Definition will open. This file, which has a .jld extension, tells Rational Application Developer how to interact with the Tomahawk controls.

Figure 4. New Faces Library Definition window
Overview on left, Details on right

Configure visualizations

Now you will configure visualizations for some of the Tomahawk controls. Visualizations affect how controls are rendered. You will customize this to make a few of the controls that you will be using easier to work with. You will also update the controls' palette icons and labels to make them faster to identify and locate.

Configure output text

  1. Expand Faces Library Definition > Tag Library (Tomahawk) > outputText.
  2. Click outputText.
  3. On the right, change the Label to Output Text.
  4. Click the button next to the Small icon.
  5. Expand Standard Faces Components and click Output.
  6. Click OK.

Configure panel grid

  1. Expand Faces Library Definition > Tag Library (Tomahawk) > panelGrid.
  2. Click on panelGrid.
  3. On the right, change the Label to Panel Grid.
  4. Click the button next to the Small icon.
  5. Expand Standard Faces Components and click Panel - Grid.
  6. Click OK.
  7. Now click Visualization under panelGrid.
  8. Click the Edit button.
  9. In the Modify Visualization window, click Insert from Template.
  10. Click Grid.
  11. Click OK twice.

Configure data table

  1. Expand Faces Library Definition > Tag Library (Tomahawk) > dataTable.
  2. Click dataTable.
  3. On the right, change the Label to Data Table.
  4. Click the button next to the Small icon.
  5. Expand Standard Faces Components and click Data Table.
  6. Click OK.
  7. Now click Visualization under dataTable.
  8. Click the Edit button.
  9. In the Modify Visualization window, click Insert from Template
  10. Click Data table
  11. Click OK twice.

Configure column

  1. Click Faces Library Definition > Tag Library (Tomahawk) > column > Visualization.
  2. Click the Edit button.
  3. In the Modify Visualization window, click Insert from Template.
  4. Click Column in a data table
  5. Click Ok twice.
  6. Save the Faces Library Definition by selecting File > Save.

Creating new templates

MyCompany is designing a new website. They would like to create a page that displays an employee's name and her past positions in the company. Because you have already imported your sample data, create data templates based on that data. These data templates can then be used to very quickly generate the web page that you are looking for. The second article in the Prerequisites section goes into more detail about Data Templates.

Start by creating a simple template that will create a Tomahawk Output Text control for a Java object.

  1. Click Faces Library Definition > Data Templates.
  2. Click the Add button.
  3. In the Add Item window, click Property Template and then click OK.

The Edit Template window will appear, as shown in Figure 5.

  1. Enter Tomahawk Output Text for the Name.
  2. Enter java.lang.Object for the Class.
  3. Enter An Output Text control from the Tomahawk tag library for the Description.
  4. Leave the Default template for this class and Use for input options cleared.
  5. Paste this in for the Pattern:
<${t}:outputText id="${id}" value="#{${value}}"></${t}:outputText>
  1. Click OK.
  2. Save the library definition.
Figure 5. Property template
Options above, Insert Variable button below

Variables in a template pattern are designated by ${variableName}. For example, ${id} is a variable. Variables are bits of the template that will be dynamically computed when the template is used. This template has three different variables:

  • id
  • value
  • t (a tag library prefix variable)

The id is a variable to ensure that the ID on the page will be unique.

The value variable will bind the output text specifically to a piece of data.

The taglib prefix variables will substitute the appropriate prefix for the particular page that the output text is used on; the prefix will most likely be "t".

Now look at your template in action.

  1. Open createControls.jsp.
  2. In the Page Data view, expand Faces Managed Beans > emp (com.MyCompany.TestEmployee) > employee (com.MyCompany.Employee), as shown in Figure 6.
  3. Click name (java.lang.String) under employee and drag the name to the page.
Figure 6. Page Data view
Tree view with icons on upper right

When you release the mouse, the Insert JavaBean wizard is displayed.

  1. Click the Displaying data (read-only) radio button
  2. Locate the combo box under Control Type.
  3. Select Tomahawk Output Text, as shown in Figure 7
  4. Click Finish.
Figure 7. Insert JavaBean wizard
Tomahawk Output Text drop-down option selected

The web page now contains a new HTML table. The third column of this table contains a Tomahawk Output Text control, just like your template. Note that you didn't have to do anything special on createControls.jsp in order to create these controls: all of the configuration was done in the Faces Library Definition.

  1. Save the page.

Creating a complex template

Now you will create a more complex data template: one that will generate a data table. This data table will display previous jobs that the employee performed.

  1. Switch to the Library Definition.
  2. Click Faces Library Definition > Data Templates.
  3. Click the Add button.
  4. In the Add Item window, select Iterative Template.
  5. Click OK.

The Edit Template window is displayed, as shown in Figure 8.

  1. Enter Tomahawk Data Table for the Name
  2. Enter java.lang.Object[] for the Class
  3. Leave both check boxes clear.
  4. Enter A Data Table with multiple Columns from the Tomahawk tag library for the Description.
  5. Paste this in the Wrapper pattern:
<${t}:dataTable id="${id}" value="#{${value}}" var="${var}">
	${iterativeTemplate}
</${t}:dataTable>
  1. Paste this in the Iterative pattern:
<${t}:column id="${id}column">
	${propertyTemplate}
</${t}:column>
  1. Click OK.
  2. Save the Library Definition.
Figure 8. Data Table template
Completed Iterative Template window

Now that you have a template, use it.

  1. Switch to createControls.jsp.
  2. In Page Data view, expand Faces Managed Beans > emp (com.MyCompany.TestEmployee) > employee (com.MyCompany.Employee)
  3. Click positionsHeld and drag it to the page.
  4. Drop it below the HTML table.

The Insert JavaBean window will appear

  1. Find the Data control to create combo box and select Tomahawk Data Table.
  2. In the Control Type column, change all of the three rows from Display Text to Tomahawk Output Text.
  3. Click Finish.

A three-column data table was generated. Because positionsHeld has three properties (payrollCode, positionCode, and title), one column was generated for each.

This page (Figure 9) now shows the employee's name and her past positions. All of the controls were created based on the data that you wanted to display, and were automatically generated for you.

Figure 9. Data table
Visualization and source tags for a three-column data table

Editing a template in preferences

What if you wanted to look at all of the data templates available in Rational Application Developer (not just the ones that you created in your Library Definition)? To see all of the templates, you can look in Rational Application Developer's preferences.

  1. Go to Window > Preferences.
  2. Expand Web > JavaServer Faces Tools > Generation Templates.

The three sub-pages (Data Templates, Iterative Templates, and Method Templates) contain all of the data templates. This includes both the standard templates that come with Rational Application Developer, and the templates that you created while running the exercises in this article.

Let's look for your Output Text template, and make a small modification to it. Because this is a Property Template (a simple template) it can be found under Data Templates.

  1. Click Data Templates.

The Show combo box allows you to filter by the origin of templates. Filter out everything but your Tomahawk templates.

  1. Change the Show combo box to Tomahawk.

Now only your Tomahawk template will appear in the list, as shown in Figure 10.

Figure 10. Preferences
Tomahawk Output Text template in the Preferences window

Edit this template and add a styleClass attribute.

  1. Select the template and click Edit.
  2. In the Pattern field, add this after the value attribute: styleClass="outputText"
  3. You should now have this pattern:
<${t}:outputText id="${id}" value="#{${value}}" 
styleClass="outputText"></${t}:outputText>
  1. Click OK twice.

Now you can see the results of your change.

  1. In the Page Data view, expand Faces Managed Beans >emp (com.MyCompany.TestEmployee) > employee (com.MyCompany.Employee)
  2. Click name and drag it to the page.
  3. Drop it at the very bottom of the page.

The Insert JavaBean window will appear.

  1. Change the Control Type combo box to Tomahawk Output Text.
  2. Click Finish.

A new HTML table has been generated. The output text inside this table will have the styleClass attribute.

  1. Save the page.

Examine the original template back in the Library Definition.

  1. Switch to the Library Definition.
  2. Click Faces Library Definition > Data Templates > Tomahawk Output Text (Property Template).

Over on the right you can see this template's pattern. This pattern is the original pattern that you entered. It does NOT contain the additional styleClass attribute. This is because template modifications made in Preferences are not written back to the Library Definition. Library Definitions are designed to be shared among team members. If a template modification would be useful to others, then it should be made and saved in the library definition. If, however, it is something that you only need temporarily, or that no one else needs, you can make the modification privately in your preferences. Modifications made in the Preferences window override the templates read from the Library Definition.


Binding to controls

Now that you have seen how to generate controls from scratch, you will learn how to bind to existing controls. Adding controls one at a time and then binding to them afterwards takes longer, but it does allow you greater control over your page.

  1. Open existingControls.jsp.
  2. In the Palette view, ensure that the Tomahawk drawer is expanded and open.
  3. Locate the Output Text control and drag it to the page.

A t:outputText control was added to the page. Now you will bind the employee's name to this output text.

  1. In Page Data view, expand Faces Managed Beans >emp (com.MyCompany.TestEmployee) > employee (com.MyCompany.Employee)
  2. Click name and drag it over to the outputText.
  3. As you hover over outputText you should see a box that says "Drop here to bind name to the control text1".
  4. Drop the name on top of outputText.

This bound the outputText to the employee's name by adding this value attribute: value="#{emp.employee.name}"

Why did this work? How did Rational Application Developer know to bind the value attribute? To find out, look at the library definition.

  1. Save the page.

Data Binding section of a library definition

  1. Switch to the Library Definition.
  2. Expand Faces Library Definition > Tag Library (Tomahawk) > outputText.
  3. Click Data Binding.

This section controls how and when Rational Application Developer will bind data to controls, and consists of four controls:

  • A check box labeled Binds to multi-valued data (Collection or array)
  • A Default attribute for binding combo box that lists all of the outputText's attributes as options
  • An Attribute for repeating values combo box that also lists all of the outputText's attributes as options
  • A Behavior for drops from Page Data view combo box. The three options in this combo box are Bind, Insert child controls, and Bind and insert child controls.

You should select the Binds to multi-valued check box if the control would normally bind to a collection or array (that is, if the data is multi-valued). For example, a Data Table control normally binds to a collection or array, so Data Table controls should have this box selected.

The Default attribute combo box sets the primary attribute on the control for data binding. If data is dropped from the Page Data view onto the control, the Default attribute chosen here will be bound to the data. In many cases, the value attribute should be selected.

The Attribute for repeating values is normally used in conjunction with the Binds to multi-valued data check box. If a control binds to a collection and can accept children, then the value binding of the children is often determined based on a repeating value attribute. For example, Data Table controls usually have a var attribute. For a Data Table control, the Binds to multi-valued option would be selected, and Attribute for repeating values would be set to var.

The Behavior combo is used when data is dragged from the Page Data view onto a control. If this is set to Bind, then the data will simply be bound to the control. If it is set to Insert, then new child controls will be generated inside of the targeted control. If it is set to Both, then the targeted control will be bound and the new child controls will be generated inside of the targeted control. You will explore all of these options in more detail below.

For your outputText control:

  • Binds to multi-valued is cleared because this control would normally bind to a single Java object and not to a collection.
  • The Default attribute is value (as you saw, the employee's name was bound to the value attribute).
  • The Attribute for repeating values is blank because it is not needed.
  • The Behavior is set to Bind.

These selections were already made for you when the Faces Library Definition was created. That's because Rational Application Developer attempts to examine the selected tag library and choose sensible defaults. However, there are many instances where you would want to go beyond these defaults and perform further configurations yourself.


Inserting new child controls

What if you want to create new child controls inside of the targeted control? Panel controls often contain other controls. Now you will customize a Panel Grid and then add a control for the employee's name inside of it.

  1. Expand Faces Library Definition > Tag Library (Tomahawk) > panelGrid
  2. Click Data Binding.
  3. By default, the Behavior for drops from Page Data view is set to Bind. Change this to Insert child controls.
  4. Save the Faces Library Definition.
  5. Switch back to existingControls.jsp.
  6. Drag a Panel Grid from the Tomahawk drawer of the Palette onto the page.
  7. In the Page Data view, expand Faces Managed Beans >emp. (com.MyCompany.TestEmployee) > employee (com.MyCompany.Employee)
  8. Click name.
  9. Drag name to the page and drop it on the panelGrid.
  10. In the Insert JavaBean window, change the combo box in the Control Type column to Tomahawk Output Text.
  11. Click Finish.

What happened here? An Output Text was added inside of the Panel Grid, but an HTML table was added as well. What if you only wanted the Output Text? You could manually delete the HTML table tags from source, or you could configure the Faces Library Definition so that it can use this configuration on other pages and in other projects. Let's configure the Faces Library Definition.

  1. Go to Edit > Undo to remove the HTML table from the page.

If you want to specially format the child controls, you will need to create a special Child Tags template for them. This template is similar to other Data Templates used in Rational Application Developer.

  1. Switch back to the Faces Library Definition.
  2. Click Library Definition > Tag Library (Tomahawk) > panelGrid
  3. Click the Add button.
  4. In the Add Item window, click Child Tags.
  5. Click OK.

The Edit Template window is displayed.

  1. Enter Panel Grid Child for the Name.
  2. Enter Formatting for the child of a Panel Grid in the Description.

The pattern for this template will be very simple: the only thing that you want to generate as a child is the Input Text control.

  1. Click the Insert Variable button and select ${propertyTemplate}, as shown in Figure 11.
Figure 11. Panel grid child tags
Name, Description, and Pattern.
  1. Click OK.
  2. Save the Faces Library Definition.
  3. Switch back to existingControls.jsp.
  4. In the Page Data view, click name.
  5. Drag name to the page and drop it on the panelGrid.
  6. In the Insert JavaBean window, change the combo box in the Control Type column to Tomahawk Output Text.
  7. Click Finish.

Success! This time the only child is a new Output Text control.

  1. Save the page.

Data binding to a data table

Now let's take a look at a more complex control: Data Table. Data Table controls are often used in conjunction with Column controls, so you will configure the Data Binding sections of both Data Table and Column in our Faces Library Definition.

First you will configure the Data Binding section for a Data Table.

  1. Switch to the Library Definition.
  2. Expand Faces Library Definition > Tag Library (Tomahawk) > dataTable.
  3. Click Data Binding.

Looking at this section, Rational Application Developer has already automatically made some selections for you:

  • Binds to multi-valued is selected
  • The Default attribute is value
  • The Attribute for repeating value is var.

All of this means that if you were to drag an array from that Page Data view onto a Data Table, the result would look something like this code:

<t:dataTable styleClass="dataTable" id="table1"
value="#{emp.employee.positionsHeld}" var="varpositionsHeld">
</t:dataTable>

This is good, but you can make it better. You can configure your Library Definition to automatically add columns.

  1. Change the Behavior for drops from Page Data view to Bind and insert child controls.

You now need to add a Child template, just as you did for the panelGrid.

  1. Click Faces Library Definition > Tag Library (Tomahawk) > dataTable
  2. Click the Add button.
  3. In the Add Item window, select Child tags.
  4. Click OK.

In the Edit Template window, you will create a template for a column.

  1. Enter Column for the Name.
  2. You can leave the description blank (template descriptions are optional).
  3. For the pattern, paste this code, as shown in Figure 12:
<${t}:column styleClass="column" id="${id}column">
	${propertyTemplate}
</${t}:column>
  1. Click OK.
  2. Save the Library Definition.
Figure 12. Column child tag
Completed Edit Template window for Data Table

This pattern is very similar to the pattern that you used for the iterative template of your Data Table data template earlier. That is because child tags are actually Iterative templates.

  1. Switch back to existingControls.jsp.
  2. Drag a Data Table from the Tomahawk drawer of the Palette and add it to the page below the Panel Grid.
  3. In the Page Data view, expand Faces Managed Beans >emp (com.MyCompany.TestEmployee) > employee (com.MyCompany.Employee)
  4. Click positionsHeld and drag it to the page.
  5. Drop it on the Data Table.
  6. In the Insert JavaBean window, change all of the combo boxes in the Control Type column to Tomahawk Output Text.
  7. Click Finish in the wizard.

The Data Table will now contain three columns, as shown in Figure 13.

Figure 13. Data Table with new columns
Data Table with three columns

The dataTable's value and var attributes were generated, and bound to the positionsHeld array, and then columns were generated inside of this data Table. Each column contains an outputText (propertyTemplate), and the value of the outputText makes use of the var of the dataTable.

To carry your configuration of the Tomahawk Library Definition further, you might also configure the Data Binding section of the Column control. Because a user might want to drop data onto the column control and generate a new Input or Output text inside of it, you can set the Behavior combo box for Column to Insert. In addition, a new Child Tags template could be created with the content: ${propertyTemplate}.


What you have learned

With Data templates and Faces Library Definitions, Rational Application Developer makes it easy for you to configure a third-party JavaServer Faces tag library. You can either create the Data templates first and generate new controls from them, or you can add controls manually and then bind them to data. Either way, Rational Application Developer provides a rich set of tools to help you customize the experience for your individual needs.


Download

DescriptionNameSize
Sample data for this article624_Employee.zip2KB

Resources

Learn

Get products and technologies

Discuss

Comments

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


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational, DevOps
ArticleID=505483
ArticleTitle=Customized data binding to third-party JavaServer Faces controls in Rational Application Developer
publish-date=08102010