5.6 Creating ADF Data Binding EL Expressions

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.

5.6.1 How to Create an ADF Data Binding 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:

#{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 the bindings variable in the binding expressions.
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 5.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 5.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 5.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.

5.6.2 How to Use 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 5.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 5-5.
  
  (JDeveloper activates the Bind to data button only if it is valid to add a binding expression to the selected property.)
  
  Figure 5-5 Bind to data Button in the Property Inspector

To use the Expression Builder:

Open the Expression Builder dialog.
In the Expression Builder, open the ADF Bindings > bindings node to display the ADF binding objects for the current page, as shown in Figure 5-6.

For information about using the ADF Bindings > data node, see Section 5.6.5, "What You May Need to Know About Binding to Values in Other Pages".

Figure 5-6 The Expression Builder Dialog
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 5-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 5-2 I cons Under the ADF Bindings Node of the Expression Builder

Icon	Description
	Represents the `bindings` container variable, which references the binding container of the current page. Opening the bindings node exposes all the binding objects for the current page.
	Represents the `data` binding variable, which references the entire binding context. Opening the data node exposes all the page definition files in the application. Opening a page definition file exposes the binding objects it defines. Before using the objects under this node, see Section 5.6.5, "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. Before using the object under this node, see Section 5.6.5, "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.
	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 5.6.4, "What You May Need to Know About ADF Binding Properties".
	Represents a parameter binding object.

5.6.3 What Happens When You Create ADF Data Binding Expressions

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.

5.6.3.1 EL Expressions That Reference Attribute Binding Objects

Example 5-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 5-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 value binding object, SvrId, referenced by the EL expressions is defined in the page definition file, as shown in Example 5-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.

Example 5-11 Attribute Binding Object Defined In the Page Definition File

<attributeValues id="SvrId" IterBinding="FindAllServiceRequestsIter"
                 isDynamic="true">
  <AttrNames>
     <Item Value="SvrId"/>
  </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.

5.6.3.2 EL Expressions That Reference Table Binding Objects

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

Example 5-12 EL Expression That References a Table Binding Object

<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.\'}"

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 findAllStaff1 table binding object, which is defined in the page definition file as shown in Example 5-13.

Example 5-13 Table Binding Object Defined 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>

The IterBinding attribute in the table binding object refers to the iterator binding that will display data in the table.

5.6.3.3 EL Expressions That Reference Action Binding Objects

Example 5-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 5-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 5-15 shows the action binding object defined in the page definition for the command button.

Example 5-15 Action Binding Object 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>

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 binding, findAllStaffIter, which iterates over the data collection being operated on by the action. The findAllStaffIter is bound to the methodAction, findAllStaff, which encapsulates the information required to invoke the findAllStaff method.

Tip:

The numerical value of the Action attribute of the action element references the number constants in the OperationDefinition interface in the oracle.adf.model.meta package.

Example 5-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 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-16 EL Expression That References an Action Binding Object for a Method

<af:commandButton actionListener="#{bindings.removeServiceHistory.execute}"
                          text="removeServiceHistory"
                          disabled="#{!bindings.removeServiceHistory.enabled}"/

Example 5-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 5-17 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>

5.6.4 What You May Need to Know About ADF Binding Properties

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, iterators can reference 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 5-18

Example 5-18 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.2, "How to Use the Expression Builder".

5.6.5 What You May Need to Know About Binding to Values in Other Pages

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 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 are defined in session scope, but the values referenced by the binding objects are not. By default, the RowSetIterator 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 is prepared during a given request.

Also, your application can, programmatically or through the use of the CacheResults or Refresh attributes on an iterator binding, re-execute or clear an iterator during a request. In this case, the binding object values would no longer be available to other pages. For more information about the iterator binding attributes that clear (CacheResults) or refresh (Refresh) the iterator, see Section A.7, "<pageName>PageDef.xml".