Skip Headers
Oracle® Application Development Framework Developer's Guide For Forms/4GL Developers
10g (10.1.3.1.0)

Part Number B25947-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

12.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 12-1 shows the Data Control Palette for the SRDemo application, which uses ADF Business Components as the business service.


Note:

If your Data Control Palette is empty, be sure that you have created view objects for the data you want to access and have added those view objects to an application module. For information about creating view objects and application modules, see Chapter 5, "Querying Data Using View Objects".

Figure 12-1 Data Control Palette

Sample Data Control Palette

12.2.1 How to Understand the Items on the Data Control Palette

The Data Control Palette lists all the data controls that have been created for the application's business services and exposes all the 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. Throughout this guide, the term data collection and collection are used interchangeably.

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 example, in an application that uses ADF Business Components to define the business services, each data control on the Data Control Palette represents a specific application module, and exposes the view object instances in that application's data model. The hierarchy of objects in the data control is defined by the view links between view objects that have specifically been added to the application module data model. For information about creating view objects and view links, see Chapter 5, "Querying Data Using View Objects". For information about adding view links to the data model, see Section 5.10.4.3, "How to Enable Active Master/Detail Coordination in the Data Model".

In the Data Control Palette, each data control object is represented by a specific icon. Table 12-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 12-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.

Usually, there is one data control for each application module. However, you may have additional data controls that were created for other types of business services (for example, for CSV files or web services). For information about creating data controls for CSV files, see Chapter 31, "Creating Data Control Adapters". For information about creating data controls for web services, see Chapter 33, "Working with Web Services".

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

Method icon


Method

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

In application module data controls, custom methods are defined in the application module itself and usually return either nothing or a single scalar value. For more information about creating custom methods, see Chapter 8, "Implementing Business Services with Application Modules".

For more information about using methods that accept parameters, see Section 17.3.2.1, "Using Parameters in a Method".

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 can be a single value or a collection.

If a custom method defined in the application module returns anything at all, it is usually a single scalar value. Application module methods do not need to return a set of data to the view layer, because displaying the latest changes to the data is handled by the view objects in the active data model (for more information, see Section 4.5, "Understanding the Active Data Model". However, custom methods in non-application module data controls (for example, a data control for a CSV file) can return collections to the view layer.

A method return appears as a child under the method that returns it. The objects that appear as children under a method return can be attributes of the collection, other methods that perform actions related to the parent collection, and operations that can be performed on the parent collection.

For single values: text fields and selection lists

For collections: forms, tables, trees, and range navigation components

Collection icon.


View Object Collection

Represents a named data collection, which is the default rowset contained in a view object instance. The name of the collection matches the view object instance name.

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. Throughout this guide, data collection and collection are used interchangeably.

A view link creates a master-detail relationship between two view objects. If you explicitly add an instance of a detail view object (resulting from a view link) to the application module data model, the collection contained in that detail view object appears as a child of the collection contained in the master view object. For information about adding detail view objects to the data model, see Section 5.10.4.3, "How to Enable Active Master/Detail Coordination in the Data Model". For more information about using master-detail relationships to create UI components, see Chapter 15, "Displaying Master-Detail Data".

The children under a collection may be attributes of the collection, other collections that are related by a view link, custom methods that return a value from the collection, and built-in operations that can be performed on the collection.

Forms, tables, trees, range navigation components, and master-detail components

Attribute icon.


Attribute

Represents a discrete data element in an object (for example, an attribute in a view row). Attributes appear as children under the collections or method returns to which they belong.

Only the attributes that were included in the view object are shown under a collection. If a view object joins one or more entity objects, that view object's collection will contain selected attributes from all of the underlying entity objects.

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 collections or method returns and under the root data control node. The operations that are children of a particular collection or method return operate on those objects only, while operations under the data control node operate on all the objects in 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.


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

Figure 12-2 shows the context menu displayed when a collection from the Data Control Palette is dropped on a page.

Figure 12-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 14, "Adding Tables".)

The resulting UI component appears in the JDeveloper visual editor. For example, if you drag a collection 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 12-3.

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

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

12.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 the binding definitions in the page definition file and registers the data controls used by those pages. For more information, see Section 12.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 12.4, "Configuring the ADF Binding Filter".

  • Register the ADF phase listener in the faces-config.xml file, as shown in Example 12-1.

    Example 12-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 13.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 12.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 12.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 11.4.2, "What Happens When You First Insert an ADF Faces Component".

12.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 DataBindings.cpx file and page definition files, as shown in Figure 12-4. The application modules define the data controls available to the application at design time, but the DataBindings.cpx file defines what data controls are available to the application at runtime. The DataBindings.cpx file lists all the data controls that are 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 the application pages. There is one page definition file for each page. For information about the ADF lifecycle, see Section 13.2.3, "What Happens at Runtime: The JSF and ADF Lifecycles".

Figure 12-4 ADF Binding File Runtime Usage

ADF binding file runtime usage