17 Using Task Flows as Regions

This chapter describes how to render task flows in pages or page fragments using ADF regions.

This chapter includes the following sections:

17.1 Introduction to Using Task Flows in ADF Regions

You can render a bounded task flow in a JSF page or page fragment (.jsff) by using an ADF region. An ADF region comprises the following:

  • An af:region tag that appears in the page or page fragment where you render the region

  • An instance object that implements RegionModel from the following package:

    oracle.adf.view.rich.model

    For more information about RegionModel, see the Oracle Fusion Middleware Java API Reference for Oracle ADF Faces

  • A task flow binding (taskFlow) in the page definition that identifies the bounded task flow to use in the ADF region

When first rendered, the ADF region's content is that of the first view activity in the bounded task flow. The view activities used in the bounded task flow must be associated with page fragments, not pages.

You can pass values to the ADF Region using task flow binding input parameters or contextual events. In addition, you can configure the task flow binding's parametersMap property to determine what input parameters the task flow binding passes from the bounded task flow to the ADF region.

ADF regions can be configured so that you determine when the region activates or refreshes. You can also configure an ADF region and a bounded task flow so that navigation control stops in the bounded task flow and passes to the page that contains the ADF region. Finally, you can create dynamic regions (ADF dynamic regions) where the task flow binding determines at runtime what bounded task flow renders in the region and configure a dynamic region link so that end users can change the bounded task flow that renders in the ADF dynamic region at runtime.

17.1.1 Benefits of Executing a Task Flow in an ADF Region

A primary reason for executing a bounded task flow as an ADF region is reuse. You can isolate specific pieces of application functionality in a bounded task flow and an ADF region in order to reuse it throughout the application. You can extract, configure, and package application functionality within a bounded task flow so that it can be added to other pages using an ADF region. ADF regions can be reused wherever needed, which means they are not dependent on a parent page. This also means that you can isolate the presentation of the parent pages from the ADF region; menus, buttons, and navigation areas are not affected by what is displayed in the ADF region. If you modify a bounded task flow, the changes apply to any ADF region that uses the task flow.

17.1.2 Task Flows and ADF Region Use Cases and Examples

Figure 17-1 shows the Registration page (register.jspx) in the Fusion Order Demo application which renders two ADF regions. One of these regions (Registration Help) is static; it appears regardless of actions that an end user invokes elsewhere on the Registration page. It displays help information for the end user by rendering the view activities defined in the Fusion Order Demo application's help-task-flow.xml task flow. For more information about creating this type of region, see Section 17.2, "Creating an ADF Region."

The second region that register.jspx renders is a dynamic region (ADF dynamic region). The task flow that it renders depends on the end user's action. If the end user clicks Register as a customer on the registration page, the ADF dynamic region renders the customer registration task flow (customer-registration-task-flow.xml). Alternatively, if the end user clicks Register as an employee, the ADF dynamic region renders the employee registration task flow (employee-registration-task-flow.xml). For more information about creating this type of region, see Section 17.8, "Creating ADF Dynamic Regions."

Figure 17-1 ADF Dynamic Region and ADF Region in the Fusion Order Demo Application

ADF Regions in the Fusion Order Demo Application

The task flows that you render in an ADF region can be simple (for example, the help task flow has one view activity that renders help information) or can involve a number of steps where you guide end users through a process to complete a task, as in the case of the customer registration task flow.

Figure 17-2 shows parts of the customer registration task flow. It contains view activities that allow end users to review information they enter (for example, reviewCustomerInfo), an exception handler activity to display a message when an error occurs (errorPage), and task flow return activities to cancel or commit the changes that end users make. All these task flow activities can be rendered within an ADF region.

Figure 17-2 Customer Registration Bounded Task Flow in Fusion Order Demo Application

Customer Registration Task Flow in Fusion Order Demo

One special case is the task flow return activity. In many cases, you cannot return control when the bounded task flow finishes execution because there is no caller (except the page or page fragment that hosts the bounded task flow) to which you can return control. For this reason, design control flow appropriately in a bounded task flow that you intend to render in an ADF region.

17.1.3 Additional Functionality for Task Flows that Render in ADF Regions

You may find it helpful to understand how a task flow that renders in an ADF region interacts with other task flow and ADF functionality. Review the information in the following sections before you attempt to render a task flow in an ADF region.

17.1.3.1 Page Fragments and ADF Regions

A page fragment is a JSF JSP document (file extension is .jsff) that renders as content in another JSF page. A page fragment must not contain any of the following tags:

  • <af:document>

  • <f:view>

  • <f:form>

  • <html>

  • <head>

  • <body>

These tags can only appear once in a document and do not support nesting in a JSF JSP page. For example, a page fragment embedded in a page cannot have an <html> tag because the JSF JSP page already has one.

Example 17-1 contains an example of a simple page fragment. Unlike a JSF JSP page, it contains no <f:view> or <f:form> tags.

Example 17-1 Page Fragment Source Code

<?xml version='1.0' encoding='UTF-8'?>
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.1"
          xmlns:af="http://xmlns.oracle.com/adf/faces/rich">
  <af:commandButton text="commandButton 1" id="cb1"/>
</jsp:root>

You must nest a page fragment that you include in another JSF page within a region (af:region tag). A bounded task flow that you add to a JSF JSP page as a region cannot call pages; it must call page fragments.

17.1.3.2 View Ports and ADF Regions

A view port is a display area capable of navigating independently of other view ports. A browser window and an ADF region are both examples of view ports. The root view port displays the main page in a browser window. The root view port may have child view ports, for example, regions on the page, but does not have a parent view port.

Java classes that implement the ViewPortContext interface in the oracle.adf.controller package get you more information about view ports. For more information, see the Oracle Fusion Middleware Java API Reference for Oracle ADF Controller.

17.1.3.3 Security and ADF Regions

You can set security on a bounded task flow that displays in an ADF region and associated page definitions. If an end user displays a page that contains an ADF region he or she is not authorized to view, the contents of the ADF region do not display. No authentication mechanism is triggered. For more information, see Chapter 30, "Enabling ADF Security in a Fusion Web Application".

17.1.3.4 Parent Page Determines the Capabilities of an ADF Region

In some cases, a page may need to determine the capabilities currently available within one of the ADF regions that it contains. For example, the page may need to initiate control flow within the ADF region based on its current state using the queueActionEventInRegion() method. Region capabilities are used by a parent page to identify the current outcomes of one of its regions based on the region's current state. They identify to the parent page whether or not an outcome is possible within the region.

The following scenario describes how region capabilities might typically be used in an application:

  1. An ADF region within a page displays its associated page fragment.

  2. A user selects a button or performs some other action in the ADF region.

  3. The parent page identifies the outcomes (region capabilities) for the ADF region.

  4. The parent page updates its buttons based on the ADF region capabilities.

The syntax of an EL expression to determine an ADF region's capabilities is as follows:

#{bindings.[regionId].regionModel.capabilities['outcome']}

where regionId is the ID of the ADF region component on the page and outcome is the possible outcome being verified within the ADF region.

Region capabilities require the availability of the specified ADF region's regionModel through an EL expression. The EL expression should never access bindings in any other binding container other than the current binding container. Region capabilities cannot be used in some cases. For example, a nested ADF region where a regionModel cannot be reached within the current binding container. This is because a nested region's nested binding container might not yet exist or might have already been released.

17.2 Creating an ADF Region

You create an ADF region by dragging and dropping a bounded task flow that contains at least one view activity or one task flow call activity to the page where you want to render the ADF region. This makes sure that the ADF region you create has content to display at runtime.

The bound task flow's view activities must be associated with page fragments (.jsff). If you attempt to drag and drop a bounded task flow that is associated with pages rather than page fragments, JDeveloper does not display the context menu that allows you to create an ADF region. You can convert a bound task flow that uses pages to use page fragments. For more information, see Section 14.5.3, "How to Convert ADF Bounded Task Flows."

The context menu that JDeveloper displays to create an ADF region presents options to create a non-dynamic and a dynamic region. A dynamic region (ADF dynamic region) determines the bounded task flow that it renders at runtime. For more information about creating an ADF dynamic region, see Section 17.8, "Creating ADF Dynamic Regions." You determine, at design time, the bounded task flow that a non-dynamic region (ADF region) displays.

Before you create an ADF region, you need to do the following:

  • Create a bounded task flow with one or more view activities associated with page fragments or one task flow call activity to a task flow with view activities

    For more information, see Section 14.2, "Creating a Task Flow.".

  • Create a page to host the ADF region

17.2.1 How to Create an ADF Region

Drag a bounded task flow from the Application Navigator to the page where you want to render an ADF region.

Before you begin:

It may be helpful to understand the requirements for a bounded task flow that you use in an ADF region. For more information, see Section 17.2, "Creating an ADF Region."

You may also find it helpful to understand functionality that can be added using other task flow features and ADF region features. For more information, see Section 17.1.3, "Additional Functionality for Task Flows that Render in ADF Regions."

To create an ADF region:

  1. In the Application Navigator, drag the bounded task flow onto the JSF page and drop it where you want to locate the ADF region.

  2. From the context menu that appears, choose Create > Region.

    The Edit Task Flow Binding dialog appears if the bounded task flow that you drop on the JSF page has an input parameter defined, as described in Section 16.3, "How to Pass Parameters to an ADF Bounded Task Flow." For more information about specifying parameters for an ADF region, see Section 17.3, "Specifying Parameters for an ADF Region."

    Figure 17-3 Edit Task Flow Binding Dialog for an ADF Region

    Edit Task Flow Binding Dialog for an ADF Region
  3. In the Structure window, right-click the node for the ADF region that you added (af:region) and choose Go to Properties.

  4. Review or modify (as appropriate) the following properties which JDeveloper automatically populates with default values in the Property Inspector for the ADF region:

    • Id: An ID that the JSF page uses to reference the ADF region, for example, r1.

    • Value: An EL reference to the ADF region model, for example, #{bindings.region1.regionModel}. This is the region model that describes the behavior of the region.

    • Rendered: If true (the default value), the ADF region renders when the JSF page renders.

  5. For information about how to map parameters between the view activity associated with the JSF page and the ADF region, see Section 17.3, "Specifying Parameters for an ADF Region".

17.2.2 What Happens When You Create an ADF Region

When you drop a bounded task flow onto a JSF page to create an ADF region, JDeveloper adds an af:region tag to the page. The af:region tag references an object that implements RegionModel. Example 17-2 shows a sample of the metadata that JDeveloper adds to the JSF page.

Example 17-2 Metadata Added to a JSF Page to Create an ADF Region

<af:region value="#{bindings.tf_register_employee1.regionModel}"                   id="r1"/>

JDeveloper also adds a task flow binding to the page definition file of the page that hosts the ADF region. Example 17-3 shows a sample of the metadata that JDeveloper adds. The task flow binding provides a bridge between the ADF region and the bounded task flow. It binds a specific instance of an ADF region to its associated bounded task flow and maintains all information specific to the bounded task flow. The taskFlowId attribute specifies the directory path and the name of the source file for the bounded task flow.

Example 17-3 Metadata Added to Page Definition to Create a Task Flow Binding

<taskFlow id="tf_register_employee1"
              taskFlowId="/WEB-INF/tf_register_employee.xml#tf_register_employee"
              activation="deferred"
              xmlns="http://xmlns.oracle.com/adf/controller/binding"/>

The bounded task flow preserves all of the data bindings when you drop it on the JSF page. At runtime, a request for a JSF page containing an ADF region initially handles like any other request for a JSF page. As the JSF page definition executes, data loads in to the JSF page. When the component tree for the parent JSF page encounters the <af:region> tag, it executes it in order to determine the first page fragment of content to display. Once it determine the first page fragment of content, it adds the appropriate UI components from the page fragment to the component tree for the parent JSF page.

The task flow binding creates an object for its task flow that implements the following interface in order to get the current view activity:

oracle.adf.controller.ViewPortContext

The task flow binding's taskFlowId attribute can also reference an EL expression that evaluates to one of the following:

  • java.lang.String

  • oracle.adf.controller.TaskFlowId

You use this capability if you create an ADF dynamic region. For more information, see Section 17.8, "Creating ADF Dynamic Regions."

17.3 Specifying Parameters for an ADF Region

You can make input parameters that you defined for a bounded task flow available to an ADF region by adding them to the task flow binding that the ADF region references. Use EL expressions to reference input parameters available in memory scopes, managed beans, or the ADF binding layer.

Specifying input parameters is one method of providing information to an ADF region. An alternative method is to use contextual events. The nature of the information that you want to provide to the ADF region determines the method you choose to provide the information. For example, choose:

  • Input parameters if the required information is at the beginning of the task flow and a change in the value of this information requires a restart of the task flow.

    For example, you have a page that contains a table of employees. An ADF region on that page contains a task flow to enroll a selected employee in a benefits program. A change in the selected employee requires that you restart the benefits enrollment task flow from the beginning for the newly selected employee. Using input parameters to the task flow is the right decision for this use case.

    You can pass input parameters by reference or by value. If you pass by reference, an update on the main page for the selected employee's information, such as last name, is automatically reflected in the task flow running in the ADF region without restarting the task flow.

  • Contextual events if you can only determine the information to exchange after the start of a task flow and a change in the information does not require a restart of the task flow. For example, the Fusion Order Demo application uses contextual events to display the appropriate help topic when the customer registration task flow renders in the register.jspx page. For more information about contextual events, see Section 28.7, "Creating Contextual Events."

For information about creating an ADF region and adding task flow bindings, see Section 17.2, "Creating an ADF Region." For information about how to define an input parameter for a bounded task flow, see Section 16.3, "How to Pass Parameters to an ADF Bounded Task Flow".

17.3.1 How to Specify Parameters for an ADF Region

Use EL expressions to specify parameters available in memory scopes, managed beans, or the ADF binding layer as input for the ADF region.

Before you begin:

It may be helpful to understand the requirements for specifying parameters for an ADF region. For more information, see Section 17.3, "Specifying Parameters for an ADF Region."

You may also find it helpful to understand functionality that can be added using other task flow features and ADF region features. For more information, see Section 17.1.3, "Additional Functionality for Task Flows that Render in ADF Regions."

To specify input parameters for an ADF region:

  1. In the Application Navigator, right-click the JSF page that holds the ADF region and choose Go to Page Definition.

  2. In the overview editor for the page definition file, expand the Model section and select the task flow binding for which you want to specify parameters.

  3. Click the Edit icon to display the Edit Task Flow Binding dialog, as shown in Figure 17-4.

    If you defined input parameters for the bounded task flow, as described in Section 16.3, "How to Pass Parameters to an ADF Bounded Task Flow", the Edit Task Flow Binding dialog lists these parameters in the Input Parameters section.

    Note:

    You can write an EL expression that references a list of input parameters specified in a managed bean using the Input Parameters Map field of the Edit Task Flow Binding dialog. For more information about implementing this functionality, see Section 17.4, "Specifying Parameters for ADF Regions Using Parameter Maps."

    Figure 17-4 Edit Task Flow Binding Dialog

    Edit Task Flow Binding Dialog
  4. Write an EL expression that retrieves the value of each input parameter you want to specify for the ADF region. Note that you must write an EL expression for parameters that you defined as required. For example, write an EL expression similar to the following:

    #{pageFlowScope.inputParameter1}

  5. Click OK.

17.3.2 What Happens When You Specify Parameters for an ADF Region

JDeveloper writes entries that are child elements of the taskFlow element in the page definition of the JSF page, as illustrated in example Example 17-4.

Example 17-4 Metadata Entries to Specify Input Parameters for an ADF Region

 <taskFlow id="tflow_tf11"
              taskFlowId="/WEB-INF/tflow_tf1.xml#tflow_tf1"
              activation="deferred"
              xmlns="http://xmlns.oracle.com/adf/controller/binding">
      <parameters>
        <parameter id="inputParameter1"
                   value="#{pageFlowScope.inputParameter1}"/>
          <parameter id="inputParameter2"
                   value="#{pageFlowScope.inputParameter2}"/>         
      </parameters>
    </taskFlow>

At runtime, the values specified by the EL expression in the value attribute are passed to the ADF region.

17.4 Specifying Parameters for ADF Regions Using Parameter Maps

In addition (or as an alternative) to listing all the input parameters on the task flow binding, as described in Section 17.3, "Specifying Parameters for an ADF Region," you can use the parametersMap property of the task flow binding to specify a parameter map object on a managed bean. The parameter map object that you reference must be of a type that implements the following interface:

java.util.Map

The parameter map object that you reference specifies keys that map to the values you want to input to the ADF region. Using this approach reduces the number of parameter child elements that appear under the task flow binding (taskFlow) element in the page definition for the page. This approach also allows you more flexibility in determining what input parameters pass to the ADF region.

You can configure an ADF region or an ADF dynamic region's task flow binding to reference a parameter map. Make sure that the name of an input parameter you define for a bounded task flow matches the name of a key that you define in the parameter map object.

17.4.1 How to Create a Parameter Map to Specify Input Parameters for an ADF Region

You configure the task flow binding's parametersMap property to reference the parameter map object that defines the key-value pairs you want to pass to the ADF region.

Before you begin:

It may be helpful to understand the configuration options available to you when passing input parameters to an ADF region. For more information, see Section 17.4, "Specifying Parameters for ADF Regions Using Parameter Maps."

You may also find it helpful to understand functionality that can be added using other task flow and ADF region features. For more information, Section 17.1.3, "Additional Functionality for Task Flows that Render in ADF Regions."

To create a parameter map to specify input parameters for an ADF region:

  1. Create a managed bean or edit an existing managed bean so that it returns an object that implements the java.util.Map interface.

    Configure the managed bean so the object returns key-value pairs with the values that you want to pass to the ADF region. For more information about managed beans, see Section 20.4, "Using a Managed Bean in a Fusion Web Application."

  2. In the Application Navigator, right-click the JSF page that holds the ADF region and choose Go to Page Definition.

  3. In the overview editor for the page definition file, expand the Model section and select the task flow binding for which you want to specify a parameter map.

  4. Click the Edit icon to display the Edit Task Flow Binding dialog.

  5. From the dropdown list beside the Input Parameters Map, select Expression Builder.

  6. Write or build an EL expression that references a parameter map. For example, write an EL expression similar to the following:

    #{pageFlowScope.userInfoBean.parameterMap}

  7. Click OK.

17.4.2 What Happens When You Create a Parameter Map to Specify Input Parameters

At runtime, the task flow binding evaluates the EL expression specified for its parametersMap property and returns values to the ADF region from the managed bean for keys that match name of the input parameters defined for the bounded task flow that renders in the ADF region.

Example 17-5 shows code snippets from a managed bean that puts two values (isLoggedIn and principalName) into a parameter map named parameterMap.

Example 17-5 Managed Bean Defining a Parameter Map

import java.util.HashMap;
import java.util.Map;
 
public class UserInfoBean {
    private Map<String, Object> parameterMap = new HashMap<String, Object>();
 
    public Map getParameterMap() {
        
        parameterMap.put("isLoggedIn", getSecurity().isAuthenticated());
        parameterMap.put("principalName", getSecurity().getPrincipalName());
        return parameterMap;
    }
}

Figure 17-5 shows the Edit Task Flow Binding dialog after you close the Expression Builder dialog, having specified the parameter map object (parameterMap) shown in Example 17-5. The Input Parameters field in the Edit Task Flow Binding dialog lists the input parameters defined for the bounded task flow associated with this ADF region (checkout-flow). The task flow binding retrieves the values for these parameters from the managed bean shown in Example 17-5.

Figure 17-5 EL Expression Referencing Parameter Map on Task Flow Binding

Parameter Map Property for Task Flow Binding

Example 17-6 shows the metadata that appears for the task flow binding in the page definition of the page that renders the ADF region. The metadata for the task flow binding references both the bounded task flow (taskFlowId attribute) and the managed bean (parametersMap).

Example 17-6 Task Flow Binding Specifying a Parameter Map

<taskFlow id="checkoutflow1"
              taskFlowId="/WEB-INF/checkout-flow.xml#checkout-flow"
              activation="deferred"
              xmlns="http://xmlns.oracle.com/adf/controller/binding"
              parametersMap="#{pageFlowScope.userInfoBean.parameterMap}"/>

You specify the <parameterMap> element in the page definition. The position of the <parameterMap> element within the <parameters> list determines whether or not values in the parameter map are used. The <parameterMap> element specifies an EL expression that returns an object that implements java.util.Map. The object contains task flow input parameter key/value pairs. The parameter set for the task flow is built from the order that is specified in the task flow binding.

Note:

If you specify Refresh="ifNeeded", parameters are not supported in the <parameterMap> element. The only condition that determines whether the region need to be refreshed is the boolean value returned by the evaluation of RefreshCondition. For more information, see Section 17.5.2, "What You May Need to Know About Refreshing an ADF Region".

17.5 Refreshing an ADF Region

You can configure when an ADF Region refreshes and whether it invokes a task flow. An ADF Region can only invoke a task flow when the ADF Region is in an active state. An ADF Region in an inactive state cannot invoke a task flow and returns a null value for the ID of the referenced task flow to the parent page.

17.5.1 How to Configure the Refresh of an ADF Region

You set values for the task flow binding of the task flow associated with the ADF Region to determine when an ADF Region switches from an inactive to an active state and to determine when an ADF Region refreshes.

Before you begin:

It may be helpful to understand the requirements for a bounded task flow that you use in an ADF region. For more information, see Section 17.5, "Refreshing an ADF Region."

You may also find it helpful to understand functionality that can be added using other task flow features and ADF region features. For more information, see Section 17.1.3, "Additional Functionality for Task Flows that Render in ADF Regions."

To configure the refreshing of an ADF Region:

  1. In the Application Navigator, select the page that contains the ADF Region, right-click and choose Go to Page Definition.

  2. In the page definition file, expand the Model view and select the task flow binding in the Executables section, as illustrated in Figure 17-6.

    Figure 17-6 Task Flow Binding

    Task Flow Binding
  3. In the Property Inspector, select a value from the dropdown list beside the Refresh property, as described in the following list:

    • default: refresh the ADF Region once when the page that hosts the ADF Region appears or when the EL expression you set as a value for the RefreshCondition property in step 4 returns true.

    • ifNeeded: refresh the ADF Region if the value of a task flow binding parameter changes. Do not set a value for the RefreshCondition property in step 4 if you select this value.

  4. If you selected default as the value for the Refresh property, select Edit from the dropdown list beside the RefreshCondition property to invoke the Expression Builder and write an EL expression that returns a boolean value at runtime. If the EL expression returns true, the ADF Region refreshes.

  5. In the Property Inspector, select a value from the dropdown list beside the activation property, as described in the following list:

    • conditional: activates the ADF region if the EL expression set as a value for the task flow binding active property returns true.

    • deferred: select this option if your application uses Facelets XHTML pages in the view layer and you want to activate the ADF region when a Facelets XHTML page first requests a viewID. If your application uses JSP technology in the view layer, selecting this option has the same effect as selecting immediate (the ADF region activates immediately).

      This option is recommended if your application uses Facelets XHTML pages. For more information about Facelets with ADF Faces, see the "Getting Started with ADF Faces" chapter in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

    • immediate: activates the ADF region immediately. This is the default value.

    The value that you select in the dropdown list determines when an ADF region switches from an inactive to an active state. An ADF region must have an active state before it can invoke a task flow.

  6. If you selected conditional as the value for the activation property, select Edit from the dropdown list beside the active property to invoke the Expression Builder and write an EL expression that returns a boolean value at runtime. If the EL expression returns true, the ADF Region invokes the task flow.

17.5.2 What You May Need to Know About Refreshing an ADF Region

An ADF region initially refreshes when the parent JSF page on which the region is located first displays. During the initial refresh, any ADF region task flow binding parameter values are passed in from the parent page. The parameter values are used to display the initial page fragment within the ADF region. If the bounded task flow relies on input parameter values that are not available when the page is first created, make sure that your task flow behaves correctly if the input parameter values are null by, for example, using a NullPointerException object. Alternatively (or additionally), make sure that the task flow does not activate until the input parameters become available by configuring the task flow binding's active property.

An ADF region task flow binding can be refreshed again based on one of the following task flow binding attributes:

  • Neither Refresh or RefreshCondition attributes are specified (default)

    If neither the Refresh nor RefreshCondition task flow binding attribute is specified, the ADF Region is refreshed only once at the time the parent page is first displayed unless you configure a value for the task flow binding's active property.

  • RefreshCondition="#{EL.expression}"

    The ADF region is refreshed a single time when its RefreshCondition evaluates true. The RefreshCondition must evaluate to a boolean value.

    At the time the RefreshCondition is evaluated, if the variable bindings is used within the EL Expression, the context refers to the binding container of the parent page, not the page fragment displayed within the ADF region.

    RefreshCondition is independent of the change of value of binding parameters. If the task flow binding parameters do not change, nothing within the ADF region will change.

  • Refresh="ifNeeded"

    Any change to a task flow binding parameter value causes the ADF region to refresh.

    If the ADF region task flow binding does not have parameters, Refresh="ifNeeded" is equivalent to not specifying the Refresh attribute.

    If you set Refresh to ifNeeded, the RefreshCondition attribute should not be specified.

    Refresh="ifNeeded" is not supported if you pass parameters to the task flow binding using a dynamic parameter map. You must instead use the RefreshCondition="#{EL.Expression}".

    For more information about specifying parameter values using a parameter map, see Section 17.4, "Specifying Parameters for ADF Regions Using Parameter Maps."

The RefreshCondition and Refresh properties are mutually exclusive. The Refresh="ifNeeded" property takes precedence over RefreshCondition. If the bindings variable is used within the EL expression at the time RefreshCondition is evaluated, the context refers to the binding container of the parent page, not the page fragment displayed within the ADF region. The expression is evaluated during the PrepareRender phase of the ADF page lifecycle. For more information, see Chapter 21, "Understanding the Fusion Page Lifecycle".

Example 17-7 contains a sample task flow binding located within the page definition of a page on which an ADF region has been added.

Example 17-7 Refresh Option Specified in ADF Region Binding

<taskFlow id="Department1" taskFlowId="/WEB-INF/Department#Department"
                   Refresh="ifNeeded"
                   xmlns="http://xmlns.oracle.com/adf/controller/binding">
        <parameters>
        <parameter id="DepartmentId" value="#{bindings.DepartmentId.inputValue}"
                   xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
      </parameters>
</taskFlow>

You do not need to refresh an ADF region to refresh the data controls inside the ADF region. During the ADF lifecycle, the refresh events telling the iterators to update will be propagated to the binding container of the current page of the ADF region.

17.6 Configuring Activation of an ADF Region

You can configure when an ADF region activates. This determines when the task flow contained in the ADF region activates. Configuring the activation of ADF regions can optimize the performance of a Fusion web application's page. For example, a page that contains 5 ADF regions may reference 5 task flows. You may not want these 5 task flows to execute simultaneously when the Fusion web application page loads so you configure an activation property to determine when a task flow executes.

17.6.1 How to Configure Activation of an ADF Region

You configure the activation property for the task flow binding associated with the ADF region to determine when to activate the ADF region.

Before you begin:

It may be helpful to understand the configuration options for activating an ADF region. For more information, see Section 17.6, "Configuring Activation of an ADF Region."

You may also find it helpful to understand functionality that can be added using other task flow features and ADF region features. For more information, see Section 17.1.3, "Additional Functionality for Task Flows that Render in ADF Regions."

To configure the activation of an ADF Region:

  1. In the Application Navigator, select the page that contains the ADF region(s), right-click and choose Go to Page Definition.

  2. In the page definition file, expand the Model view and select the task flow binding in the Executables section, as illustrated in Figure 17-7.

    Figure 17-7 Task Flow Bindings for ADF Region Configured for Activation

    Task Flow Binding
  3. In the Property Inspector, select a value from the dropdown list beside the activation property, as described in the following list:

    • conditional: activates the ADF region if the EL expression set as a value for the task flow binding active property returns true.

    • deferred: select this option if your application uses Facelets XHTML pages in the view layer and you want to activate the ADF region when a Facelets XHTML page first requests a viewID. If your application uses JSP technology in the view layer, selecting this option has the same effect as selecting immediate (the ADF region activates immediately).

      This option is recommended if your application uses Facelets XHTML pages. For more information about Facelets with ADF Faces, see the "Getting Started with ADF Faces" chapter in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

    • immediate: activates the ADF region immediately. This is the default value.

    The value that you select in the dropdown list determines when an ADF region switches from an inactive to an active state. An ADF region must have an active state before it can invoke a task flow.

  4. If you selected conditional as the value for the activation property, select Edit from the dropdown list beside the active property to invoke the Expression Builder and write an EL expression that returns a boolean value at runtime. If the EL expression returns true, the ADF region invokes the task flow. If the EL expression returns false, the ADF region deactivates a task flow that was active in the ADF region.

17.6.2 What Happens When You Configure Activation of an ADF Region

The behavior of the ADF region at runtime depends on the options that you set for the activation property.

Figure 17-8 shows the default behavior where all task flows in ADF regions execute when the page loads the ADF regions (Tab # 1, Tab # 2, Tab # 3).

Figure 17-8 Default Activation of ADF Regions

Default Activation of Task Flows

Figure 17-9 shows an example where the activation property was set to deferred and the application uses Facelets. The regions in Tab # 1 and Tab # 2 have an active state because the end user navigated to these regions. The region in Tab # 3 is inactive.

Figure 17-9 Deferred Activation of ADF Regions

Deferred Activation of ADF Regions

Figure 17-10 shows an example where the activation property was set to conditional and the active property to an EL expression that returns a boolean value at runtime. The region in Tab # 1 is in an active state because the EL expression specified for the active property returns true. The regions in Tab # 2 and Tab # 3 are inactive because the EL expression specified for the active property returns false.

Note that the following events occur if a region deactivates a task flow (the value returned by the active property changes from true to false):

Figure 17-10 Conditional Activation of ADF Regions

Conditional Activation of ADF Regions

17.7 Navigating Outside an ADF Region's Task Flow

A bounded task flow running in an ADF region may need to trigger navigation of its parent view activity or to navigate to the root page of its application. The parent action activity exposes properties (parent-outcome and root-outcome) that you configure if you want to implement either of these use cases.

For example, you might specify a value for parent-outcome if you have a page that displays employee information and an ADF region that contains an enroll button for an employee. After the enroll page completes and the ADF region returns, the employee information page refreshes with the next employee.

Note:

An ADF region does not maintain state when you navigate away from the region.

17.7.1 How to Trigger Navigation Outside of an ADF Region's Task Flow

You add a parent action activity to the bounded task that runs in the ADF region and configure it so that it navigates to the parent's view activity.

Before you begin:

It may be helpful to understand the configuration options for activating an ADF region. For more information, see Section 17.6, "Configuring Activation of an ADF Region."

You may also find it helpful to understand functionality that can be added using other task flow features and ADF region features. For more information, see Section 17.1.3, "Additional Functionality for Task Flows that Render in ADF Regions."

To trigger navigation outside of an ADF region's task flow:

  1. In the Application Navigator, double-click the XML file for the bounded task flow that runs in the ADF region.

  2. In the ADF Task Flow page of the Component Palette, select Parent Action and drag it to the bounded task flow.

  3. Select the parent action activity in the diagram for the bounded task flow.

  4. In the Property Inspector, choose the appropriate option:

    • Parent Outcome: enter a literal value or write an EL expression that returns an outcome so that the parent action activity navigates to the parent view activity. The outcome is then used to navigate the parent view activity's task flow rather than navigating the ADF region's bounded task flow.

      The parent view activity's task flow should contain a control flow case or wildcard control flow rule that accepts the value you specify for parent-outcome.

    • Root Outcome: enter a literal value or write an EL expression that returns an outcome so that the parent action activity navigates to the root page of the application.

    Note:

    Parent Outcome and Root Outcome are mutually exclusive.
  5. (Optional) In the Outcome field, enter a literal value that specifies an outcome for control flow within the ADF region after the parent action activity adds parent-outcome or root-outcome to the appropriate queue.

    Specifying an outcome element is useful in cases where the parent view activity or root page does not navigate as a result of the parent-outcome or root-outcome sent by the parent action activity. In addition, the ADF region should not continue to display the same view. If you do not specify a value for outcome, the ADF region's viewId remains unchanged.

17.7.2 What Happens When You Configure Navigation Outside a Task Flow

At design time, JDeveloper writes entries to the source file for the bounded task flow based on the property values you set for the parent action activity. Example 17-8 shows sample entries that JDeveloper generates when you write a literal value for the Parent Outcome and Outcome properties of the parent action activity.

Example 17-8 Metadata for a Parent Action Activity with a Parent Outcome

<parent-action id="parentAction1">        <parent-outcome>parent_outcome</parent-outcome>        <outcome id="__2">outcome</outcome>    </parent-action>

Example 17-9 shows sample entries that JDeveloper generates when you write a literal value for the Root Outcome and Outcome properties of the parent action activity.

Example 17-9 Metadata for a Parent Action Activity with a Root Outcome

<parent-action id="parentAction1">
      <root-outcome>root_outcome</root-outcome>
      <outcome id="__2">outcome</outcome>
</parent-action>

At runtime, the bounded task flow navigates to its parent view activity or the root page of the Fusion web application depending on the property that you configured for the parent action activity.

17.8 Creating ADF Dynamic Regions

An ADF dynamic region is an ADF region where the task flow binding dynamically determines the value of its taskFlowId attribute at runtime. This allows the Fusion web application to determine which bounded task flow to execute within the ADF dynamic region based on the result of evaluation of the task flow binding's taskFlowId attribute.

Figure 17-11 shows a runtime example from the Fusion Order Demo application where the register.jspx page renders a different registration task flow in its center facet in response to the command component button that the end user clicks. For example, if the end user clicks Register as an employee the Fusion Order Demo application renders the employee-registration-task-flow in the ADF dynamic region.

At runtime, the ADF dynamic region swaps the task flows that it renders during the Prepare Render lifecycle phase. To give components from a previous task flow the opportunity to participate smoothly in the lifecycle phases, do not navigate off the regionModel until the JSF Invoke Application lifecycle phase. It is good practice, therefore, not to navigate a task flow in a dynamic region in response to contextual events. For more information about lifecycle phases, see Chapter 21, "Understanding the Fusion Page Lifecycle," and for more information about contextual events, see Section 28.7, "Creating Contextual Events."

Figure 17-11 Customer Registration Task Flow in an ADF Dynamic Region

Customer Registration Task Flow in an ADF Dynamic Region

You create an ADF dynamic region by dragging and dropping a bounded task flow to the page where you want to render the ADF dynamic region. The view activities in the bounded task flow must be associated with page fragments (.jsff).

If you attempt to drag and drop a bounded task flow that is associated with pages rather than page fragments, JDeveloper does not display the context menu that allows you to create an ADF dynamic region. You can convert a bound task flow that uses pages to use page fragments. For more information, see Section 14.5.3, "How to Convert ADF Bounded Task Flows."

After you create an ADF dynamic region, you can add additional bounded task flows to the dynamic region by creating ADF dynamic region links, as described in Section 17.9, "Adding Additional Task Flows to an ADF Dynamic Region."

17.8.1 How to Create an ADF Dynamic Region

Drag and drop bounded task flows to the page where you want to render the ADF dynamic region.

Before you begin:

It may be helpful to understand the configuration options available to you when creating an ADF dynamic region. For more information, see Section 17.8, "Creating ADF Dynamic Regions."

You may also find it helpful to understand other functionality that can be added using other task flow and ADF region features. For more information, see Section 17.1.3, "Additional Functionality for Task Flows that Render in ADF Regions."

To create an ADF dynamic region:

  1. In the Application Navigator, select and open the JSF page where you want to create the ADF dynamic region.

  2. Drag and drop the first bounded task flow onto the JSF page.

  3. From the context menu that JDeveloper displays, choose Create > Dynamic Region.

  4. Choose the appropriate option in the Choose Managed Bean for Dynamic Region dialog that JDeveloper displays:

    • If you want an existing managed bean to store the bounded task flow's ID, select an existing managed bean from the Managed Bean dropdown list.

      The managed bean passes the value of the bounded task flow's ID into the task flow binding of the ADF dynamic region.

    • If no managed bean exists for the page, click the Add icon next to the Managed Bean dropdown list to create a new one. Enter values in the dialog that appears as follows:

      1. Bean Name: Enter a name for the new managed bean. For example, enter DynamicRegionBean.

      2. Class Name: Enter the name of the new managed bean class.

      3. Package: Enter the name of the package that is to contain the managed bean or browse to locate it.

      4. Extends: Enter the name of the Java class that the managed bean extends. The default value is java.lang.Object.

      5. Scope: This field is read-only and its value is set to backingBean. For more information about the memory scope for managed beans, see Section 14.2.4, "What You May Need to Know About Memory Scope for Task Flows."

      6. Click OK to close the dialogs where you configure the managed bean.

  5. Choose the appropriate option in the Edit Task Flow Binding dialog that JDeveloper displays:

    Figure 17-12 shows the Edit Task Flow Binding dialog that JDeveloper displays after you configure a managed bean.

    Note:

    You can write an EL expression that references a list of input parameters specified in a managed bean using the Input Parameters Map field of the Edit Task Flow Binding dialog. For more information about implementing this functionality, see Section 17.4, "Specifying Parameters for ADF Regions Using Parameter Maps."

    Figure 17-12 Edit Task Flow Binding Dialog for an ADF Dynamic Region

    Edit Task Flow Binding Dialog for an ADF Dynamic Region
  6. Click OK.

17.8.2 What Happens When You Create an ADF Dynamic Region

When you drop a bounded task flow onto a JSF page to create an ADF dynamic region, JDeveloper adds an af:region tag to the page. The af:region tag contains a reference to a task flow binding. Example 17-10 shows a sample of the metadata that JDeveloper adds to the JSF page.

Example 17-10 Metadata Added to a JSF Page to Create an ADF Dynamic Region

<af:region value="#{bindings.dynamicRegion1.regionModel}" id="r1"/>

JDeveloper also adds a task flow binding to the page definition file of the page that hosts the ADF dynamic region. Example 17-11 shows a sample of the metadata that JDeveloper adds. The task flow binding provides a bridge between the ADF dynamic region and the bounded task flow. It binds the ADF dynamic region to the bounded task flow and maintains all information specific to the bounded task flow.

Example 17-11 Metadata Added to Page Definition to Create a Task Flow Binding

<taskFlow id="dynamicRegion1"
      taskFlowId="${backingBeanScope.ManagedBeanName.dynamicTaskFlowId}"
              activation="deferred"
              xmlns="http://xmlns.oracle.com/adf/controller/binding"/>

The taskFlowId attribute in the task flow binding metadata specifies the managed bean that determines at runtime what bounded task flow to associate with the ADF dynamic region. JDeveloper creates this managed bean or modifies an existing managed bean to store this data. Example 17-12 shows extracts of the code that JDeveloper writes to the managed bean.

Example 17-12 Managed Bean Entries to Retrieve Bounded Task Flow for an ADF Dynamic Region

import oracle.adf.controller.TaskFlowId;
 ...
    private String taskFlowId = "/directoryPath/toTaskFlow";
 ...
    public TaskFlowId getDynamicTaskFlowId() {
        return TaskFlowId.parse(taskFlowId);
    }
...

At runtime, the managed bean stores the value of the bounded task flow's ID (taskFlowId) that displays inside the ADF dynamic region. The managed bean swaps the different bounded task flows into the task flow binding of the ADF dynamic region.

When an ADF dynamic region reinitializes, the Fusion web application must reinitialize the task flow binding associated with the ADF dynamic region. This includes evaluating if there are new input parameters and input parameter values to pass to the ADF dynamic region.

17.9 Adding Additional Task Flows to an ADF Dynamic Region

An ADF dynamic region link swaps a bounded task flow for another bounded task flow within an ADF dynamic region. An end user clicks a command component (for example, a button or a link) to update the ADF dynamic region with the new bounded task flow.

For example, a bounded task flow in the ADF dynamic region displays general information about an employee such as an ID and photo. When the end user clicks a link command component labeled Details, the ADF dynamic region updates with a table containing more information about the employee from another bounded task flow. The end user's action (clicking the link) invokes a method on the ADF dynamic region's managed bean. The value of the new bounded task flow is passed to the method, and the ADF dynamic region refreshes with the new bounded task flow. The new bounded task flow now displays within the ADF dynamic region.

By default, a ADF dynamic region link swaps another bounded task flow in for the original, but cannot swap back to the original. To toggle back to the original bounded task flow, you could add a second ADF dynamic region link on the page that, when clicked, swaps the current task flow back to the original one.

You can add an ADF dynamic region link if you already have at least one ADF dynamic region on a page and are adding a new bounded task flow as an ADF dynamic region to the same page. After you drop the bounded task flow on the page and choose to create an ADF dynamic region link, a menu displays all of the dynamic regions currently on the page, as shown in Figure 17-13.

JDeveloper displays a list of the current dynamic regions in a document when you choose Dynamic Region Link from the menu that appears after you drag and drop a bounded task that you want to add as an option to an existing dynamic region in the document, as shown in Figure 17-13.

Figure 17-13 ADF Dynamic Region Link Menu

Dynamic Region Link Menu

Use this menu to select the ADF dynamic region within which you want to display the contents of the bounded task flow.

Tip:

You can use the values in the dynamic region link in other UI components. For example, you could create a selection list in which each of the items in the list links to a different bounded task flow. All of the linked bounded task flows would display in the same dynamic region. The links perform a method in the class behind the managed bean created to swap the bounded task flow it displays.

17.9.1 How to Create an ADF Dynamic Region Link

You drag and drop a bounded task flow to a page that already contains an ADF dynamic region and you select Dynamic Region Link on the context menu that JDeveloper displays to view a list of ADF dynamic regions to which you can create a link.

Before you begin:

It may be helpful to understand the configuration options required before you attempt to create an ADF dynamic region link. For more information, see Section 17.9, "Adding Additional Task Flows to an ADF Dynamic Region."

You may also find it helpful to understand functionality that can be added using other task flow and ADF region features. For more information, see Section 17.1.3, "Additional Functionality for Task Flows that Render in ADF Regions."

To create an ADF dynamic region link:

  1. In the Application Navigator, select and open the JSF page where you want to create the ADF dynamic region link.

    This procedure assumes that you have already added at least one ADF dynamic region to the JSF page that you open. For information about adding an ADF dynamic region to a JSF page, see Section 17.8, "Creating ADF Dynamic Regions."

  2. Drag a bounded task flow and drop it anywhere on the page.

    The view activities of the bounded task flow must be associated with page fragments You can convert a bounded task flow that uses pages to use page fragments. For more information, Section 14.5.3, "How to Convert ADF Bounded Task Flows.".

  3. From the context menu that JDeveloper displays, choose Dynamic Region Link.

    A menu displays a list of all ADF dynamic regions that have already been added to the page.

  4. Select the name of the ADF dynamic region in which you want to display the contents of the bounded task flow.

  5. Click OK.

17.9.2 What Happens When You Create an ADF Dynamic Region

JDeveloper adds a command link to the page, as shown in Example 17-13. JDeveloper also updates the managed bean for the ADF dynamic region and updates the corresponding task flow binding with any new parameters.

Example 17-13 Dynamic Region Link

<af:commandLink text="region2" action="#{RegionBean.region2}"
  id="dynamicRegionLink1"/>