Skip Headers
Oracle® Application Development Framework Developer's Guide
10g (10.1.3.1.0)

Part Number B28967-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

5.2 Using the Data Control Palette

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 View > Data Control Palette. 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 data controls created from EJB session facades.


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

Sample Data Control Palette

5.2.1 How to Understand the Items 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 built-in 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.

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

Icon Name Description Used to Create...

Data control icon.


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.

Not used to create anything. Serves as a container for the other objects.

Create method icon.


Create Method

Represents a built-in method that creates a new instance of an object in a data collection. 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 in which the object will be created. If the objects in a collection contain an attribute from another collection (called a foreign key in relational databases), that attribute is represented by an accessor return icon. I this case, the accessor returns a single value and has no children. For more information about using constructors, see Section 10.7, "Creating an Input Form for a New Record".

Creation forms

Method icon


Method

Represents a custom method on the data control that may accept parameters, perform some action or business logic, and return single values or data collections.

If the method is a get method of a Map and returns a value or a 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 more information about using methods that accept parameters, see Section 10.6, "Creating a Form or Table Using a Method that Takes Parameters".

Command components

For methods that accept parameters: command components and parameterized forms

Method return icon.


Method Return

Represents an object that is returned by a custom method. The returned object may be a single value or a collection. 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 collections: forms, tables, trees, and range navigation components

For single values: text fields and selection lists

Collection icon.


Accessor Return

Represents an object returned by an 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 accessor returns and master-detail objects, see Chapter 8, "Displaying Master-Detail Data".

The children under an accessor return may be attributes of the object, other accessor returns, custom methods that return a value from the accessor return, and operations that can be performed on the accessor return.

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


Attribute

Represents a discrete data element in an object. Attributes appear as children under the method returns or accessor returns to which they belong.

Label, text field, and selection list components.

Data control operation icon.


Operation

Represents a built-in data control operation that performs actions on the parent object. 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.

If an operation requires one or more parameters, they are listed in a Parameters folder under the operation.

UI actions such as buttons or links.

Parameter icon.


Parameter

Represents a parameter value that is declared by the method or operation under which it appears. Parameters appear in the Parameters folder under a method or operation.

Label, text, and selection list components.


5.2.2 How to Use 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 of all the default 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 only one type of component—creation forms.

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


Tip:

By default, the Data Control Palette context menu displays only ADF Faces components. 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

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 from the context menu, 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

Databound UI Component

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 a data collection iterator through an iterator binding. The selection facet was included by selecting the Enable Selection option in the Edit Table Columns dialog, which appears after you drop the table component. (Binding expressions are discussed later in Section 5.6, "Creating ADF Data Binding EL Expressions".)

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

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


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 delete a databound component from a page, if the related binding objects in the page definition file are not referenced by any other component, JDeveloper automatically deletes those binding objects for you.

5.2.3 What Happens When You Use 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 configure these various files yourself. However, when you use the Data Control Palette, JDeveloper does all the required steps for you, which are:

  • Create a DataBindings.cpx file in the view package in the Application Sources directory (if one does not already exist), and add an entry for the page.

    The DataBindings.cpx file defines the binding context for the application. It maps individual pages to their corresponding page definition files and registers the data controls used by those pages. The data controls are 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> 
    
    

    The ADF 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, which are 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.3, "What Happens at Runtime: The JSF and ADF Lifecycles".

  • 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, the name of 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 runtime access to all the ADF binding objects. In later chapters, you will see how the page definition files are used to define and edit the binding object definitions 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 definitions of the binding objects referenced by the page.

  • Add prebuilt components to the JSF page.

    These prebuilt components include ADF data binding expression language (EL) expressions that reference the binding objects in the page definition file. For more information, see Section 5.6, "Creating ADF Data Binding EL Expressions".

  • Add all the libraries, files, and configuration elements required by ADF Faces components, if ADF Faces components are used. For more information, see Section 4.4.2, "What Happens When You First Insert an ADF Faces Component".

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 contains a list 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, 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 the application pages. There is one page definition for each page. For information about the ADF lifecycle, see Section 6.2.3, "What Happens at Runtime: The JSF and ADF Lifecycles".

Figure 5-4 ADF Binding File Runtime Usage

ADF Binding File Runtime Usage