|
Oracle® Application Development Framework Developer's Guide
10g Release 3 (10.1.3) B25386-01 |
|
 Previous |
 Next |
|
Oracle® Application Development Framework Developer's Guide
10g Release 3 (10.1.3) B25386-01 |
|
|
Previous |
Next |
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. Web page UI components, are bound to binding objects using JSF EL expressions. These EL expressions reference a specific binding object in a binding container. At runtime, when the EL expression is evaluated the binding object populates the component with data. For general information about JSF EL expressions, see Chapter 1, "Introduction to Oracle ADF Applications".
When you use the Data Control Palette to create a component, the ADF databinding expressions are created for you. The expressions are added to every component attribute that will be populated by data from 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 databinding 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 databinding EL expression uses the following syntax to reference any of the different types of binding objects in the binding container:
#{bindingVariable.BindingObject.propertyName}
where:
bindingVariable is a variable that identifies where to find the binding object being referenced by the expression. The bindings variable is the most common variable used in ADF binding expressions. It references the binding container of the current page. By default, all components created from the Data Control Palette use this variable in the binding expressions.
BindingObject is the name of the binding object as it appears in the page definition file. The binding object names appear in the id attribute of the binding definition and must be unique to that page definition file. 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 5.6.3, "Using Binding Object Runtime Properties".
For example, the expression shown in Example 5-11 uses the binding variable, which references a bound value in the current page's binding container. The binding object being referenced is userID, which is an attribute binding object. The binding property is inputValue, which returns the value of the first userID.
|
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 databinding expressions, see Section 5.6.2, "What Happens When You Use ADF Databinding EL Expressions".
When you use the Data Control Palette to create a databound UI component, JDeveloper creates the binding expression for you. 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 5.6.1.2, "Using 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, #{).
Select a UI component in the visual editor or the Structure window and open the 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 objects, managed beans, and properties. It is particularly useful when creating or editing ADF databound expressions because it provides a hierarchical list of ADF binding objects and their valid properties from which you can select the ones you want to use in an expression. For information about binding properties, see Section 5.6.3, "Using Binding Object Runtime Properties".
To use the Expression Builder:
Open the Expression Builder dialog, using any of the following techniques:
To edit or add a binding expression:
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 edit an existing binding expression:
Select a UI component in the Structure window or the visual editor and open the Property Inspector.
In the Property Inspector, click the ellipses next to an existing binding expression to display the Expression Builder.
To add a new binding expression:
Select a UI component in the Structure window or the visual editor and open the Property Inspector.
In the Property Inspector, select a property to which you want to add a binding.
If it is valid to add a binding expression to the selected property, JDeveloper activates the Bind to data button (shown in Figure 5-5). Click this button to display the Expression Builder.
In the Expression Builder, open the ADF Bindings node to display the ADF binding objects, as shown in Figure 5-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. Table 5-2 describes all of the icons under the ADF Bindings node. Select an item in the tree and click the right arrow button to move it to the Expression box.
If you are creating a new expression, begin typing the expression in the Expression box and each time you type a period (which separates the properties of the expression), JDeveloper displays a dropdown list of binding objects from which you can choose.
Use the operator buttons under the expression as needed.
Table 5-2 Icons Under the ADF Bindings Node of the Expression Builder
| Icon | Description |
|---|---|
|
|
Represents the 
|
|
|
Represents the 
Before using the objects under this node, see Section 5.6.4, "What You May Need to Know About Binding to Values in Other Pages" for more information and cautions. |
|
|
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. For example: 
Before using the object under this node, see Section 5.6.4, "What You May Need to Know About Binding to Values in Other Pages" for more information and cautions. |
|
|
Represents an action binding object. Opening a node that uses this icon exposes a list of valid action binding properties. For example: 
|
|
|
Represents an iterator. Opening a node that uses this icon exposes a list of valid iterator binding properties. For example: 
|
|
|
Represents an attribute binding object. Opening a node that uses this icon exposes a list of valid attribute binding properties. For example: 
|
|
|
Represents a list binding object. Opening a node that uses this icon exposes a list of valid list binding properties are displayed. For example: 
|
|
|
Represents a table binding object. Opening a node that uses this icon exposes a list of valid table binding properties. For example: 
|
|
|
Represents a tree binding object. Opening a node that uses this icon exposes a list of valid tree binding properties. For example: 
|
|
|
Represents a binding object property. For more information, see Section 5.6.3, "Using Binding Object Runtime Properties". |
|
|
Represents a parameter binding object. |
As was previously mentioned, when you create a component using the Data Control Palette, the ADF databinding expressions are added for you. Each expression is slightly different depending on the type of binding object being referenced.
Example 5-12 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 a value binding object for a specific attribute in the data collection.
Example 5-12 EL Expressions That Reference an Attribute Binding Object
<af:inputText value="#{bindings.userId.inputValue}"
label="#{bindings.userId.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 userID. In the label attribute, the EL expression references the label binding property, which returns the label currently assigned to the data attribute.
The value binding object, userId, referenced by the EL expressions is defined in the page definition file, as shown in Example 5-13. The name of the binding object, which is referenced by the EL expression, is defined in the id attribute.
Example 5-13 Page Definition Attribute Binding Object Referenced by an EL Expression
<attributeValues id="userId" IterBinding="findUserIdByEmailIter"
isDynamic="true">
<AttrNames>
<Item Value="userId"/>
</AttrNames>
</attributeValues>
|
Tip: For a value binding that was created by dragging an attribute from an accessor return from the Data Control Palette, JDeveloper prefixes the accessor method name to the attribute name. For example, in the expression#{bindings.ServiceRequestsvrId.label}, the binding object name is a combination of the accessor method name, ServiceRequest, and the attribute name, svrId.
|
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 5-14.
Example 5-14 EL Expression for a Table Component
<af:table value="#{bindings.findAllStaff1.collectionModel}" var="row"
rows="#{bindings.findAllStaff1.rangeSize}"
first="#{bindings.findAllStaff1.rangeStart}"
emptyText="#{bindings.findAllStaff1.viewable ?
\'No rows yet.\' : \'Access Denied.\'}"
The table is bound to the findAllStaff1 table binding object, which is defined in the page definition file as shown in Example 5-15. 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 rangeSize property, which defines the number of rows the iterator should return.
The IterBinding attribute in the table binding in the page definition file refers to the iterator binding object that will return the data that populates the table, which is the findAllStaffIter iterator.
Example 5-15 Table Bindings in the Page Definition File
<table id="findAllStaff1" IterBinding="findAllStaffIter">
<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>
Example 5-16 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 data control operation, First, which displays the first data object in the data collection to which the operation belongs.
Example 5-16 EL Expression That References an Action Binding on an Operation
<af:commandButton actionListener="#{bindings.First.execute}"
text="First"
disabled="#{!bindings.First.enabled}"/>
The actionListener attribute is bound to the action binding, First, which is defined in the page definition file. The execute binding property executes the operation when the user clicks the button. By default, the labels on ADF command buttons contain the name of the method or operation being called. You can change the label as needed. The disabled attribute determines if the button should be disabled on the page. The expression in the disabled attribute evaluates to the value of the enabled property, which is an action binding property that is set by methods in the binding object. For example, in an action binding object that is bound to the First operation, a method would set enabled to false (which disables the button) if the current data object is the first one, or would set enabled to true (which enables the button) if the current data object is not the first one.
Example 5-17 shows the action bindings defined in the page definition for the command button. The action element, First, defines the action binding that is directly referenced by the EL expression in the command button. The IterBinding attribute of the action binding references the method iterator, findAllStaffIter, which iterates over the data collection. The findAllStaffIter is bound to the methodAction, findAllStaff, which encapsulates the information required to invoke the findAllStaff method.
Example 5-17 Action Bindings Defined in the Page Definition File for an Operation
<executables>
<methodIterator id="findAllStaffIter" Binds="findAllStaff.result"
DataControl="SRPublicFacade" RangeSize="10"
BeanClass="oracle.srdemo.model.entities.User"/>
</executables>
<bindings>
<methodAction id="findAllStaff" InstanceName="SRPublicFacade.dataProvider"
DataControl="SRPublicFacade" MethodName="findAllStaff"
RequiresUpdateModel="true" Action="999"
ReturnName="SRPublicFacade.methodResults.
SRPublicFacade_dataProvider_findAllStaff_result"/>
<action id="First" IterBinding="findAllStaffIter"
InstanceName="SRPublicFacade.dataProvider"
DataControl="SRPublicFacade" RequiresUpdateModel="true"
Action="12"/>
</bindings>
Example 5-18 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 removeServiceHistory method, which removes an object from the data collection. Parameters passed to the method when it is invoked identify which object to remove. The execute binding property in the EL expression in the actionListener attribute invokes the method when the user clicks the button
Example 5-18 EL Expression That References an Action Binding on a Method
<af:commandButton actionListener="#{bindings.removeServiceHistory.execute}"
text="removeServiceHistory"
disabled="#{!bindings.removeServiceHistory.enabled}"/
Example 5-19 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 5-19 Method Action Binding Defined in the Page Definition File
<bindings>
<methodAction id="removeServiceHistory"
InstanceName="SRPublicFacade.dataProvider"
DataControl="SRPublicFacade" MethodName="removeServiceHistory"
RequiresUpdateModel="true" Action="999">
<NamedData NDName="serviceRequest"
NDType="oracle.srdemo.model.entities.ServiceRequest"/>
<NamedData NDName="serviceHistory"
NDType="oracle.srdemo.model.entities.ServiceHistory"/>
</methodAction>
</bindings>
For information about action bindings that return navigation outcomes, see Chapter 9, "Adding Page Navigation Using Outcomes".
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 binding iterators. 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, iterators can reference a property called RangeSize, which specifies the number of rows the iterator should return at one time. The value assigned to RangeSize is specified in the page definition file. Example 5-20 shows an accessor iterator defined in a page definition file. Notice that the RangeSize is set to 10, meaning that the iterator returns 10 rows at a time.
Example 5-20 Iterator Binding Object with the RangeSize Property
<accessorIterator id="serviceHistoryCollectionIterator" RangeSize="10"
Binds="serviceHistoryCollection"
DataControl="SRDemoSessionDataControl"
BeanClass="oracle.srdemo.model.ServiceHistory"
MasterBinding="findAllServiceRequestIter"/>
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 5.6.1.2, "Using the Expression Builder".
While Oracle does not recommend this approach, you can access the bound values in another page's binding container from the current page using the ADF data binding variable in an EL expression. The data binding variable references the binding context itself, which provides access to all the binding containers that are available. Use this variable when you want to bind to an object in the binding container of another page. The data variable must be immediately followed by the name of a page definition file that defines the binding container being referenced. For example:
#{data.mypagePageDef.BindingObject.propertyName}
At runtime, only the current incoming page's (or if the rendered page is different from the incoming, the rendered page's) binding container is automatically prepared by the framework during the current request. Therefore, to successfully access a bound value in another page from the current page, you must programmatically prepare that page's binding container in the current request (for example, using a backing bean). Otherwise, the bound values in that page may not be available or valid in the current request.
You may find cases, where you need to use the data variable to bind to values across binding containers. However, Oracle recommends that instead you use a backing bean to store page values and make them available to other pages. For more information about storing values in backing beans, see Section 10.2, "Using a Managed Bean to Store Information".
|
Caution: As was mentioned in Section 5.5.4, "What You May Need to Know About Binding Container Scope", the binding container, the binding objects it contains, and the values the binding objects reference are defined in session scope. By default, theRowSetIterator state and the data caches are maintained between requests, which makes the bound value referenced by a binding object available across pages.
However, when referring to binding objects across pages, you cannot rely on the bound values at session scope. The lifecycle of bound values is managed by the data control. The availability of a bound value during a given request depends on whether the data control itself is available and whether the referenced binding container has been prepared in the lifecycle. So, before referencing a bound value in one binding container from another page, be sure that the binding container being referenced will be prepared during a given request. Also, your application can, programmatically or through the use of the |
