| Oracle® Application Development Framework Developer's Guide For Forms/4GL Developers 10g (10.1.3.1.0) Part Number B25947-01 |
|
|
View PDF |
| Oracle® Application Development Framework Developer's Guide For Forms/4GL Developers 10g (10.1.3.1.0) Part Number B25947-01 |
|
|
View PDF |
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.
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.
