17.3 Creating Command Components to Execute Methods

When your application contains custom methods, these methods appear in the Data Control Palette. You can then drag these methods and drop them as command buttons. When a user clicks the button, the method is executed. For more information about custom methods, see Chapter 8, "Implementing Business Services with Application Modules".

For example, the SRService application module in the SRDemo application contains the deleteServiceHistoryNotes(Set keySet) method. This method ensures that one or more rows are selected, then deletes those rows and commits the transaction. To allow the user to execute this method, you drag the deleteServicehistoryNotes(Set) method from the Data Control Palette, as shown in Figure 17-3.

Figure 17-3 Methods in the Data Control Palette

Note:

In the SRDemo application, additional view-layer logic is added to the deleteServiceHistoryNotes(Set) method by overriding this method in a managed bean. You can also override a custom method if you need to provide conditional navigational logic. For more information, see Section 17.5, "Overriding Declarative Methods".

17.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 from where the value for the parameter(s) can be retrieved.

For example, if you use the deleteServicehistoryNotes(Set) method, you need to specify the set of rows to be deleted.

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 use the builder to set the value of the method's parameter.

17.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 action 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 13.4.2.3, "Using EL Expressions to Bind to Navigation Operations". However, instead of being bound to the execute method of the action binding for a built-in operation, the button is bound to the execute method of the method action binding for the method that was dropped.

17.3.2.1 Using Parameters in a Method

When you drop a method that takes parameters onto a JSF page, JDeveloper creates a method action binding. This binding is what causes the method to be executed when a user clicks the command component. 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 deleteServiceHistoryNotes method action binding contains a NamedData element for the Set parameter. This element is bound to the value specified when you created the action binding. Example 17-3 shows the method action binding created when you drop the deleteServiceHistoryNotes(Set) method, and bind the Set parameter (named keySet) to the keySet property of the selectionState property of the history table UI component in the page's backing bean (for more information about using this method to delete multiple rows (the key set), see Section 14.6.5, "How to Use the TableSelectMany Component in the Selection Facet").

Example 17-3 Method Action Binding for a Parameter Method

<methodAction id="deleteServiceHistoryNotes"
              InstanceName="SRService.dataProvider"
              DataControl="SRService"
              MethodName="deleteServiceHistoryNotes"
              RequiresUpdateModel="true" Action="999">
  <NamedData NDName="keySet"
             NDValue="${backing_SRMain.historyTable.selectionState.keySet}"
             NDType="java.util.Set"/>
</methodAction>

17.3.2.2 Using EL Expressions to Bind to Methods

Like creating command buttons using 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 application module. For more information about the command button's actionListener attribute, see Section 13.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 17.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 17-4 shows the EL expression used to bind the command button to the deleteServiceHistoryNotes(Set) method.

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

<af:commandButton actionListener="#{bindings.deleteServiceHistoryNotes.execute}"
                  text="deleteServiceHistoryNotes"
                  disabled="#{!bindings.deleteServiceHistoryNotes.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. Note that if you do change the ID, you must manually update any references to it in EL expressions in the page.

17.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 deleteServiceHistoryNotes(Set) method, the method takes the value of the key set (in this case the selected rows in a table) and deletes them from the data source.