You can use command components to perform an action, such as passing parameters, overriding declarative actions, or performing some logic. You can bind a command component to a custom method in the Data Controls panel. For example, if you have a custom method called deleteOrderItem(), you can create a button bound to this method so that when the user presses this button, the order item will be deleted.

You can also use the setPropertyListener tag within a command component to assign values when an event fires. For example, assume you have a button that initiates a search and displays the results on another page depending on a parameter value stored in a managed bean. You can use the setPropertyListener property to pass this parameter value to the method that checks this value.

You can add code to a declarative method that is bound to a command component. For example, after you have created a declarative Commit button, you can add code to a managed bean and then override the Commit operation for additional processing

1. From the Data Controls panel, 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.

2. From the context menu, choose Create > Methods > ADF Button.

   If the method takes parameters, the Edit Action Binding dialog opens. In the Edit Action Binding dialog, enter values for each parameter or click the Show EL Expression Builder menu selection in the Value column of Parameters to launch the EL Expression Builder.

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.

• Binds the button to the method using actionListener.

• Uses the return value from the method call.

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 populateInventoryForProduct(String productId) method, the method takes the value of the productId parameter and displays the inventory for that product.

1. In the Applications window, double-click the web page that contains the command component to which you want to add the listener.
2. In the design editor for the page, right-click the command component and choose Insert Inside Button > ADF Faces.
3. In the Insert ADF Faces Item dialog, select Set Property Listener and click OK.
4. In the Insert Set Property Listener dialog, enter the parameter value in the From field.

   You can bring up an expression builder for this field by hovering to the right of the field, clicking the icon that appears, and choosing Expression Builder.

5. Enter the parameter target in the To field.

   You can bring up an expression builder for this field by hovering to the right of the field, clicking the icon that appears, and choosing Expression Builder.

   Tip:

   Consider storing the parameter value on a managed bean or in scope instead of setting it directly on the resulting page's page definition file. By setting it directly on the next page, you lose the ability to easily change navigation in the future. For more information, see Using a Managed Bean in a Fusion Web Application. Additionally, the data in a binding container is valid only during the request in which the container was prepared. The data may change between the time you set it and the time the next page is rendered.

6. From the Type dropdown menu, select Action.
7. Click OK.

The setPropertyListener component lets the command component set a value before it navigates to the next page. When you set the from attribute either to the source of the value you need to pass or to the actual value, the component will be able to access that value. When you set the to attribute to a target, the command component is able to set the value on the target. The following example shows the code on the JSF page for a command component that takes the value false and sets it as the value of the initialSearch flag on the searchResults managed bean.

<af:button actionListener="#{bindings.Execute.execute}"
                 text=Search>
      <af:setPropertyListener from="#{false}"
                          to="#{searchResults.initialSearch}"/>
                          type="action"/>
</af:button>

When a user clicks the command component, before navigation occurs, the setPropertyListener component sets the parameter value. As the example in What Happens When You Set Parameters Using a setPropertyListener illustrates, the setPropertyListener takes the value false and sets it as the value for the initialSearch attribute on the searchResults managed bean. Now, any component that needs to know this value in determining whether or not to render can access it using the EL expression #{searchResults.initialSearch}.

1. Drag the operation or method to be overridden onto the JSF page and drop it as a UI command component.

   The component is created and bound to the associated binding object in the ADF Model layer with the ActionListener attribute.

   For more information about creating command components using methods on the Data Controls panel, see Creating Command Components to Execute Methods.

   For more information about creating command components from operations, see What Happens When You Create Command Components Using Operations.

2. On the JSF page, double-click the component.
3. In the Bind Action Property dialog, identify the backing bean and the method to which you want to bind the component, using one of the following techniques:

   • If auto-binding has been enabled on the page (by selecting the Automatically Expose UI Components in a New Managed Bean option that is available on the Managed Bean tab of the Create JSF Page wizard), the backing bean is already selected for you.

     • To create a new method, enter a name for the method in the Method field, which initially displays a default name.

       or

     • To use an existing method, select a method from the dropdown list in the Method field.

     • Select Use ADF Binding for Generation.

   • If the page is not using auto-binding, you can select from an existing backing bean or create a new one.

     • Click New to create a new backing bean. In the Create Managed Bean dialog, name the bean and the class, and set the bean's scope.

       or

     • Select an existing backing bean and method from the dropdown lists.

     Figure 33-2 shows the Bind Action Property dialog with a method from a managed bean specified for the method binding.

     Figure 33-2 Bind Action Property Dialog

     
     Description of "Figure 33-2 Bind Action Property Dialog"

   Note:

   Whenever there is a value for the ActionListener attribute on the command component, JDeveloper understands that the button is bound to the execute property of a binding. If you have removed that binding, you will not be given the choice to generate the ADF binding code. You will need to insert the code manually, or to set a dummy value for the ActionListener before double-clicking the command component.

4. After identifying the backing bean and method, click OK in the Bind Action Property dialog

   The managed bean opens in the source editor. The following example shows the code inserted into the bean in the Summit ADF task flow sample application. In this example, a command button is bound to the CreateInsert operation.

   public void createNewOrder() {
           BindingContainer bindings = getBindings();
           OperationBinding operationBinding =
                 bindings.getOperationBinding("CreateInsert");
           Object result = operationBinding.execute();
           if (!operationBinding.getErrors().isEmpty()) {
               return null;
           }
   }
   

5. You can now add logic either before or after the binding object is accessed, as shown by the code in bold in the following example.

   public void createNewOrder() {
   //This method is called when creating a new order 
   //to create the record and switch the tab
     getSdi3().setDisclosed(false);
     getSdi4().setDisclosed(true);
     BindingContainer bindings = getBindings();
     OperationBinding operationBinding =
          bindings.getOperationBinding("CreateInsert");
     operationBinding.execute();
     AdfFacesContext adfFacesContext = AdfFacesContext.getCurrentInstance();
     adfFacesContext.addPartialTarget(getSdi4()); 
   }
   

   In addition to any processing logic, you may also want to write conditional logic to return one of multiple outcomes. For example, you might want to return null if there is an error in the processing, or another outcome value if the processing was successful. A return value of null causes the navigation handler to forgo evaluating navigation cases and to immediately redisplay the current page.

   Tip:

   To trigger a specific navigation case, the outcome value returned by the method must exactly match the outcome value in the navigation rule, including case.

   The command button is now bound to this new method using the Action attribute instead of the ActionListener attribute. If a value had previously existed for the Action attribute (such as an outcome string), that value is added as the return for the new method. If there was no value, the return is kept as null.

When you override a declarative method, JDeveloper adds a managed property to your backing bean with the managed property value of #{bindings} (the reference to the binding container), and it adds a strongly typed bean property to your class of the BindingContainer type, which the JSF runtime will then set with the value of the managed property expression #{bindings}. JDeveloper also adds logic to the UI command action method. This logic includes the strongly typed getBindings() method used to access the current binding container.

The code does the following:

• Accesses the binding container.

• Finds the binding for the associated method, and executes it.

• Adds a return for the method that can be used for navigation. By default, the return is null. If an outcome string had previously existed for the button's Action attribute, that attribute is used as the return value. You can change this code as needed.

JDeveloper automatically rebinds the UI command component to the new method using the Action attribute, instead of the ActionListener attribute. The following example shows the code when a CreateInsert operation is declaratively added to a page.

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

The following example shows the code for the button tag after the method on the page's backing bean is overridden. Note that the action attribute is now bound to the backing bean's method.

<af:button text="New"
           action="#{backingBeanScope.CustomersBackingBean.createNewOrder}"/>