Running a Bounded Task Flow in a Modal Dialog describes how you can run a bounded task flow in a modal dialog to retrieve input from an end user, and return to a view activity that called the bounded task with the retrieved input. If your application does not use ADF Controller task flows or you want to use modeless dialogs, Using the ADF Faces Dialog Framework Instead of Bounded Task Flows, describes how you can use the ADF Faces dialog framework to render one or more pages in a dialog.

You may find it helpful to understand other Oracle ADF features before you configure or use dialogs in your application. Additionally, you may want to read about what you can do with the dialogs you configure. Following are links to other functionality that may be of interest.

• If your application uses ADF Controller task flows, you may find it helpful to understand more about the features that task flows offer. For more information, see Getting Started with ADF Task Flows .

• For more information about ADF Faces components, see Developing Web User Interfaces with Oracle ADF Faces.

• You can also write custom code for your dialogs using the APIs provided by Oracle ADF. Make sure when you write custom code that you do not import packages that are marked internal, as in this example:

  import oracle.adfinternal.controller.*;

  For information about the APIs that you can use to write custom code, see the following reference documents:

  • Java API Reference for Oracle ADF Controller

  • Java API Reference for Oracle ADF Faces

1. In the Applications window, double-click the existing task flow.
2. In the diagram for the task flow, double-click the view activity to open the associated page.
3. Select the command component that the end user clicks at runtime to invoke the bounded task flow as a modal dialog box (for example, a button component).
4. In the Properties window, expand the Common section and enter the control flow case to invoke the bounded task flow in the Action field.

   For example, selectmultipleitems in Figure 28-1.

5. From the UseWindow dropdown list, select true to invoke the bounded task flow in a popup dialog.
6. In the diagram for the existing task flow, select the task flow call activity.
7. In the Properties window, expand the Behavior section and select true from the Run As Dialog dropdown list to run the bounded task flow as a dialog.

   The bounded task flow that the task flow activity calls can now behave as a dialog; it can be invoked by the command component you configured in Steps 3 to 5 and can return a value to the view activity that renders the command component, as described in How to Return a Value From a Modal Dialog. Note that you need to make these other changes to run a bounded task flow in a modal dialog. Setting the run-as-dialog attribute to true is not sufficient.

8. Select external-window (the default value) from the Display Type dropdown list if you want to render the dialog in an external browser window or inline-popup if you want to render the dialog in the same browser window.

1. In the Applications window, double-click the task flow that contains the task flow call activity to invoke the bounded task flow to render in a modal dialog.
2. In the diagram editor, select the task flow call activity.
3. In the Properties window, expand the Behavior section and select true from the Run As Dialog dropdown list.
4. In the Dialog Return Value field, enter the name of the return value definition you specified for the target bounded task flow.

   For information about how to specify the return value definition on a bounded task flow, see Configuring a Return Value from a Bounded Task Flow.

5. In the Applications window, double-click the page that launches the modal dialog.
6. In the design editor, select the input component and, in the Properties window, expand the Behavior section to specify an EL expression in the PartialTriggers field.

   The EL expression you specify identifies the command component, accepts the return value of the command component, and specifies a backing bean. For example, enter an EL expression with syntax similar to the following:

   #{pageFlowScope.backingBean.gotoModalDialog}

   where gotoModalDialog identifies the command component.

7. In the design editor, select the command component and, in the Properties window, expand the Behavior section and enter an EL expression that references a return listener method in the page's backing bean as a value in the ReturnListener field.

   The return listener method you specify processes the return event that is generated when an end user dismisses the modal dialog. In the Summit ADF task flow sample application, the command component in the Orders.jsff page fragment specifies the following EL expression:

   #{viewScope.OrdersBackingBean.onShuttleTaskFlowReturn}

<af:button text="Edit" 
    id="b1" binding="#{backingBeanScope.backing_launch_page.b1}"
    action="edit" useWindow="true"
    returnListener="#{backingBeanScope.backing_launch_page.backFromPopup}"/>

public void backFromPopup(ReturnEvent returnEvent) {
        AdfFacesContext adfFacesContext;
        adfFacesContext = AdfFacesContext.getCurrentInstance();
        adfFacesContext.addPartialTarget(this.getF1());
}

1. In the Applications window, double-click the task flow that invokes the bounded task flow that renders in a modal dialog.
2. In the diagram, double-click the view activity that references the page where your end user invokes a command component to launch the modal dialog.
3. In the design editor, select the command component.
4. In the Properties window, expand the Behavior section and, from the ReturnListener field under the Secondary Window label, select Edit from the icon that appears when you hover over the property field to specify the name of the backing bean method that you want JDeveloper to generate.
5. In the Edit Property: ReturnListener dialog, click New beside the Managed Bean field.
6. In the Create Managed Bean dialog, name the bean and the class, set the bean's scope, and click OK.
7. In the Edit Property: ReturnListener dialog, click New beside the Method field.
8. In the Create Method dialog, name the method and click OK.
9. In the Edit Property: ReturnListener dialog, click OK.
10. In the Applications window, expand Application Sources and then expand the package that contains the backing bean class and method that you created in Steps 3 to 9.
11. Write a method body to invoke a partial page render event on your page.

If your Fusion web application renders modeless dialogs (non modal dialogs without task flows) and also uses ADF Controller features, such as task flows, you specify the dialog:syntax in the control flow rules of the application's adfc-config.xml file rather than the faces-config.xml file. Specify dialog:syntax in navigation rules within the faces-config.xml file if your Fusion web application does not use ADF Controller features, as described in Using the ADF Faces Dialog Framework Instead of Bounded Task Flows.

The following example shows what you can specify in the adfc-config.xml file. Note that although this example references a JSP page, you can define a view activity that invokes either a JSF page or a page fragment file.

<?xml version="1.0" encoding="windows-1252" ?> 
  <adfc-config xmlns="http://xmlns.oracle.com/adf/controller" version="1.2" id="__1"> 
    <view id="view1"
        <page>/view1.jsf</page> 
    </view>
    <view id="dialog"> 
       <page>/dialog/untitled1.jsf</page> 
   </view> 
   <control-flow-rule> 
        <from-activity-id>test</from-activity-id> 
        <control-flow-case> 
          <from-outcome>dialog:test</from-outcome
          <to-activity-id>dialog</to-activity-id>
         </control-flow-case> 
</adfc-config>

1. In the Applications window, expand the WEB-INF node and double-click adfc-config.xml.
2. In the diagram editor, create a page flow for your originating page and dialog pages.

   For more information, see How to Add a Control Flow Rule to a Task Flow.

3. When creating navigation rules to the dialog pages, the outcome must begin with dialog:. For example, in the login sample application shown in Figure 28-2, the outcome from the Login page to the New Account dialog page is dialog:newAccount.

1. In the Applications window, double-click the JSF page.
2. In the ADF Faces page of the Components window, from the General Controls panel, drag and drop a command component (for example, a Button) onto the JSF page.

   For more information about adding a command component to a page, see the "Using Buttons and Links for Navigation" section in Developing Web User Interfaces with Oracle ADF Faces.

   Note the following when setting the attributes on the command component:

   • Action: Set the action attribute to the outcome that navigates to the dialog, as created in How to Define a JSF Navigation Rule for Opening a Dialog.

     Tip:

     The action value can be either a static string or the return of a method on a managed bean.

     For example, the action attribute on the command component of the Login page is bound to a method that determines whether to navigate to the Orders page or to the Error dialog page, based on the returned outcome. If the method returns dialog:error, the error dialog opens. If the method returns success, the user navigates to the Orders page.

   • ActionListener: As an alternative to setting the action attribute, configure the actionListener attribute to invoke the launchDialog method from an instance of the following class:

     oracle.adf.view.rich.context.AdfFacesContext

     For more information about the launchDialog method and the AdfFacesContext class, see the Java API Reference for Oracle ADF Faces.

   • UseWindow: Set to true to have the dialog open.

     Tip:

     When set to false, ADF Faces shows the dialog page in the current window after preserving all of the state of the current page. You do not have to write any code to facilitate this.

   • WindowHeight and WindowWidth: Set the desired size of the dialog window. These values will set the contentWidth and contentHeight attributes on the popup component for the dialog.

     Tip:

     While the user can change the values of these attributes at runtime, the values will not be retained once the user leaves the page unless you configure your application to use change persistence. For information about enabling and using change persistence, see the "Allowing User Customization on JSF Pages" chapter in Developing Web User Interfaces with Oracle ADF Faces.

   • PartialSubmit: Set to true. This prevents the originating page from reloading (and hence being visible only momentarily) when the popup dialog is displayed.

   • WindowEmbedStyle: Set to inlineDocument if you want the dialog to open in a popup that belongs to the originating page. Set to window if you want the dialog to open in a separate browser.

   • WindowModalityType: Set to applicationModal if you want the dialog to be modal. Modal dialogs do not allow the user to return to the originating page until the dialog has been dismissed. Set to modeless if you want the user to be able to go back and forth between the originating page and the dialog.

1. In the Applications window, double-click the dialog page.
2. In the ADF Faces page of the Components window, from the General Controls panel, drag and drop a command component (for example, a Button) onto the dialog page.

   For more information about adding a command component to a page, see the "Using Buttons and Links for Navigation" section in Developing Web User Interfaces with Oracle ADF Faces.

3. If the command component will be used to close the window, in the Properties window, expand the Behavior section and select true from the Immediate dropdown list.
4. If the command component will be used to navigate to another page in the dialog process, configure the command component as though it were standard navigation. To do this, in the Properties window, expand the Common section and select false from the UseWindow dropdown list. This causes the next page to display in the same dialog window, preserving the state of the previous page.
5. If you need to end the dialog process and close the dialog, but do not need to return a value, in the Components window, from the Operations panel, in the Listeners group, drag a Return Action Listener and drop it as a child to the command component.

   The returnActionListener tag calls the returnFromDialog method on the AdfFacesContext object - no backing bean code is needed.

   No attributes are used with the af:returnActionListener tag. The immediate attribute on the af:button component is set to true if the user clicks Cancel without entering values in the required Password and Confirm Password fields, the default JSF ActionListener can execute during the Apply Request Values phase instead of the Invoke Application phase, thus bypassing input validation. For more information, see the "Using the JSF Lifecycle with ADF Faces" chapter in Developing Web User Interfaces with Oracle ADF Faces.

6. If you need to end the dialog process and do need to return a value, create a method on a managed bean that handles the action event and returns the needed values using the returnFromDialog method on the current instance of AdfFacesContext.

   Note:

   The AdfFacesContext.returnFromDialog() method returns null. This is all that is needed in the backing bean to handle the Cancel action event.

   For example, when the user clicks Done on the Account Details page, the process ends and returns the user input values. The following example shows the code for the event handler method to which the Done button binds. The method gets the customer information, then either creates a Faces message for an incorrect password, or sets the values on the new customer object and return that object.

public void done(ActionEvent e)
{
  AdfFacesContext afContext = AdfFacesContext.getCurrentInstance();
  String firstname = afContext.getPageFlowScope().get("firstname").toString();
  String lastname = afContext.getPageFlowScope().get("lastname").toString();
  String street = afContext.getPageFlowScope().get("street").toString();
  String zipCode = afContext.getPageFlowScope().get("zipCode").toString();
  String country = afContext.getPageFlowScope().get("country").toString();
  String password = afContext.getPageFlowScope().get("password").toString();
  String confirmPassword =
   afContext.getPageFlowScope().get("confirmPassword").toString();
  if (!password.equals(confirmPassword))
  {
    FacesMessage fm = new FacesMessage();
    fm.setSummary("Confirm Password");
    fm.setDetail("You've entered an incorrect password. Please verify that you've
     entered a correct password!");
    FacesContext.getCurrentInstance().addMessage(null, fm);
  }
  else
  {
    //Get the return value 
    Customer cst = new Customer();
    cst.setFirstName(firstname);
    cst.setLastName(lastname);
    cst.setStreet(street);
    cst.setPostalCode(zipCode);
    cst.setCountry(country);
    cst.setPassword(password);
    // And return it
    afContext.getCurrentInstance().returnFromDialog(cst, null);
  }
}

When the dialog is dismissed, ADF Faces generates a return event (ReturnEvent). The AdfFacesContext.returnFromDialog() method sends a return value as a property of the return event. The return event is delivered to the return listener (ReturnListener) that is registered on the command component that opened the dialog (for example, the New User link on the Login page). How you handle the return value is described in How to Handle the Return Value.

1. In the Applications window, double-click the JSF page that contains the command component used to navigate to the dialog page.
2. In the design editor, select the command component used to navigate to the dialog page.
3. In the Properties window, expand the Behavior section.
4. From the icon that appears when you hover over the LaunchListener property field, select Edit.
5. In the Edit Property: LaunchListener dialog, click New beside the Managed Bean field.
6. In the Create Managed Bean dialog, name the bean and the class, set the bean's scope, and click OK.
7. In the Edit Property: LaunchListener dialog, click New beside the Method field.
8. In the Create Method dialog, name the method and click OK and click OK to close the Edit Property: LaunchListener dialog.
9. In the Applications window, expand Application Sources and then expand the package that contains the bean class and method that you created in Steps 3 to 8.
10. In the source editor, write a handler method for the LaunchEvent that uses the getDialogParameters method to get the parameters from a dialog.

    For example, in the sample application, a new user can enter a name in the Username field on the Login page, and then click the New User? link. When the New Account dialog page displays in a popup dialog, the First Name input field is automatically populated with the name that was entered in the Login page. To accomplish this, you create a handler that uses the getDialogParameters method to put the value of the username field into the dialog, as shown in the following example.

    public void handleLaunch(LaunchEvent event)
    {
      //Pass the current value of the field into the dialog
      Object usr = username;
      event.getDialogParameters().put("firstname", getUsername());
    }
    // Use by inputText value binding 
    private String username;
    public String getUsername()
    {
      return username;
    }
    public void setUsername(String username)
    {
      this.username = username;
    }
    

11. In the Applications window, double-click the dialog page.
12. On the dialog page, use the pageFlowScope object to retrieve the key and value via a special EL expression in the format #{pageFlowScope.someKey}, as shown in the following example.

    <af:inputText label="First name" value="#{pageFlowScope.firstname}"/>
    

In ADF Faces, a process always gets a copy of all the values that are in the pageFlowScope of the page from which a dialog is launched. When the getDialogParameters() method has added parameters to a Map, those parameters also become available in pageFlowScope, and any page in the dialog process can get the values out of pageFlowScope by referring to the pageFlowScope objects via EL expressions.

1. In the Applications window, double-click the JSF page that contains the command component used to navigate to the dialog page.
2. In the design editor, select the command component used to navigate to the dialog page.
3. In the Properties window, expand the Behavior section.
4. From the icon that appears when you hover over the ReturnListener property field, select Edit.
5. In the Edit Property: ReturnListener dialog, click New beside the Managed Bean field.
6. In the Create Managed Bean dialog, name the bean and the class, set the bean's scope, and click OK.
7. In the Edit Property: ReturnListener dialog, click New beside the Method field.
8. In the Create Method dialog, name the method and click OK and click OK to close the Edit Property: LaunchListener dialog.
9. In the Applications window, expand Application Sources and then expand the package that contains the bean class and method that you created in Steps 3 to 8.
10. In the source editor, write a handler method for the returnEvent. You use the getReturnValue() method to retrieve the return value, because the return value is automatically added as a property of the ReturnEvent.

    The following example shows the code for the return listener method that handles the return value.

    public void handleReturn(ReturnEvent event)
    {
      if (event.getReturnValue() != null)
      {
        Customer cst;
        String name;
        String psw;
        cst = (Customer)event.getReturnValue();
        name = cst.getFirstName();
        psw = cst.getPassword();
        CustomerList.getCustomers().add(cst);
        inputText1.setSubmittedValue(null);
        inputText1.setValue(name);
        inputText2.setSubmittedValue(null);
        inputText2.setValue(psw);
      }
    }
    

At runtime in the sample application, when ADF Faces delivers a ReturnEvent to the ReturnListener registered on the link component, the handleReturn() method is called and the return value is processed accordingly. The new user is added to a customer list, and as a convenience to the user any previously submitted values in the Login page are cleared and the input fields are populated with the new information.