5.2 Using the Data Control Palette to Create Databound UI Components

You can design a databound user interface by dragging an item from the Data Control Palette and dropping it on a page as a specific UI component. When you use the Data Control Palette to create a UI component, JDeveloper automatically creates the various code and objects needed to bind the component to the data control you selected.

To display the Data Control Palette, open a JSF page in the Design page of the visual editor and choose Data Control Palette from the View menu. By default, JDeveloper displays the Data Control Palette in the same window as the Component Palette. Figure 5-1 shows the Data Control Palette for the SRDemo application, which uses TopLink as the business service and a data control created from an EJB session facade.

Note:

If no data controls have been created for the application's business services, the Data Control Palette will be empty. For information about creating data controls, see Chapter 3, "Building and Using Application Services".

Figure 5-1 Data Control Palette

5.2.1 What You See on the Data Control Palette

The Data Control Palette shows all the data controls that have been created for the application's business services and exposes all the data objects, data collections, methods, and operations that are available for binding to UI components. A data collection represents a set of data objects (also known as a rowset) in the data model. Each object in a data collection represents a specific structured data item (also known as a row) in the data model.

Each root node in the Data Control Palette represents a specific data control. Under each data control is a hierarchical list of objects, collections, methods, and operations. How this hierarchy appears on the Data Control Palette depends on the type of business service represented by the data control and how the business services were defined. For more information about data controls, see Section 3.10, "Exposing Services with ADF Data Controls".

In the Data Control Palette, each data control object is represented by a specific icon. Table 5-1 describes what each icon represents, where it appears in the Data Control Palette hierarchy, and what components it can be used to create.

Table 5-1 The Data Control Palette Icons and Object Hierarchy

Name	Description	Used to Create...
Data Control	Represents a data control. You cannot use the data control itself to create UI components, but you can use any of the child objects listed under it. Depending on how your business services were defined, there may be more than one data control, each representing a logical grouping of data functions. For example, in the SRDemo application, there are three data controls: `SRPublicFacade`, `SRAdminFacade`, and `SRDemoFAQ`.	Not used to create anything. Serves as a container for the other objects.
Create Method	Represents a built-in method that creates a new instance of an object in a data collection using the new Java constructor call. Create method icons are located in a folder named after the data collection to which they belong. These data collection folders are located in the Constructors folder under the data control. The Attributes folder, which appears as a child under a create method, contains all the attributes of the data collection. If the collection contains an attribute from another collection (called a foreign key in relational databases), that attribute is represented by an accessor return icon. In this case, the accessor returns a single object. For more information about using constructors, see Section 10.7, "Creating an Input Form for a New Record". For example, in the SRDemo Data Control Palette, shown in Figure 5-1, `ExpertiseArea()` is a built-in method that creates a new `expertiseArea` object in the `ExpertiseArea` collection.	Creation forms.
Method	Represents a custom method on the data control that may accept parameters, perform some action or business logic, and return data or data collections. If the method is a `get` method of a `map` and returns a data collection, a method return icon appears as a child under it. If a method requires a parameter, a folder appears under the method, which lists the required parameters. For example, in the SRDemo Data Control Palette, shown previously in Figure 5-1, `findAllProduct()` is a method that retrieves all products from the database.	UI actions such as buttons or links.
Method Return	Represents a data collection that is returned by a custom method. A method return appears as a child under the method that returns it. The objects that appear as children under a method return may be attributes of the collection, accessor returns that represent collections related to the parent collection, other methods that perform actions related to the parent collection, and operations that can be performed on the parent collection. For example, in the SRDemo Data Control Palette shown previously in Figure 5-1, `Product` is the data collection of all users returned by the `findAllProduct()` method.	Forms, tables, trees, and range navigation components.
Accessor Return	Represents an object returned by a bean-style accessor method on the business service. An accessor method is used when the objects returned are JavaBeans. Accessor returns appear as children under method returns, other accessor returns, or in the Attributes folder under built-in create methods. Accessor returns are objects that are related to the current object in the parent collection. This relationship is usually based on a common unique attribute in both objects. For example, if a method returns a collection of users, an accessor return that is a child of that collection might be a collection of service requests that are assigned to a particular user. In ADF, the relationship between parent and child collections is called a master-detail relationship. For more information about master-detail objects, see Chapter 8, "Working with Master-Detail Relationships". Accessor returns can be either collections or single objects. For example, if a method returns a collection of service requests, one accessor return under that method might be a collection of service history details for the current service request, while another accessor return might be a single user assigned to the current service request. By default, when data controls are created from TopLink POJOs (or session beans over POJOs), the names of accessors that return collections end in `Collection`. For example, `serviceHistoryCollection`. The UI components available from the Data Control Palette context menu differ depending on whether the accessor return is a collection or a single object. The children under an accessor return may be attributes of the collection or object, other accessor returns, custom methods that return a value from the collection or object, and operations that can be performed on the collection or object. The accessor returns under a built-in create method are always a single object and never have any children. For example, in the SRDemo Data Control Palette shown previously in Figure 5-1, `serviceRequestCollection` is an accessor return of the service requests associated with a specific product in the `Product` data collection.	For collections: Forms, tables, trees, range navigation components, and master-detail widgets. For single objects: Forms, master-detail widgets, and selection lists. For single objects under a constructor: selection lists only.
Attribute	Represents a discrete data element in an object. Attributes appear as children under method returns or accessor returns. For example, in the SRDemo Data Control Palette, shown in Figure 5-1, `description`, `image`, `name`, and `prodId` are attributes of the `Product` data collection returned by the `findAllProduct()` method.	Label, text field, and selection list components.
Operation	Represents a built-in data control operation that performs actions on the parent object. If an operation requires a parameter, a folder appears under the method, which lists the required parameters. Data control operations are located in an Operations folder under method returns or accessor returns and under the root data control node. The operations that are children of a particular method or accessor return operate on that return object only, while operations under the data control node operate on all the objects represented by the data control. For example, in the SRDemo Data Control Palette, shown in Figure 5-1, `create`, `execute`, `find`, `first`, `last` are operations that perform actions on the `Product` data collection, which is the return of the `findAllProduct()` method.	UI actions such as buttons or links.
Parameter	Represents a parameter value that is declared by the method or operation under which it appears. Parameters appear in a folder under a method or operation. For example, in the SRDemo Data Control Palette shown in Figure 5-1, the `problemDescription`, `productId`, and `createdBy` are parameters for the `createServiceRequest()` method.	Label, text, and selection list components.

5.2.2 How to Create Databound UI Components Using the Data Control Palette

To create a databound UI component, drag an item from the Data Control Palette and drop it on a JSF page.

When you drag an item from the Data Control Palette and drop it on a page, JDeveloper displays a context menu with all the UI components available for the item you dropped. From the context menu, select the component you want to create.

Note:

When you drag and drop a built-in create method from the Data Control Palette, the context menu does not appear. This is because create methods can be used to create one type of component—creation forms.

Figure 5-2 shows the context menu displayed when a data collection represented by a method return on the Data Control Palette is dropped on a page.

Tip:

By default, the Data Control Palette context menu displays ADF Faces components only. However, you can use equivalent JSF components instead. To have JSF components appear in the Data Control Palette context menu, select the Include JSF HTML Widgets for JSF Databinding option in the ADF View Settings page of the project properties. However, using ADF Faces components, especially with ADF bindings, provide greater functionality than JSF components.

Figure 5-2 Data Control Palette Context Menu

Depending on the component you select from the context menu, JDeveloper may display a dialog that enables you to define how you want the component to look. For example, if you select ADF Read-only Table, the Edit Table Columns dialog appears. This dialog enables you to define which attributes you want to display in the table columns, the column labels, what types of text fields you want use for each column, and what functionality you want to include, such as selection facets or column sorting. (For more information about creating tables, see Chapter 7, "Adding Tables".)The resulting UI component appears in the JDeveloper visual editor. For example, if you drag a method return from the Data Control Palette, and choose ADF Read-only Table from the context menu, a read-only table appears in the visual editor, as shown in Figure 5-3.

Figure 5-3 Databound UI Component: ADF Read-only Table

Notice that the column labels in the sample table contain binding expressions, which bind each column label to an attribute in the data collection. The default table includes a selection facet, which is bound to the data collection iterator. The selection facet was included by selecting an option in the Edit Table Columns dialog, which appears after you drop the table component. (Binding expressions are discussed later in Section 5.6, "Using ADF Databinding EL Expressions".)

By default, the UI components created when you use the Data Control Palette use ADF Faces components, are bound to the ADF data control, and may have one or more built-in features including:

Databound labels
Tooltips
Formatting
Type safety
Basic navigation buttons
Validation (if validation rules are attached to a particular attribute; see Chapter 12, "Using Validation and Conversion" for information about validation)

The default components are fully functional without any further modifications. However, you can modify them to suit your particular needs. Each component and their various features are discussed further in the remaining chapters of this book.

Tip:

If you want to change the type of ADF databound component used on a page, the easiest method is to delete the component and drag and drop a new one from the Data Control Palette. When you do this, JDeveloper automatically removes all the binding objects related to the deleted component.

5.2.3 What Happens When You Create a Component From the Data Control Palette

While an ADF web application is built using the JSF framework, it requires a few additional application object definitions to render and process a page containing ADF databound UI components. If you do not use the Data Control Palette, you will have to manually enter these object definitions yourself. However, when you use the Data Control Palette, JDeveloper does all the required steps for you, which are:

Add a DataBindings.cpx file to the view package in the Application Sources directory (if one does not already exist), and an entry is added for the page.

The DataBindings.cpx file maps individual pages to the binding definitions in the page definition file and references the data controls defined in the DataControls.dcx file. For more information, see Section 5.3, "Working with the DataBindings.cpx File".
Register the ADF binding filter in the web.xml file.

The ADF binding filter preprocesses any HTTP requests that may require access to the binding context. For more information about the binding filter configuration, see Section 5.4, "Configuring the ADF Binding Filter".
Register the ADF phase listener in the faces-config.xml file, as shown in Example 5-1.
Example 5-1 ADF Phase Listener Entry in the faces-config.xml File
```
<lifecycle>
   <phase-listener>oracle.adf.controller.faces.lifecycle.ADFPhaseListener
   </phase-listener>
</lifecycle> 
```
Because the default UI components created by the Data Control Palette are ADF Faces components, the ADF phase listener is added to the faces-config.xml file. The phase listener is used to execute the ADF page lifecycle. It listens for all the JSF phases before which and after which it needs to execute its own phases concerned with preparing the model, validating model updates, and preparing pages to be rendered. For more information about the ADF lifecycle, see Section 6.2.2.4, "The JSF and ADF Lifecycles".
Register the default ADF render kit in the faces-config.xml file, as shown in Example 5-2.

The ADF render kit is needed to properly render UI components that are bound to ADF data controls. For more information about the ADF lifecycle, see Section 6.2.2.4, "The JSF and ADF Lifecycles".
Example 5-2 ADF Render Kit Entry in the faces-config.xml File
```
<application>
   <default-render-kit-id>oracle.adf.core</default-render-kit-id>
</application>  
```
Add the following ADF runtime libraries to the project properties of the view project:
- ADF Model Runtime (ADFm.jar)
- ADF Controller (adf-controller.jar)
Add a page definition file (if one does not already exist for the page) to the page definition subpackage, which is defined in the ADFm settings of the project properties. The default subpackage is view.pageDefs in the Application Sources directory.

The page definition file (<pageName>PageDef.xml) defines the ADF binding container for each page in an application's view layer. The binding container provides access to all the ADF binding objects currently used by a page. In later chapters, you will see how the page definition files are used to define and edit the bindings for specific UI components. For more information about the page definition file, see Section 5.5, "Working with Page Definition Files".
Configure the page definition file, which includes adding the definitions for the binding objects referenced by the page.
Add prebuilt UI components to the JSF page.

These prebuilt UI components use JSF or ADF Faces tags and ADF databinding expression language (EL) expressions that reference the binding object in the page definition file. For more information, see Section 5.6, "Using ADF Databinding EL Expressions".

5.2.4 What Happens at Runtime

When a page contains ADF bindings, at runtime, the interaction with the business services initiated from the client or controller is managed by the application through a single object known as the Oracle ADF binding context. The ADF binding context is a container object that defines a hierarchy of data controls and data binding objects derived from the Oracle ADF Model layer. The ADF lifecycle creates the Oracle ADF binding context from the DataControls.dcx, DataBindings.cpx, and page definition files created when you use the Data Control Palette, as shown in Figure 5-4. The DataControls.dcx file defines all the data controls available to the application. The DataBindings.cpx file references the data controls that are currently being used by pages in the application and maps the binding containers, which contain the binding objects defined in the page definition files, to web page URLs. The page definition files define the binding objects used by a page. For information about the ADF lifecycle, see Section 6.2.2.4, "The JSF and ADF Lifecycles".

Figure 5-4 ADF Binding File Runtime Usage