| Oracle® Application Development Framework Developer's Guide For Forms/4GL Developers 10g Release 3 (10.1.3.0) Part Number B25947-02 |
|
|
View PDF |
| Oracle® Application Development Framework Developer's Guide For Forms/4GL Developers 10g Release 3 (10.1.3.0) Part Number B25947-02 |
|
|
View PDF |
This chapter describes how to use the Data Control Palette to create databound UI components that display data on a page. It also describes how to work with all the objects that are created when you use the Data Control Palette.
This chapter includes the following sections:
The remaining chapters in this part of this guide describe how to create specific types of pages using databound components.
The ADF data controls provide an abstraction of an application's business services, giving the ADF binding layer access to the service data. An application module data control represents a specific application module and exposes instances of that application module's view objects. Each application module is automatically available as a data control. You can bind UI components to application module data controls to populate a page with data from your active data model at runtime. For more information about application module data controls, see Chapter 10, "Overview of Application Module Data Binding".
The JDeveloper Data Control Palette exposes an application's data controls in the IDE and enables you to use drag and drop to create a variety of UI components on a JSF page. The UI components created by the Data Control Palette use declarative data binding, which means that the data binding expressions are automatically configured and that, in most cases, you do not have to write any additional code.
Read this chapter to understand:
How to use the Data Control Palette to create databound UI components
The items that appear on the Data Control Palette
The objects that JDeveloper creates for you when you use the Data Control Palette
How to construct an ADF data binding EL expression
The content of the page definition file and its relationship to EL expressions
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".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 |
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 |
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 |
|
|
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 |
|
|
|
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 |
|
|
|
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. |
|
|
|
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. |
|
|
|
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. |
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.
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.
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:
Databound labels
Tooltips
Formatting
Basic navigation buttons
Validation (if validation rules are attached to a particular attribute; see Chapter 20, "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 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.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:
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".
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".
The DataBindings.cpx file defines the Oracle ADF binding context for the entire application and provides the metadata from which the Oracle ADF binding objects are created at runtime. It maps individual pages to page definition files and declares which data controls are being used by the application. At runtime, only the data controls listed in the DataBindings.cpx file are available to the current application.
The first time you use the Data Control Palette to add a component to a page in an application, JDeveloper automatically creates the DataBindings.cpx file in the view package of the Application Sources directory of the view project. Once the DataBindings.cpx file is created, JDeveloper adds an entry for the first page. Each subsequent time you use the Data Control Palette to add a component to a page, JDeveloper adds an entry to the DataBindings.cpx for that page, if one does not already exist.
Example 12-2 shows a sample DataBindings.cpx file for the SRDemo application. The pageMap element maps each JSF page to its corresponding page definition file. The pageDefintionUsages element identifies each page definition file in the application. The dataControlUsages element identifies the data controls being used by the binding objects defined in the page definition files. The BC4JDataControl elements within the dataControlUsages element identify the data controls (application modules) being used by the application. The dc elements identify any data control adaptors (for example, data controls for CSV files) being used by the application. For more information about the elements and attributes in the DataBindings.cpx file, see Appendix A, "Reference ADF XML Files".
Example 12-2 DataBindings.cpx File
<?xml version="1.0" encoding="UTF-8" ?>
<Application xmlns="http://xmlns.oracle.com/adfm/application"
version="10.1.3.35.65" id="DataBindings" SeparateXMLFiles="false"
Package="oracle.srdemo.view" ClientType="Generic">
<pageMap>
<page path="/app/SRList.jspx" usageId="app_SRListPageDef"/>
<page path="/app/SRCreate.jspx" usageId="app_SRCreatePageDef"/>
<page path="/app/SRCreateConfirm.jspx" usageId="app_SRCreateConfirmPageDef"/>
...
</pageMap>
<pageDefinitionUsages>
<page id="app_SRListPageDef"
path="oracle.srdemo.view.pageDefs.app_SRListPageDef"/>
<page id="app_SRCreatePageDef"
path="oracle.srdemo.view.pageDefs.app_SRCreatePageDef"/>
<page id="app_SRCreateConfirmPageDef"
path="oracle.srdemo.view.pageDefs.app_SRCreateConfirmPageDef"/>
...
</pageDefinitionUsages>
<dataControlUsages>
<dc id="SRDemoFAQ" path="oracle.srdemo.faq.SRDemoFAQ"/>
<BC4JDataControl id="SRService" Package="oracle.srdemo.model"
FactoryClass="oracle.adf.model.bc4j.DataControlFactoryImpl"
SupportsTransactions="true" SupportsFindMode="true"
SupportsRangesize="true" SupportsResetState="true"
SupportsSortCollection="true"
Configuration="SRServiceLocal" syncMode="Immediate"
xmlns="http://xmlns.oracle.com/adfm/datacontrol"/>
</dataControlUsages>
</Application>
The ADF binding filter is a servlet filter that is an instance of the oracle.adf.model.servlet.ADFBindingFilter class. ADF web applications use the ADF binding filter to preprocess any HTTP requests that may require access to the binding context.
The first time you add a databound component to a page using the Data Control Palette, JDeveloper automatically configures the filter for you in the application's web.xml file.
To configure the binding filter, JDeveloper adds the following elements to the web.xml file:
A Servlet context parameter: Specifies which DataBindings.cpx file the binding filter reads at runtime to define the application binding context.
The servlet context parameter is defined in the web.xml file, as shown in Example 12-0. The param-name element must contain the value CpxFileName, and the param-value element must contain the fully qualified name of the application's DataBindings.cpx file without the .cpx extension.
An ADF binding filter class: Specifies the name of the binding filter object, which implements the javax.servlet.Filter interface.
The ADF binding filter is defined in the web.xml file, as shown in Example 12-4. The filter-name element must contain the value adfBindings, and the filter-class element must contain the fully qualified name of the binding filter class, which is oracle.adf.model.servlet.ADFBindingFilter.
Filter mappings: Link filters to static resources or servlets in the web application.
At runtime, when a mapped resource is requested, a filter is invoked. Filter mappings are defined in the web.xml file, as shown in Example 12-5. The filter-name element must contain the value adfBindings. Notice that in the example there is a filter mapping for both types of page formats: jsp and jspx.
Example 12-5 Filter Mapping Defined in the web.xml File
<filter-mapping>
<filter-name>adfBindings</filter-name>
<url-pattern>*.jsp</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>adfBindings</filter-name>
<url-pattern>*.jspx</url-pattern>
</filter-mapping>
Tip:
If you have multiple filters defined in theweb.xml file, be sure to list them in the order in which you want them to run. At runtime, the filters are executed in the sequence they appear in the web.xml file.At runtime, the ADF binding filter performs the following functions:
Overrides the character encoding when the filter is initialized with the name specified as a filter parameter in the web.xml file. The parameter name of the filter init-param element is encoding.
Instantiates the ADFContext object, which is the execution context for an ADF application and contains context information about ADF, including the security context and the environment class that contains the request and response object.
Serializes incoming HTTP requests from the same browser (for example, from framesets) to prevent multithreading problems.
Notifies data control instances that they are about to receive a request, allowing them to do any necessary per-request setup.
Notifies data control instances after the response has been sent to the client, allowing them to do any necessary per-request cleanup.
Page definition files define the binding objects that populate the data in UI components at runtime. For every page that has ADF bindings, there must be a corresponding page definition file that defines the binding object used by that page. Page definition files provide design time access to all the ADF bindings. At runtime, the binding objects defined by a page definition file are instantiated in a binding container, which is the runtime instance of the page definition file.
The first time you use the Data Control Palette, JDeveloper automatically creates a page definition file for that page and adds definitions for each binding object referenced by the component. For each subsequent databound component you add to the page, JDeveloper automatically adds the necessary binding object definitions to the page definition file.
By default, the page definition files are located in the view.PageDefs package in the Application Sources directory of the view project. You can change the location of the page definition files using the ADFm Settings page of the project properties.
JDeveloper names the page definition files using the following convention:
<pageName>PageDef.xml
where <pageName> is the name of the JSF page. For example, if the JSF page is named SRList.jsp, the default page definition filename is SRListPageDef.xml. If you organize your pages into subdirectories, JDeveloper prefixes the directory name to the page definition filename using the following convention:
<directoryName>_<pageName>PageDef.xml
For example, in the SRDemo application, the name of the page definition file for the SRMain page, which is in the app subdirectory of the Web Content folder is app_SRMainPageDef.xml.
Caution:
TheDataBindings.cpx file maps JSF pages to their corresponding page definition files. If you change the name of a page definition file or a JSF page, JDeveloper does not automatically refactor the DataBindings.cpx file. You must manually update the page mapping in the DataBindings.cpx file.To open a page definition file, right-click on the page in the visual editor or in the Application Navigator, and choose Go to Page Definition.
Example 12-6 shows a sample page definition file that was created for the SRCreate page in the SRDemo application. Notice that the page definition file groups the binding object definitions under the following wrapper elements:
parameters (for more information, see Section 12.5.2.1, "Binding Objects Defined in the parameters Element")
executables (for more information, see Section 12.5.2.2, "Binding Objects Defined in the executables Element")
bindings (for more information, see Section 12.5.2.3, "Binding Objects Defined in the bindings Element")
Each wrapper element contains specific types of binding object definitions. The id attribute of each binding object definition specifies the name of the binding object. Each binding object name must be unique within the page definition file. By default, the binding objects are named after the data control object that was used to create it. If a data control object is used more than once on a page, JDeveloper adds a number to the default binding object names to keep them unique. In Section 12.6, "Creating ADF Data Binding EL Expressions", you will see how the ADF data binding EL expressions reference the binding object names.
Example 12-6 Page Definition File
<?xml version="1.0" encoding="UTF-8" ?>
<pageDefinition xmlns="http://xmlns.oracle.com/adfm/uimodel"
version="10.1.3.35.65" id="app_SRCreatePageDef"
Package="oracle.srdemo.view.pageDefs">
<parameters/>
<executables>
<invokeAction Binds="cancelNewServiceRequest"
id="clearServiceRequestFieldsIfNotInTrain"
Refresh="prepareModel"
RefreshCondition="${adfFacesContext.postback == false and empty
requestScope.processChoice}"/>
<iterator id="ProductListIterator" Binds="ProductList" RangeSize="-1"
DataControl="SRService"/>
<iterator id="GlobalsIterator" RangeSize="10" Binds="Globals"
DataControl="SRService"/>
</executables>
<bindings>
<attributeValues IterBinding="GlobalsIterator" id="ProblemDescription">
<AttrNames>
<Item Value="ProblemDescription"/>
</AttrNames>
</attributeValues>
<list StaticList="false" ListOperMode="0" IterBinding="GlobalsIterator"
ListIter="ProductListIterator" id="ProductList">
<AttrNames>
<Item Value="ProductId"/>
<Item Value="ProductName"/>
</AttrNames>
<ListAttrNames>
<Item Value="ProdId"/>
<Item Value="Name"/>
</ListAttrNames>
<ListDisplayAttrNames>
<Item Value="Name"/>
</ListDisplayAttrNames>
</list>
<attributeValues IterBinding="GlobalsIterator" id="ProductId">
<AttrNames>
<Item Value="ProductId"/>
</AttrNames>
</attributeValues>
<attributeValues IterBinding="GlobalsIterator" id="ProductName">
<AttrNames>
<Item Value="ProductName"/>
</AttrNames>
<methodAction id="cancelNewServiceRequest"
</attributeValues>
InstanceName="SRService.dataProvider"
DataControl="SRService"
MethodName="cancelNewServiceRequest"
RequiresUpdateModel="true" Action="999"/>
</bindings>
</pageDefinition>
In later chapters, you will see how the page definition file is used to define and edit the bindings for specific UI components. For a description of all the possible elements and attributes in the page definition file, see Appendix A, "<pageName>PageDef.xml".
The parameters element of the page definition file defines the parameters for the page.
The parameter binding objects declare the parameters that the page evaluates at the beginning of a request (in the Prepare Model phase of the ADF lifecycle). In a web application, the page parameters are evaluated once during the Prepare Model phase. (For more information about the ADF lifecycle, see Section 13.2.3, "What Happens at Runtime: The JSF and ADF Lifecycles".) You can define the value of a parameter in the page definition file using static values, binding expressions, or EL expressions that assign a static value.
The SRDemo application does not use parameter bindings. However, Example 12-7 shows how parameter binding objects can be defined in a page definition file.
Example 12-7 The parameters Element of a Page Definition File
<parameters>
<parameter id="filedBy"
value="${bindings.userId}"/>
<parameter id="status"
value="${param.status != null ? param.status : 'Open'}"/>
</parameters>
The value of the filedBy parameter is defined by a binding on the userID data attribute, which would be an attribute binding defined later in the bindings wrapper element. The value of the status parameter is defined by an EL expression, which assigns a static value.
Tip:
By default, JDeveloper uses the dollar sign ($), which is a JSP EL syntax standard, as the prefix for EL expressions that appear in the page definition file. However, you can use the hash sign (#) prefix, which is a JSF EL syntax standard, as well.For more information about passing parameters to methods, see Chapter 17, "Creating More Complex Pages".
The executables element of the page definition file defines the following types of executable binding objects:
iterator: Binds to an iterator that iterates over view object collections.
When you drop a collection or an attribute of a collection on the page, an iterator binding is automatically added to the executables element.
methodIterator: Binds to an iterator that iterates over the collections returned by custom methods in the data control.
A method iterator binding is always related to a methodAction binding defined in the bindings element. The methodAction binding encapsulates the details about how to invoke the method and what parameters (if any) the method is expecting. For more information about methodAction bindings, see Section 12.5.2.3, "Binding Objects Defined in the bindings Element".
You will see methodIterator bindings in the executables element only if you drop a method return collection or an attribute of a method return collection from a non-application module data control on the page. If you are using only application module data controls, you will see only iterator bindings.
variableIterator: Binds to an iterator that exposes all the variables in the binding container to the other bindings.
Page variables are local to the binding container and exist only while the binding container object exists. When you use a data control method or operation that requires a parameter that is to be collected from the page, JDeveloper automatically defines a variable for the parameter in the page definition file. Attribute bindings can reference the page variables.
The variableIterator element can contain one of two types of variable definitions: variable and variableUsage. A variable type variable is a simple value holder, while a variableUsage type variable is a value holder that is related to a view object's named bind parameter. Defining a variable as a variableUsage type allows it to inherit the default value and UI control hints from the view object named bind variable to which it is bound.
invokeAction: Binds to a method that invokes the operations or methods defined in action or methodAction bindings during any phase of the page lifecycle.
Action and method action bindings are defined in the bindings element. For more information about methodAction objects, see Section 12.5.2.3, "Binding Objects Defined in the bindings Element".
Iterator binding objects bind to an underlying ADF RowSetIterator object, which manages the current object and current range information. The iterator binding exposes the current object and range state to the other binding objects used by the page. The iterator range represents the current set of objects to be displayed on the page. The maximum number of objects in the current range is defined in the rangeSize attribute of the iterator. For example, if a collection in the data control contains service requests and the iterator range size is 10, the first ten service requests in the collection are displayed on the page. If the user scrolls down, the next set of 10 service requests are displayed, and so on. If the user scrolls up, the previous set of 10 are displayed.
There is one iterator binding for each collection used on the page, but there is only one variablesIterator binding for all variables used on the page. (The variables iterator is like an iterator pointing to a collection that contains only one object whose attributes are the binding container variables.) All of the value bindings on the page must refer to an iterator binding to have the component values populated with data at runtime. (For information about value bindings, see Section 12.5.2.3, "Binding Objects Defined in the bindings Element".)
At runtime, the bindings in the executables element are refreshed in the order in which they appear in the page definition file. Refreshing an iterator binding reconnects it with its underlying RowSetIterator object. Refreshing an invokeAction binding invokes the action. However, before refreshing any bindings, the ADF runtime evaluates any Refresh and RefreshCondition attributes specified in the iterator and invokeAction elements. The Refresh attribute specifies the ADF lifecycle phase within which the executable should be invoked. The RefreshCondition attribute specifies the conditions under which the executable should be invoked. You can specify the RefreshCondition value using a boolean EL expression. If you leave the RefreshCondition attribute blank, it evaluates to true.
For more information about how bindings are refreshed and how to set the Refresh and RefreshCondition attributes, see Section 10.5.5, "How to Use Refresh Correctly for InvokeAction and Iterator Bindings".
Tip:
Use the Structure window to re-order bindings in theexecutables element using drag and drop.Example 12-8 shows an example of an executables element, which defines an invokeAction binding object and two iterator binding objects.
Example 12-8 The executables Element in a Page Definition File
<executables>
<invokeAction Binds="cancelNewServiceRequest"
id="clearServiceRequestFieldsIfNotInTrain"
Refresh="prepareModel"
RefreshCondition="${adfFacesContext.postback == false and empty
requestScope.processChoice}"/>
<iterator id="ProductListIterator" Binds="ProductList" RangeSize="-1"
DataControl="SRService"/>
<iterator id="GlobalsIterator" RangeSize="10" Binds="Globals"
DataControl="SRService"/>
</executables>
<bindings>
<attributeValues IterBinding="GlobalsIterator" id="ProblemDescription">
<AttrNames>
<Item Value="ProblemDescription"/>
</AttrNames>
</attributeValues>
...
<methodAction id="cancelNewServiceRequest"
InstanceName="SRService.dataProvider"
DataControl="SRService"
MethodName="cancelNewServiceRequest"
RequiresUpdateModel="true" Action="999"/>
</bindings>
The invokeAction object invokes the cancelNewServiceRequest method, which is named in the Binds attribute. In the bindings wrapper element, the methodAction binding object encapsulates the details about how to invoke the method. (For more information about methodAction objects, see Section 12.5.2.3, "Binding Objects Defined in the bindings Element".) The Refresh attribute specifies when in the ADF lifecycle the method is executed, while the RefreshCondition attribute provides a condition for invoking the action. (For more information about the Refresh and RefreshCondition attributes, see Section A.6, "<pageName>PageDef.xml".
The iterator binding named ProductListIterator was created by dropping the ProductId attribute of the Globals collection on the page as a list box. In the ensuing List Binding Editor, the Add button was used to create a new iterator binding for the items to display as choices in the list from the ProductList view object instance in the data model. (For more information, see Section 19.7, "Creating Selection Lists".)
The Binds attribute of the iterator element defines the collection the iterator will iterate over, which in this case is the ProductList collection. The RangeSize attribute defines the number of objects the iterator is to display on the page at one time. A RangeSize value of -1 causes the iterator to display all the objects from the collection.
Tip:
Normally, an iterator binding's default range size is 10. However, when an iterator binding is created from the List Binding Editor, the range size defaults to-1 so that all choices display in the list, not just the first 10.The iterator binding named GlobalsIterator was created the first time one of the attributes from the Globals collection was dropped on the page. In this case, the RangeSize attribute is set to 10, which means the iterator binding will display a maximum of 10 objects at a time from the collection. In the bindings wrapper element, notice that the IterBinding attribute of the attributeValues element references the GlobalsIterator iterator binding, which populates the ProblemDescription text field with data.
The bindings element of the page definition file defines the following types of binding objects:
Value: Display data in UI components by referencing an iterator binding. Each discrete UI component on a page that will display data from the data control is bound to a value binding object. Value binding objects include:
methodAction: Bind command components, such as buttons or links, to custom methods on the data control. A methodAction binding object encapsulates the details about how to invoke a method and what parameters (if any) the method is expecting.
action: Bind command components, such as buttons or links, to built-in data control operations (such as, Commit or Rollback) or to built-in collection-level operations (such as, Create, Delete, Next, Previous, or Save).
Collectively, the binding objects defined in the bindings element are referred to as control bindings, because each databound control on a page is bound to one of these objects, which in turn is bound to an object defined in the executables element.
Example 12-9 shows a sample bindings element, which defines one attribute binding for a text field called ProblemDescription and one methodAction binding called cancelNewServiceRequest.
Example 12-9 The bindings Element of a Page Definition File
<bindings>
<attributeValues IterBinding="GlobalsIterator" id="ProblemDescription">
<AttrNames>
<Item Value="ProblemDescription"/>
</AttrNames>
</attributeValues>
...
<methodAction id="cancelNewServiceRequest"
InstanceName="SRService.dataProvider"
DataControl="SRService"
MethodName="cancelNewServiceRequest"
RequiresUpdateModel="true" Action="999"/>
</bindings>
The binding object defined in the methodAction element encapsulates the information needed to invoke the cancelNewServiceRequest method, which is identified in the MethodName attribute. The value of true in the RequiresUpdateModel attribute specifies that the model layer needs to be updated before the method is executed.
The cancelnewServiceRequest method does not accept parameters. If it did, the methodAction binding object definition would include one or more NamedData elements that would define the parameters expected by the method. For more information about passing parameters to methods, see Chapter 17, "Creating More Complex Pages".
The attributeValues element defines the value bindings for the text fields on the page. In the example, only one attribute is displayed on the page, ProblemDescription, which is defined in the AttrNames element. The IterBinding attribute references the iterator binding that displays the data in the text field.
At runtime, the ADF page lifecycle passes the page URL to the ADF binding context, which matches the URL to a page definition file using the information in the DataBindings.cpx file. Next, the binding context instantiates the binding container if it does not already exist in the current session. The binding container is the runtime instance object that contains all of the binding objects defined in the page definition file. All the data that is displayed by a page's UI components is provided by the binding objects in the binding container. The ADF data binding expressions used by components on a page are evaluated at runtime and are replaced by values supplied by the binding objects when the page is rendered.
By default, the binding container and the binding objects it contains are defined in session scope. However, the values referenced by value bindings and iterator bindings are undefined between requests and for scalability reasons do not remain in session scope. Therefore, the values that binding objects refer to are only valid during a request in which that binding container has been prepared by the ADF lifecycle. What stays in session scope are only the binding container and binding objects themselves.
Upon each request, the iterator bindings are refreshed to rebind them to the underlying RowSetIterator objects. For more information about refreshing iterator bindings, see Section 10.5.5, "How to Use Refresh Correctly for InvokeAction and Iterator Bindings". Use the ADF Business Components State Management facility, described in Chapter 28, "Application Module State Management", to ensure that the rowset iterator state and any pending changes in the transaction are managed between requests.
In the previous section, you saw how the page definition is used to define the binding objects that are created in the binding container at runtime. To display data from the data model, web page UI components, are bound to binding objects using JSF Expression Language (EL) expressions. These EL expressions reference a specific binding object in a binding container. At runtime, the JSF runtime evaluates EL expression and pulls the value from the binding object to populate the component with data when the page is displayed. If the user updates data in the UI component, the JSF runtime pushes the value back into the corresponding binding object based on the same EL expression.
When you use the Data Control Palette to create a component, the ADF data binding expressions are created for you. The expressions are added to every component attribute that will either display data from or reference properties of a binding object. Each prebuilt expression references the appropriate binding objects defined in the page definition file. You can edit these binding expressions or create your own, as long as you adhere to the basic ADF binding expression syntax. ADF data binding expressions can be added to any component attribute that you want to populate with data from a binding object.
In JSF pages, a typical ADF data binding EL expression uses the following syntax to reference any of the different types of binding objects in the binding container:
#{bindings.BindingObject.propertyName}
where:
bindings is a variable that identifies that the binding object being referenced by the expression is located in the binding container of the current page. All ADF data binding EL expressions must start with the bindings variable.
BindingObject is the name of the binding object as it is defined in the page definition file. The binding object name appears in the id attribute of the binding object definition in the page definition and is unique to that page definition. An EL expression can reference any binding object in the page definition file, including parameters, executables, or value bindings. When you use the Data Control Palette to create a component, JDeveloper assigns the names to the binding objects based on the names of the items in the data control.
propertyName is a variable that determines the default display characteristics of each databound UI component and sets properties for the binding object at runtime. There are different binding properties for each type of binding object. For more information about binding properties, see Section 12.6.4, "What You May Need to Know About ADF Binding Properties".
For example, in the following expression:
#{bindings.SvrId.inputValue}
the bindings variable references a bound value in the current page's binding container. The binding object being referenced is SvrId, which is an attribute binding object. The binding property is inputValue, which returns the value of the first SvrId attribute.
Tip:
While the binding expressions in the page definition file can use either a dollar sign ($) or hash sign (#) prefix, the EL expressions in JSF pages can use only the hash sign (#) prefix.For more examples of various types of ADF data binding expressions, see Section 12.6.3, "What Happens When You Create ADF Data Binding Expressions".
To create or edit an ADF Data Binding EL Expression
You can create or edit an expression in JDeveloper using any of the following techniques:
Double-click the UI component in the Structure window, and edit the value field in the displayed editor. (Click the Bind button to go to the Expression Builder, where you can select from available binding objects and properties. For more information, see Section 12.6.2, "How to Use the Expression Builder".)
View the web page using the source view of the visual editor and edit the expression directly in the source. JDeveloper provides Code Insight for EL expressions in the source editor. Code Insight is also available in the Property Inspector and the Tag Editor. To invoke Code Insight, type the leading characters of an EL expression (for example, #{). Code Insight displays a list of valid items for each segment of the expression from which you can select the one you want.
Select a UI component in the visual editor or the Structure window and open the Property Inspector (View > Property Inspector). You can edit the expression directly in the Property Inspector, or click the ellipses next the expression to open the Expression Builder.
The JDeveloper Expression Builder is a dialog that helps you build EL expressions by providing lists of binding objects defined in the page definition files, as well as lists of managed beans and binding properties. It is particularly useful when creating or editing ADF databound expressions because it provides a hierarchical list of ADF binding objects and their most commonly used properties from which you can select the ones you want to use in an expression. For information about binding properties, see Section 12.6.4, "What You May Need to Know About ADF Binding Properties".
You can open the Expression Builder from either the Structure window or the Property Inspector.
To open the Expression Builder from the Structure window:
Double-click an ADF databound UI component in the Structure window.
In the ensuing dialog, click the Bind button next to a component property to display the Expression Builder.
To open the Expression Builder from the Property Inspector:
Select a UI component in the Structure window or the visual editor and open the Property Inspector.
In the Property Inspector, take one of the following actions to display the Expression Builder:
Click the ellipses next to an existing binding expression.
OR
Select a property to which you want to add a binding, and click the Bind to data button, as shown in Figure 12-5.
(JDeveloper activates the Bind to data button only if it is valid to add a binding expression to the selected property.)
To use the Expression Builder:
In the Expression Builder, open the: ADF Bindings > bindings node to display the ADF binding objects for the current page, as shown in Figure 12-6.
Use the Expression Builder to edit or create ADF binding expressions using the following features:
Use the Variables tree to select items that you want to include in the binding expression. The tree contains a hierarchical representation of the binding objects. Each icon in the tree represents various types of binding objects that you can use in an expression (see Table 12-2 for a description of each icon). Select an item in the tree and click the shuttle button to move it to the Expression box.
If you are creating a new expression, begin typing the expression in the Expression box. JDeveloper provides Code Insight in the Expression Builder. To invoke Code Insight, type the leading characters of an EL expression (for example, #{) or a period separator. Code Insight displays a list of valid items for each segment of the expression from which you can select the one you want.
Use the operator buttons under the expression to add logical or mathematical operators to the expression.
Table 12-2 Icons Under the ADF Bindings Node of the Expression Builder
| Icon | Description |
|---|---|
|
|
Represents the |
|
|
Represents the Use this node only to view the binding objects defined for other pages; do not use it to create expressions in the current page. If you want to include an object in the current page that is defined in another page, add a binding to that object in the current page using the Data Control Palette. |
|
|
Represents a binding container. Each binding container node is named after the page definition file that defines it. These nodes appear only under the data node. Opening a binding container node exposes the binding objects defined for that page. Use this node only to view the binding objects defined for other pages; do not use it to create expressions in the current page. If you want to include an object in the current page that is defined in another page, add a binding to that object in the current page using the Data Control Palette. |
|
|
Represents an action binding object. Opening a node that uses this icon exposes a list of valid action binding properties. |
|
|
Represents an iterator binding object. Opening a node that uses this icon exposes a list of valid iterator binding properties. |
|
|
Represents an attribute binding object. Opening a node that uses this icon exposes a list of valid attribute binding properties. |
|
|
Represents a list binding object. Opening a node that uses this icon exposes a list of valid list binding properties are displayed. |
|
|
Represents a table binding object. Opening a node that uses this icon exposes a list of valid table binding properties. |
|
|
Represents a tree binding object. Opening a node that uses this icon exposes a list of valid tree binding properties. |
|
|
Represents an ADF binding object property. For more information about ADF properties, see Section 12.6.4, "What You May Need to Know About ADF Binding Properties". |
|
|
Represents a parameter binding object. |
As was previously mentioned, when you create a component using the Data Control Palette, the ADF data binding expressions are added for you. Each expression is slightly different depending on the type of binding object being referenced.
Example 12-10 shows a text field that was created when a data collection was dropped on a page as an ADF Read-only Form. Each UI component in the form, including the text field shown in the example, contains an EL expression that references an attribute binding object on a specific attribute in the data collection.
Example 12-10 EL Expressions That Reference an Attribute Binding Object
<af:inputText value="#{bindings.SvrId.inputValue}"
label="#{bindings.SvrId.label}"/>
In this example, the UI component is bound to the SvrId binding object, which is a specific attribute in a data collection. The inputValue binding property returns the value of the first attribute to which the binding is associated, which in this case is SvrId. In the label attribute, the EL expression references the label binding property, which returns the label currently assigned to the data attribute.
The attribute binding object, SvrId, referenced by the EL expressions is defined in the page definition file, as shown in Example 12-11. The name of the binding object, which is referenced by the EL expression, is defined in the id attribute of the binding object definition.
When you drag a data collection from the Data Control Palette and drop it on a JSF page as an ADF Read-only Table, the resulting table tag typically contains a set of EL expressions that bind the table to a table value-binding object, as shown in Example 12-12.
Example 12-12 EL Expression That References a Table Binding Object
<af:table value="#{bindings.ServiceRequests.collectionModel}" var="row"
rows="#{bindings.ServiceRequests.rangeSize}"
first="#{bindings.ServiceRequests.rangeStart}"
emptyText="#{bindings.ServiceRequests.viewable ?
\'No rows yet.\' : \'Access Denied.\'}"
Each attribute of the table tag contains a binding expression that references the table binding object and an appropriate binding property for that tag attribute. The binding expression in the rows attribute references the iterator binding rangeSize property (which defines the number of rows in each page of the iterator) so that the number of rows rendered in the table matches the number of rows per page defined by the iterator binding.
The table is bound to the ServiceRequests table binding object, which is defined in the page definition file as shown in Example 12-13.
Example 12-13 Table Binding Object Defined in the Page Definition File
<table id="ServiceRequests" IterBinding="ServiceRequestsIterator">
<AttrNames>
<Item Value="City"/>
<Item Value="CountryId"/>
<Item Value="Email"/>
<Item Value="FirstName"/>
<Item Value="LastName"/>
<Item Value="PostalCode"/>
<Item Value="StateProvince"/>
<Item Value="StreetAddress"/>
<Item Value="UserId"/>
<Item Value="UserRole"/>
</AttrNames>
</table>
The IterBinding attribute in the table binding object refers to the iterator binding that will display data in the table.
Example 12-14 shows a command button that was created by dragging a built-in operation from the Data Control Palette and dropping it on the page. The button contains an EL expression that binds to a built-in operation, First, which displays the first data object in the data collection to which the operation belongs.
Example 12-14 EL Expression That References an Action Binding Object for an Operation
<af:commandButton actionListener="#{bindings.First.execute}"
text="First"
disabled="#{!bindings.First.enabled}"/>
The button's action listener is bound to the execute() method on the action binding named First in the binding container. When the user clicks the button, the action listener mechanism resolves the binding expression and then invokes the execute() method, which executes the operation. By default, the button label contains the name of the operation being called. You can change the label as needed. The disabled attribute determines if the button should be disabled on the page. Because of the not operator (!) at the beginning of the expression, the disabled attribute evaluates to the negation of the value of the enabled property of the action binding.
In other words, if the enabled property evaluates to false, the disabled attribute evaluates to true. For example, in an action binding that is bound to the First operation, if the current data object is the first one, the enabled property evaluates to false, which causes the disabled attribute to evaluate to true, thus disabling the button. However, if the current data object is not the first one, the enabled property evaluates to true, which causes the disabled attribute to evaluate to false, thus enabling the button.
Example 12-15 shows the action binding object defined in the page definition for the command button.
Example 12-15 Action Binding Object Defined in the Page Definition File for an Operation
<bindings>
<action id="First" IterBinding="ServiceRequestsIterator"
InstanceName="SRService.ServiceRequests" DataControl="SRService"
RequiresUpdateModel="true" Action="12"/>
</bindings>
The action element, First, defines the action binding object that is directly referenced by the EL expression in the command button. The IterBinding attribute of the action binding references the iterator binding for the data collection being operated on by the action.
Tip:
The numerical value of theAction attribute of the action element references the number constants in the OperationDefinition interface in the oracle.adf.model.meta package.Example 12-16 shows a command button that was created by dragging a method from the Data Control Palette and dropping it on a JSF page. In this example, the command button is bound to the deleteServiceHistoryNotes method. The execute binding property in the EL expression in the actionListener attribute invokes the method when the user clicks the button
Example 12-16 EL Expression That References an Action Binding Object for a Method
<af:commandButton actionListener="#{bindings.deleteServiceHistoryNotes.execute}"
text="deleteServiceHistoryNotes"
disabled="#{!bindings.deleteServiceHistoryNotes.enabled}"/
Example 12-17 shows the binding object created in the page definition file for the command button. When a command component is bound to a method, only one binding object is created in the page definition file—a methodAction. The methodAction binding defines the information needed to invoke the method, including any parameters, which are defined in the NamedData element.
Example 12-17 Method Action Binding Defined in the Page Definition File
<bindings>
<methodAction id="deleteServiceHistoryNotes"
InstanceName="SRService.dataProvider" DataControl="SRService"
MethodName="deleteServiceHistoryNotes"
RequiresUpdateModel="true" Action="999">
<NamedData NDName="keySet" NDType="java.util.Set"/>
</methodAction>
</bindings>
When you create a databound component using the Data Control Palette, the EL expression references specific ADF binding properties. At runtime, these binding properties can define such things as the default display characteristics of a databound UI component or specific parameters for iterator bindings. The ADF binding properties are defined by Oracle APIs. For a full list of the available properties for each binding type, see Appendix B, "Reference ADF Binding Properties".
Values assigned to certain properties are defined in the page definition file. For example, iterator bindings have a property called RangeSize, which specifies the number of rows the iterator should display at one time. The value assigned to RangeSize is specified in the page definition file, as shown in Example 12-18.
Example 12-18 Iterator Binding Object with the RangeSize Property
<iterator id="ServiceRequestsIterator" RangeSize="10"
Binds="ServiceRequests" DataControl="SRService"/>
Use the JDeveloper Expression Builder to display a list of valid binding properties for each binding object. For information about how to use the Expression builder, see Section 12.6.2, "How to Use the Expression Builder".
