13.2 Designing Pages for ADF Bindings

When designing and creating a web page that will have ADF bindings added later, use the JDeveloper wizards, visual editors, and design tools (such as the Component Palette).

You can design your pages using any tags that you want; however, if you plan to add ADF bindings to certain components, you may want to design those components using tags that work with ADF bindings. Otherwise, the components will have to be entirely replaced when the bindings are added later.

When you add ADF bindings to an existing component, ADF preserves as much of the original component's properties as possible. However, the binding may overwrite such things as labels, column headings, and range navigation.

If a label value contains a static text string, the ADF binding overwrites the value with an EL expression that binds to an attribute name in the data control. However, if you define your UI labels using EL expressions that reference managed beans (for example, a standard binding on a resource bundle), that label is preserved when you add the ADF binding to that component. In many cases, it is preferable to design your basic UI components using labels that are bound to resource bundles, especially if you will be localizing your pages. For more information about resource bundles, see Section 14.4, "Internationalizing Your Application".

Range navigation is another property that is overwritten by the ADF binding, because the iterator referenced by the binding manages the current rowset. Later sections in this chapter discuss how to add ADF bindings to specific UI components and how those specific components are affected by the ADF bindings.

13.2.1 Creating the Page

When you use the Create JSF JSP wizard to create a page to which you intend to add ADF bindings, be sure to do the following actions to make future binding easier:

Choose the Do not Automatically Expose UI Components in a Managed Bean option.

This option turns off JDeveloper's auto-binding feature, which automatically associates every UI component in the page to a corresponding property in the backing bean for eventual programmatic manipulation. If you intend to add ADF bindings to a page, Oracle recommends that you do not use the auto-binding feature. If you use the auto-binding feature, you will have to remove the managed bean bindings later, after you have added the ADF bindings. The managed bean UI component property bindings do not affect the ADF bindings, but their presence may be confusing in the JSF code. For information about managed beans, see Section 4.5, "Creating and Using a Backing Bean for a Web Page".
Add the ADF Faces tag libraries.

While you can add ADF bindings to JSF components, the ADF Faces components provide greater functionality, especially when combined with ADF bindings.
Add the desired page-level physical attributes such as background color, style sheets, or skins.

The ADF bindings do not affect your page-level attributes. For information about using ADF Faces skins, see Section 14.3, "Using Skins to Change the Look and Feel".

13.2.2 Adding Components to the Page

When designing web pages, keep in mind that ADF bindings can be added only to certain ADF Faces tags or their equivalent JSF HTML tags. Table 13-1 lists the ADF Faces and JSF tags to which you can later add ADF bindings. On the Component Palette, the ADF Faces tags are available on the ADF Faces Core page, and the JSF tags are available on the JSF HTML page.

Tip:

To enable the use of JSF Reference Implementation UI component tags with ADF bindings, you must choose the Include JSF HTML Widgets for JSF Databinding option in the ADF View Settings of the project properties. However, using ADF Faces tags, especially with ADF bindings, provides greater functionality than does using the reference implementation JSF tags.

Table 13-1 Tags That Can Be Used for ADF Bindings

ADF Faces Tags Used in ADF Bindings	Equivalent JSF HTML Tags
Text Fields
af:·i`nputText`	`h:inputText`
`af:outputText`	`h:outputText`
`af:outputLabel`	`h:outputLabel`
Tables
`af:table`	`h:dataTable`
Actions
`af:commandButton`	`h:commandButton`
`af:commandLink`	`h:commandLink`
Selection Lists
`af:selectOneChoice`	`h:selectOneMenu`
`af:selectOneListbox`	`h:selectOneListbox`
`af:selecOneRadio`	`h:selectOneRadio`
`af:selectBooleanRadio`	`h:selectBooleanCheckbox`
Trees
`af:tree`	n/a
`af:treeTable`	n/a

13.2.3 Other Design Considerations

When designing pages using the JDeveloper wizards and editors to which you will later add ADF bindings, you can either:

Choose options that enable you to bind later and, instead, enter static labels and values. This approach enables you to design your UI using placeholder labels and values that will be replaced later by the values and labels returned by the ADF bindings.

OR
Bind labels to resource bundles, which contain the actual text to be displayed in the label. When you later add an ADF binding to a component, ADF retains any existing label bindings on resource bundles (or managed beans). For information about using resource bundles, see Section 14.4, "Internationalizing Your Application".

For information about creating JSF and ADF Faces components, see Section 4.4.1, "How to Add UI Components to a JSF Page".

13.2.3.1 Creating Text Fields in Forms

For text field labels, you can either enter static placeholder values or bind to resource bundles. If you are not binding labels to resource bundles, then use the Property Inspector or source editor to add or modify placeholder labels and values in text fields. Use placeholder labels and values that make it easier for the developer, who will later add the bindings, to determine the intent of the field. Static placeholder values will be replaced by the ADF bindings. However, as mentioned previously, any bindings to resource bundles will be retained.

For example, if you are creating a form that displays user information, you might use User First Name, User Last Name, and User Address as placeholder text field labels. The developer who adds the ADF bindings would then match the placeholder labels to actual attributes in a data source on the data control.

13.2.3.2 Creating Tables

When you drag a table component from the Component Palette and drop it on a page, JDeveloper displays a table wizard to help you define the table. Choose the Bind Later option in the ADF Faces Table wizard (or, for JSF tables, the Number of Columns option in the Create Data Table wizard), which enables you to specify the number of columns needed in the table instead of binding to a data source. If you are unsure of the total number of columns needed, enter an estimate. Later, when the bindings are added, the number of columns can easily be adjusted.

As with text fields, use placeholder labels or bindings on resource bundles in the column headings. If you are using the ADF table component, you can specify the column headings in the Header Text field on the Column Details page of the ADF Faces Table wizard. For JSF tables, you can enter the column headings directly in the table displayed in the visual editor.

13.2.3.3 Creating Buttons and Links

For the button or link label, use the Property Inspector or the source editor to add a static placeholder or a binding on a resource bundle. If the button or link will perform page navigation, you can specify an outcome value in the action attribute, to enable page navigation in your initial pages. However, when the ADF bindings are added, the action attribute is overwritten, and the action will have to be re-entered.

13.2.3.4 Creating Lists

When you drag a selection list from the Component Palette and drop it on a page, JDeveloper displays the Insert dialog to help you define the list. Use the Create List option on the Insert dialog to define the list. Only enter item labels or values if you will ultimately create a static list. If you intend to populate the list from a binding on a data collection, leave the item labels and values blank. For the list label, use the Property Inspector to enter a static placeholder or a binding on a resource bundle. For example, if you are creating a dropdown list of products, you might enter Products as the label for the list. Later, when the binding is added, static placeholder labels are replaced by an ADF binding expression.

13.2.3.5 Creating Trees or Tree Tables

When creating trees, use the value attribute to identify the root node and the var value to identify the branch node. When creating a tree table, choose the Bind Later option in the ADF Faces Tree Table wizard. You can specify a number of columns, but when the ADF binding is added all data is displayed in a single column.