10.3 Creating Command Components to Execute Methods

When you create a UI component by dragging and dropping a collection that is a return of a method, that method is executed when the page is rendered, so that it can return the collection. However, you can also drag the method itself (or any other type of method) and drop it as a command component to directly invoke the method.

Tip:

You can also drop the method as a parameter form. For more information, see Section 10.7.3, "How to Use a Custom Method to Create an Input Form" and Section 10.8.1, "How to Create a Search Form".

In addition to custom methods, your data control may contain built-in methods that perform some standard business logic, such as updating or deleting objects. You can use these methods in conjunction with a collection. For example, the SRDemo application contains the mergeEntity(Object) method on the SRPublicFacade bean that can be used to update any object and merge it in the data source. When you drag this method from the Data Control Palette and drop it as command button, the button is automatically bound to the method, and so that method will execute whenever the button is clicked. Figure 10-3 shows some of the methods in the Data Control Palette for the SRDemo application.

Figure 10-3 Methods in the Data Control Palette

Whether using a custom method or a built-in method, you can create a command button that executes the associated business logic on your service bean by binding the button to that method. When you use the Data Control Palette to create the button, JDeveloper creates the binding for you. You need only to set the values for any parameters needed by the method.

10.3.1 How to Create a Command Component Bound to a Service Method

In order to perform the required business logic, many methods require a value for the method's parameter or parameters. That means when you create a button bound to the method, you need to specify where the value for the parameter(s) can be retrieved.

For example, if you use the mergeEntity(Object) method, you need to specify the object to be updated.

To add a button bound to a method:

From the Data Control Palette, drag the method onto the page.

Tip:
If you are dropping a button for a method that needs to work with data in a table or form, that button must be dropped inside the table or form.
From the context menu, choose Methods > ADF Command Button.

If the method takes parameters, the Action Binding dialog opens. In the Action Binding Editor, click the ellipses (...) button in the Value column of Parameters to launch the EL Expression Builder. You'll use the builder to set the value of the method's parameter. Figure 10-4 shows the EL Expression Builder.

Figure 10-4 The EL Expression Builder

The EL Expression Builder shows all values you can bind to

For example, to set the value for the Object parameter of the mergeEntity(Object) method used to update a collection, you would:

In the EL Expression Builder, expand the ADF Bindings node and then expand the bindings node.

All the bindings in the JSF page's page definition file are displayed.
Expand the node for the iterator that works with the object you want to merge.
Expand the currentRow node. This node represents the current row in the iterator.
Select the dataProvider property and click the right-arrow button. Doing so creates an EL expression that evaluates to the data for the object in the current row of the iterator. Click OK to close the EL Expression Builder and populate the value with the EL expression. Click OK again to bind the button to the method.

Tip:

Consider criteria such as the following when determining what to select for the parameter value:

If you want the method to operate on a row in a table, you would set the parameter to be the current row in the table binding, and not the current object in the iterator.
If you want to be able to update multiple rows that represent detail objects in a master-detail relationship, you can set the parameter to be the master list object.
If the value is stored in a scope or on a managed bean, you would select the corresponding attribute in that scope or on that managed bean. However, this value must be set by a sending page. For more information, see Section 10.4, "Passing Parameter Values to Another Page Using a Command Component".

10.3.2 What Happens When You Create Command Components Using a Method

When you drop a method as a command button, JDeveloper:

Defines a method binding for the method. If the method takes any parameters, JDeveloper creates NamedData elements that hold the parameter values.
Inserts code in the JSF page for the ADF Faces command component. This code is the same as code for any other command button, as described in Section 6.4.2.3, "Using EL Expressions to Bind to Navigation Operations". However, instead of being bound to the execute method of an action binding for an operation, the buttons are bound to the execute method of the action binding for the method that was dropped.

10.3.2.1 Using Parameters in a Method

As when you drop a collection that is a return of a method, when you drop a method that takes parameters onto a JSF page, JDeveloper creates a method action binding (for details, see Section 6.2.2.1, "Creating and Using Iterator Bindings"). However, when the method requires parameters to run, JDeveloper also creates NamedData elements for each parameter. These elements represent the parameters of the method.

For example, the mergeEntity(Object) method action binding contains a NamedData element for the Object parameter. This element is bound to the value specified when you created the action binding. Example 10-3 shows the method action binding created when you dropped the mergeEntity(Object) method, and bound the Object parameter (named entity) to the data for the current row in the findServiceRequestByIdIter iterator.

Example 10-3 Method Action Binding for a Parameter Method

<methodAction id="mergeEntity" InstanceName="SRPublicFacade.dataProvider"
                  DataControl="SRPublicFacade" MethodName="mergeEntity"
                  RequiresUpdateModel="true" Action="999"
                  ReturnName="SRPublicFacade.methodResults.SRPublicFacade
                        _dataProvider_mergeEntity_result">
  <NamedData NDName="entity"
             NDValue="${bindings.findServiceRequestByIdIter.
                        currentRow.dataProvider}"
             NDType="java.lang.Object"/>
</methodAction>

10.3.2.2 Using EL Expressions to Bind to Methods

Like creating command buttons using navigation operations, when you create a command button using a method, JDeveloper binds the button to the method using the actionListener attribute. The button is bound to the execute property of the action binding for the given method. This binding causes the binding's method to be invoked on the business service. For more information about the command button's actionListener attribute, see Section 6.4.3, "What Happens at Runtime: About Action Events and Action Listeners".

Tip:

Instead of binding a button to the execute method on the action binding, you can bind the button to method in a backing bean that overrides the execute method. Doing so allows you to add logic before or after the original method runs. For more information, see Section 10.5, "Overriding Declarative Methods".

Like navigation operations, the disabled property on the button uses an EL expression to determine whether or not to display the button. Example 10-4 shows the EL expression used to bind the command button to the mergeEntity(Object) method.

Example 10-4 JSF Code to Bind a Command Button to a Method

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

Tip:

When you drop a UI component onto the page, JDeveloper automatically gives it an ID based on the number of that component previously dropped, for example, commandButton1, commandButton2. You may want to change the ID to something more descriptive, especially if you will need to refer to it in a backing bean that contains methods for multiple UI components on the page.

10.3.3 What Happens at Runtime

When the user clicks the button, the method binding causes the associated method to be invoked, passing in the value bound to the NamedData element as the parameter. For example, if a user clicks a button bound to the mergeEntity(Object) method, the method takes the value of the current record and updates the data source accordingly.