23 Using Task Flows as Regions

This chapter describes how to render ADF task flows in pages or page fragments using ADF regions in your Fusion web application. Key features such as the ability to specify parameters, how to refresh or activate an ADF region, navigate to a parent page, and create dynamic ADF regions are also described.

This chapter includes the following sections:

23.1 About Using Task Flows in ADF Regions

You can execute a bounded task flow in a JSF page or page fragment (.jsff) by using 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.

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 Java API Reference for Oracle ADF Faces

  • One or other of the following:

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

    • A multi task flow binding (multiTaskFlow) in the page definition that identifies a list of bounded task flows 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.

Figure 23-1 shows how an ADF region references a bounded task flow using a task flow binding in the page definition file of the page that hosts the ADF region.

Figure 23-1 ADF Region Referencing a Bounded Task Flow

ADF Region Referencing a Bounded Task Flow

23.1.1 About Page Fragments and ADF Regions

A page fragment is a JSF document (file extension is .jsff) that renders as content in another JSF page. A page fragment should not have more than one root component. Wrapping multiple root components in a single root component helps you to optimize the display performance of the page fragment. In addition, if a page fragment has only one visual root component and a popup component (which is invisible to end users until invoked), consider wrapping these components in a single root component. For example, place the popup component in a panelStretchLayout component's bottom facet with the bottomHeight attribute set to 0 pixels.

If a page fragment has more than one root component, the Fusion web application logs a message at runtime, as shown in Example 23-1, where r1 identifies the ADF region that renders the page fragment.

Example 23-1 Log Message for a Page Fragment with Multiple Root Components

<RegionRenderer> <encodeAll> The region component with id: r1 has detected a page
 fragment with multiple root components. Fragments with more than one root
 component may not display correctly in a region and may have a negative impact
 on performance. It is recommended that you restructure the page fragment to have
 a single root component.

Apart from having only one root component element, 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 page. For example, a page fragment embedded in a page cannot have an <html> tag because the JSF page already has one.

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

Example 23-2 Page Fragment Source Code

<?xml version='1.0' encoding='UTF-8'?>
<ui:composition xmlns:ui="http://java.sun.com/jsf/facelets"
                     xmlns:af="http://xmlns.oracle.com/adf/faces/rich">
  <af:button text="button 1" id="b1"/>
</ui:composition>

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 page as a region cannot call pages; it must call page fragments.

23.1.2 About 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 Java API Reference for Oracle ADF Controller.

23.1.3 Task Flows and ADF Region Use Cases and Examples

Figure 23-2 shows the General Information page fragment (GeneralInfo.jsff) from the edit-customer-task-flow-definition.xml task flow in the Summit sample application for ADF task flows. This task flow renders in an ADF region and displays information about customers in a series of page fragments that authenticated users can navigate through and edit using the provided controls. For more information about creating this type of region, see Section 23.2, "Creating an ADF Region."

Figure 23-2 ADF Region in the Summit ADF Task Flow Sample Application

ADF Region in the Summit ADF Application for ADF Task Flows

Figure 23-2 also shows links (labeled Register as Employee and Register as Customer) that invoke different task flows in the ADF dynamic region that the showDetailItem component labeled Welcome renders. For more information about creating this type of region, see Section 23.9, "Creating ADF Dynamic Regions."

Figure 23-3 shows the edit-customer-task-flow-definition.xml task flow in JDeveloper. It contains three view activities to display information about customers to end users.

Figure 23-3 Edit Customer Task Flow in ADF Summit Application for ADF Task Flows

Edit Customer Task Flow

23.1.4 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. Following are links to other functionality that may be of interest.

23.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 bounded 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 20.6.4, "How to Convert Bounded Task Flows."

The context menu that appears to create an ADF region presents options to create a nondynamic 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 23.9, "Creating ADF Dynamic Regions." You determine at design time the bounded task flow that a nondynamic region (ADF region) displays.

23.2.1 How to Create an ADF Region

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

Before you begin:

It may be helpful to have an understanding of the requirements for a bounded task flow that you use in an ADF region. For more information, see Section 23.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 23.1.4, "Additional Functionality for Task Flows that Render in ADF Regions."

You will need to complete these tasks:

  • 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 20.2, "Creating a Task Flow."

  • Create a JSF page to host the ADF region.

    For more information, see the "How to Create JSF Pages" section of Developing Web User Interfaces with Oracle ADF Faces.

To create an ADF region:

  1. In the Applications window, double-click the JSF page where you want to locate the ADF region.

  2. From the Applications window, drag and drop the bounded task flow onto the JSF page, and from the context menu, choose Create > Region.

  3. If the Edit Task Flow Binding dialog appears, click OK.

    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 22.3.1, "How to Pass an Input Parameter to a Bounded Task Flow."

    For more information about specifying parameters for an ADF region, see Section 23.3, "Specifying Parameters for an ADF Region."

    Figure 23-4 Edit Task Flow Binding Dialog for an ADF Region

    Edit Task Flow Binding Dialog for an ADF Region

  4. In the Structure window, right-click the node for the ADF region that you added (af:region) and choose Go to Properties.

  5. Review or modify (as appropriate) the following fields which JDeveloper automatically populates with default values in the Properties window 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.

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

23.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 23-3 shows the af:region tag that appears in the Customers.jsff page fragment of the Summit ADF task flow sample application.

Example 23-3 Metadata Added to a JSF Page to Create an ADF Region

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

JDeveloper also adds a task flow binding to the page definition file of the page that hosts the ADF region. Example 23-4 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 23-4 Metadata Added to Page Definition to Create a Task Flow Binding

<taskFlow id="editcustomertaskflowdefinition1"
    taskFlowId="/WEB-INF/flows/edit-customer-task-flow-definition.xml#edit
    -customer-task-flow-definition"
    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 23.9, "Creating ADF Dynamic Regions."

23.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 Inventory Control tab in the Summit ADF task flow sample application uses contextual events to display the appropriate chart for product inventory in one region in response to the product that a user selects in another region. For more information, see Chapter 40, "Using Contextual Events."

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

23.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 have an understanding of the requirements for specifying parameters for an ADF region. For more information, see Section 23.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 23.1.4, "Additional Functionality for Task Flows that Render in ADF Regions."

To specify input parameters for an ADF region:

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

  2. In the overview editor, click the Bindings and Executables navigation tab, select the task flow binding for which you want to specify parameters and click the Edit icon.

  3. In the Edit Task Flow Binding dialog, write EL expressions that retrieve the values 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}

    Figure 23-5 shows the Edit Task Flow Binding dialog where the Input Parameters section lists a number of input parameters that were defined for the bounded task, as described in Section 22.3, "Passing Parameters to a Bounded Task Flow."

    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 23.4, "Specifying Parameters for ADF Regions Using Parameter Maps."

    Figure 23-5 Edit Task Flow Binding Dialog

    Edit Task Flow Binding Dialog

  4. Click OK.

23.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 23-5.

Example 23-5 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.

23.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 23.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 or the multi task flow binding (multiTaskFlow) in the page definition for the page. This approach also allows you more flexibility in determining what input parameters pass to the ADF region. In particular, it provides a way to pass parameters to ADF dynamic regions as the number of input parameters can differ between the different task flow bindings in an ADF dynamic region. For more information, see Section 23.9, "Creating ADF Dynamic Regions."

You can configure an ADF region or an ADF dynamic region's task flow binding to reference a parameter map. You can also configure a multi 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.

If you specify a parameter with the same id attribute in a <parameter> element and in a <parametersMap> element, the <parametersMap> element always takes precedence. This is because the <parametersMap> element may need to override the static value of the parameter if you create an ADF dynamic region, as described in Section 23.9, "Creating ADF Dynamic Regions."

23.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 have an understanding of the configuration options available to you when passing input parameters to an ADF region. For more information, see Section 23.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, see Section 23.1.4, "Additional Functionality for Task Flows that Render in ADF Regions."

You will need to complete this task:

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 26.4, "Using a Managed Bean in a Fusion Web Application."

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

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

  2. In the overview editor, click the Bindings and Executables navigation tab, select the task flow binding or multi task flow binding for which you want to specify a parameter map, and then click the Edit icon.

    The type of task flow binding that you select determines the dialog that appears.

  3. In the Edit Task Flow Binding dialog or the Edit Multi Task Flow Binding dialog, select Expression Builder from the Input Parameters Map dropdown menu.

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

    #{pageFlowScope.userInfoBean.parameterMap}

  5. Click OK.

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

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

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

Example 23-6 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 23-6 shows the Edit Task Flow Binding dialog after you close the Expression Builder dialog, having specified the parameter map object (parameterMap) shown in Example 23-6. 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 23-6.

Figure 23-6 EL Expression Referencing Parameter Map on Task Flow Binding

Parameter Map Property for Task Flow Binding

Example 23-7 shows the metadata that appears for the task flow binding in the page definition file 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 23-7 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.

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 23.5.2, "What You May Need to Know About Configuring an ADF Region to Refresh."

23.5 Configuring an ADF Region to Refresh

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.

23.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 have an understanding of the requirements for a bounded task flow that you use in an ADF region. For more information, see Section 23.5, "Configuring an ADF Region to Refresh."

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 23.1.4, "Additional Functionality for Task Flows that Render in ADF Regions."

To configure the refreshing of an ADF Region:

  1. In the Applications window, select the page that contains the ADF region, right-click and choose Go to Page Definition.

  2. In the page definition file, select the task flow binding or multi task flowing binding in the Executables section, as illustrated in Figure 23-7.

    Figure 23-7 Task Flow Binding

    Task Flow Binding

  3. Choose the appropriate option to refresh the ADF region.

    • Refresh if the value of a task flow binding parameter changes.

      In the Properties window, select ifNeeded from the Refresh dropdown list.

      Do not select ifNeeded if you want to set a value for the RefreshCondition property. The RefreshCondition property will not be evaluated if you select ifNeeded for the Refresh property.

    • Refresh if a condition that you specify returns true.

      In the Properties window, write an EL expression in the RefreshCondition field that returns a boolean value. If the EL expression returns true, the ADF region refreshes.

  4. In the Properties window, select a value from the activation dropdown list, 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) provided that the parent component for the ADF region is not a popup or panelTabbed component that has its childCreation attribute set to deferred. If this latter scenario occurs, the parent component (popup or panelTabbed) determines behavior.

      Use this option if your application uses Facelets XHTML pages. For more information about Facelets with ADF Faces, see the "Getting Started with ADF Faces and JDeveloper" chapter in Developing Web User Interfaces with Oracle ADF Faces.

    • 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.

  5. If you selected conditional as the value for the activation property, write an EL expression that returns a boolean value at runtime for the active property. If the EL expression returns true, the ADF region invokes the task flow.

23.5.2 What You May Need to Know About Configuring an ADF Region to Refresh

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:

  • taskFlowId

    This attribute specifies the directory path and the name of the source file for the bounded task flow. The ADF region refreshes if this attribute value changes.

  • Neither Refresh or RefreshCondition attributes are specified (default)

    If neither the Refresh or 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 property 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.

    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 23.4, "Specifying Parameters for ADF Regions Using Parameter Maps."

The Refresh="ifNeeded" property takes precedence over RefreshCondition and RefreshCondition will not be evaluated if you set Refresh="ifNeeded".

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 27, "Understanding the Fusion Page Lifecycle".

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

Example 23-8 Refresh Option Specified in ADF Region Binding

<taskFlow id="Department1" taskFlowId="/WEB-INF/Department#Department"
    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.

23.6 Configuring Activation of an ADF Region

You can configure when an ADF region activates. This has the effect of determining when the task flows contained in ADF regions activate. 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.

23.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 have an understanding of the configuration options for activating an ADF region. For more information, see Section 23.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 23.1.4, "Additional Functionality for Task Flows that Render in ADF Regions."

To configure the activation of an ADF region:

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

  2. In the page definition file, select the task flow binding or multi task flow binding in the Executables section, as illustrated in Figure 23-8.

    Figure 23-8 Task Flow Bindings for ADF Region Configured for Activation

    Task Flow Binding

  3. In the Properties window, select a value from the activation dropdown list, 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).

      Use this option if your application uses Facelets XHTML pages. For more information about Facelets with ADF Faces, see the "Getting Started with ADF Faces and JDeveloper" chapter in Developing Web User Interfaces with Oracle ADF Faces.

    • 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 in the activation dropdown list, write an EL expression that returns a boolean value at runtime for the active property. 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.

23.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 23-9 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 23-9 Default Activation of ADF Regions

Default Activation of Task Flows

Figure 23-10 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 23-10 Deferred Activation of ADF Regions

Deferred Activation of ADF Regions

Figure 23-11 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 23-11 Conditional Activation of ADF Regions

Conditional Activation of ADF Regions

23.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.

23.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 have an understanding of the configuration options for activating an ADF region. For more information, see Section 23.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 23.1.4, "Additional Functionality for Task Flows that Render in ADF Regions."

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

  1. In the Applications window, double-click the bounded task flow that runs in the ADF region.

  2. In the ADF Task Flow page of the Components window, from the Component panel, in the Activities group, drag and drop a Parent Action onto the diagram for the bounded task flow.

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

  4. In the Properties window, 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.

      For example, to navigate from an ADF region to the home page in your application, you specify a value for Root Outcome, as illustrated in Figure 23-12.

      Figure 23-12 Navigating to Home Page

      Navigating to Home Page

    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.

23.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 23-9 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 23-9 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 23-10 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 23-10 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.

23.7.3 What You May Need to Know About How a 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.

23.8 Configuring Transaction Management in an ADF Region

ADF task flows provide options to implement transactions, as described in Section 24.3, "Managing Transactions in Task Flows." You can choose whether a task flow shares or isolates its data controls with a calling task flow by setting a value for its data-control-scope property, as described in Section 24.2, "Sharing Data Controls Between Task Flows." Whether a task flow creates a new transaction depends on the values you choose for the transaction and data-control-scope properties, as described in Section 24.3.3, "What You May Need to Know About Sharing Data Controls and Managing Transactions."

If, for example, you share a task flow's data control with a calling task flow, a new transaction is created if you configure the task flow's transaction option to Always Begin New Transaction (new-transaction) or to Use Existing Transaction If Possible (requires-transaction). The requires-transaction option creates a new transaction only if a transaction does not already exist. The created transaction has the same lifespan as the ADF region that renders the task flow. This may cause behavior that you do not intend when the task flow renders in an ADF region. For example, if an ADF region refreshes, it restarts the task flow that it renders and causes the following events to occur:

There are a number of ways to prevent the inadvertent termination of a task flow's transaction by the refresh of an ADF region. All these options disassociate the lifespan of the transaction in the task flow that renders in an ADF region from the lifespan of the ADF region. These options make sure that the region's parent page owns the transaction and/or that the transaction starts before the region renders. Choose the most appropriate option for your application:

  • Set the transaction option on the taskflow that renders in the ADF region to Always Use Existing Transaction (requires-existing-transaction). This throws an exception if a transaction does not exist and prevents the ADF region from owning the transaction.

  • Set the calling task flow's transaction option to Always Begin New Transaction (new-transaction) so that the lifespan of the transaction is associated with the lifespan of the parent page.

  • Invoke the DataControlFrame interface's beginTransaction() method in the action that navigates to the parent page that contains the region.

  • Configure a method call activity that invokes the DataControlFrame interface's beginTransaction() method from a managed bean with a request scope before navigating to the parent page of the ADF region.

    The following code begins a transaction:

      public void beginTransaction()
  {
    BindingContext context = BindingContext.getCurrent();
 
    String dcFrameName = context.getCurrentDataControlFrame();
    DataControlFrame dcFrame = context.findDataControlFrame(dcFrameName);
    dcFrame.beginTransaction(new TransactionProperties());
  }

If you share the data controls of a task flow with a calling task flow, use the rollback or commit options exposed by the task flow's task flow return activity to commit or rollback changes rather than programmatically use the methods exposed by the ADF Model layer's DataControlFrame interface. Using the methods exposed by the DataControlFrame interface closes the transaction and may cause the task flow that renders in the ADF region to create a new transaction.

23.9 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 23-13 shows a runtime example from the Summit ADF task flow sample application where the index.jsf page renders a different registration task flow in the showDetailItem component labeled Welcome in response to the link component that the end user clicks. For example, if the end user clicks Register as Employee, the application renders the emp-reg-task-flow-definition.xml task flow in the ADF dynamic region. If the end user clicks Register as Customer, the application renders the edit-customer-task-flow-definition.xml 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 27, "Understanding the Fusion Page Lifecycle," and for more information about contextual events, see Chapter 40, "Using Contextual Events."

Figure 23-13 ADF Dynamic Region in the Summit ADF Task Flow Sample Application

ADF Dynamic Region in Summit ADF Application

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 20.6.4, "How to Convert 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 23.10, "Adding Additional Task Flows to an ADF Dynamic Region."

23.9.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 have an understanding of the configuration options available to you when creating an ADF dynamic region. For more information, see Section 23.9, "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 23.1.4, "Additional Functionality for Task Flows that Render in ADF Regions."

To create an ADF dynamic region:

  1. In the Applications window, double-click the JSF page where you want to create the ADF dynamic region.

  2. From the Applications window, drag and drop the first bounded task flow onto the JSF page, and from the context menu, choose Create > Dynamic Region.

  3. Choose the appropriate option in the Choose Managed Bean for Dynamic Region dialog:

    • 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. Make sure that the managed bean you select is not used by another 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 20.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.

  4. Choose the appropriate option in the Edit Task Flow Binding dialog:

    Figure 23-14 shows the Edit Task Flow Binding dialog that appears 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 23.4, "Specifying Parameters for ADF Regions Using Parameter Maps."

    Figure 23-14 Edit Task Flow Binding Dialog for an ADF Dynamic Region

    Edit Task Flow Binding Dialog for an ADF Dynamic Region

  5. Click OK.

23.9.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 23-11 shows the af:region tag that renders the ADF dynamic region in the index.jsf page of the Summit ADF task flow sample application.

Example 23-11 Metadata Added to a JSF Page to Create an ADF Dynamic Region

<af:region value="#{bindings.dynamicRegion1.regionModel}" id="r4"
                             rendered="#{WelcomePageBean.isRegistration}"/>

JDeveloper also adds a task flow binding to the page definition file of the page that hosts the ADF dynamic region. Example 23-12 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 23-12 Metadata Added to Page Definition to Create a Task Flow Binding

<taskFlow id="dynamicRegion1"
       taskFlowId="${WelcomePageBean.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 23-13 shows extracts of the code that JDeveloper writes to the managed bean.

Example 23-13 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.

23.10 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 (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 23-15.

A list of the current dynamic regions in a document appears 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 23-15.

Figure 23-15 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.

23.10.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 appears to view a list of ADF dynamic regions to which you can create a link.

Before you begin:

It may be helpful to have an understanding of the configuration required before you attempt to create an ADF dynamic region link. For more information, see Section 23.10, "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 23.1.4, "Additional Functionality for Task Flows that Render in ADF Regions."

You will need to complete this task:

Add at least one ADF dynamic region to the JSF page where you are going to create an ADF dynamic region link. For information about adding an ADF dynamic region to a JSF page, see Section 23.9, "Creating ADF Dynamic Regions."

To create an ADF dynamic region link:

  1. In the Applications window, double-click the JSF page where you want to create the ADF dynamic region link.

  2. From the Applications window, drag and drop a bounded task flow onto the JSF page and, from the context menu, choose Dynamic Region Link.

    Note:

    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, see Section 20.6.4, "How to Convert Bounded Task Flows."

  3. In the context menu that displays a list of the ADF dynamic regions that have already been added to the page, select the name of the ADF dynamic region in which you want to display the contents of the bounded task flow.

  4. Click OK.

23.10.2 What Happens When You Create an ADF Dynamic Region

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

Example 23-14 Dynamic Region Link

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

23.11 Configuring a Page To Render an Unknown Number of Regions

You can configure a page at design time when you do not know the number of regions that render in the page at runtime. For example, you want to add or remove regions to tabs using the panelTabbed component. Each tab that you add or remove renders a region that references a bounded task flow.

To implement this functionality, you configure the JSF page definition file's multiTaskFlow element to reference a list of task flow bindings contained in a managed bean of the following type:

oracle.adf.controller.binding.TaskFlowBindingAttributes

Example 23-15 shows the code for the class of a managed bean named MultiBean that returns a list containing two task flows.

Example 23-15 Managed Bean Returning a List of Task Flow Bindings

package view;
 
import java.util.ArrayList;
import java.util.List;
 
import oracle.adf.controller.TaskFlowId;
import oracle.adf.controller.binding.TaskFlowBindingAttributes;
 
public class MultiBean {
    private List<TaskFlowBindingAttributes> mTaskFlowBindingAttrs = new 
                   ArrayList<TaskFlowBindingAttributes>(5);
 
    public MultiBean() {
        TaskFlowBindingAttributes tfAttr = new TaskFlowBindingAttributes();
        tfAttr.setId("region1");
        tfAttr.setTaskFlowId(new TaskFlowId("/WEB-INF/r1.xml", "r1"));
        mTaskFlowBindingAttrs.add(tfAttr);
 
        tfAttr = new TaskFlowBindingAttributes();
        tfAttr.setId("region2");
        tfAttr.setTaskFlowId(new TaskFlowId("/WEB-INF/r2.xml", "r2"));
        mTaskFlowBindingAttrs.add(tfAttr);
 
    }
 
    public List<TaskFlowBindingAttributes> getTaskFlowList() {
        return mTaskFlowBindingAttrs;
    }
}

For more information about the TaskFlowBindingAttributes class, see the Java API Reference for Oracle ADF Controller.

At runtime, the multiTaskFlow binding references a list of one or more task flows that an end user can add or remove to the page using command components that you also expose. Figure 23-16 shows the relationships between the different parts that make up this use case.

Note:

The page fragments that the bounded task flows render must use the Facelets document type.

Figure 23-16 ADF Regions Derived from a Multi Task Flow Binding

ADF Regions Derived from a Multi Task Flow Binding

23.11.1 How to Configure a Page to Render an Unknown Number of Regions

Configure the JSF page definition file's multiTaskFlow element to reference a list of bounded task flows. This list can be modified at runtime by adding or removing elements of type TaskFlowBindingAttributes.

Before you begin:

It may be helpful to have an understanding of the configuration options available to you when configuring a page to render an unknown number of ADF regions. For more information, see Section 23.11, "Configuring a Page To Render an Unknown Number of 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 23.1.3, "Task Flows and ADF Region Use Cases and Examples."

You will need to complete this task:

Create a managed bean with a pageFlow scope that returns a list of type TaskFlowBindingAttributes. Example 23-15 shows the code for the class of a managed bean that returns such a list. For more information about how to create a managed bean, see Section 26.4.1, "How to Use a Managed Bean to Store Information."

To configure a page to render an unknown number of regions:

  1. In the Applications window, right-click the JSF page where you want to add or remove ADF regions at runtime and choose Go to Page Definition.

  2. If a confirmation dialog appears, click Yes.

  3. In the overview editor, click the Binding and Executables tab, and then click the Add icon in the Executables section.

  4. In the Insert Item dialog, select ADF Task Flow Bindings from the dropdown menu, then select multiTaskFlow as the item to create and click OK.

  5. In the Insert multiTaskFlow dialog, enter the following values:

    • id*: Enter a unique ID for the multi task flow binding.

    • taskFlowList *: Enter an EL expression that returns the list of TaskFlowBindingAttributes to return at runtime. For example, to return the list in Example 23-15, enter the following EL expression:

      #{pageFlowScope.multiBean.taskFlowList}

  6. In the Applications window, double-click the JSF page where you want end users to add or remove ADF regions at runtime.

  7. In the ADF Faces page of the Components window, from the Operations panel, drag and drop a For Each onto the component in the Structure window that you want to enclose the For Each component.

  8. In the Properties window for the For Each component, enter values in the following fields:

    • Items: Enter an EL expression that references the method that return the list of task flow bindings from the multi task flow binding runtime object.

      For example, enter an EL expression similar to the following:

      #{bindings.multiRegion1.taskFlowBindingList}

    • Var: Enter a value to identify the list of task flow bindings.

  9. In the JSF page that contains the For Each component, insert a Region component inside the For Each component that references the Region component's region model using an EL expression, as shown in Example 23-16.

    Example 23-16 ADF Region Referencing a Region Model

    <af:forEach var="tf" items="#{bindings.multiRegion1.taskFlowBindingList}">
  <af:panelBox text="#{tf.name}" id="pb1">
    <f:facet name="toolbar"/>
    <af:region value="#{tf.regionModel}" id="r1"/>
  </af:panelBox>
</af:forEach>

23.11.2 What Happens When You Configure a Page to Render an Unknown Number of Regions

Metadata similar to that shown in Example 23-17 appears in the JSF page definition file for the multi task flow binding.

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

<multiTaskFlow id="multiRegion1"              
    taskFlowList="${pageFlowScope.multiBean.taskFlowList}" activation="deferred"
    xmlns="http://xmlns.oracle.com/adf/controller/binding"/>

The taskFlowList attribute in the multi task flow binding metadata specifies the managed bean. The managed bean stores the list of objects describing the task flows that can be added to the page at runtime.

23.11.3 What You May Need to Know About Configuring a Page to Render an Unknown Number of Regions

  • Attempt to limit the number of ADF regions that you create in a page to 10.

  • Each task flow binding inherits attributes defined for the multi task flow binding unless you override this behavior using the methods exposed by TaskFlowBindingAttributes.

  • Each task flow binding inherits parameters defined in the multi task flow binding in addition to those defined using the parametersMap property, as described in Section 23.4, "Specifying Parameters for ADF Regions Using Parameter Maps."

23.12 Handling Access to Secured Task Flows by Unauthorized Users

A bounded task flow does not render in an ADF region if it is invoked by a user who does not have the security permissions to access it. The region renders a blank area in place of the requested task flow when this occurs. This may confuse your users as it does not provide feedback as to why the task flow that they attempted to invoke does not appear. To improve the user experience, you can specify an alternative bounded task flow to render when a user attempts to access a bounded task for which they do not have the required security permissions. You can, for example, configure the alternative bounded task flow to display a page to inform users that they do not have the necessary security permissions. A more complex approach may be to render a bounded task flow that takes the users step-by-step through the process to request the necessary permissions from their system administrator.

Configure the level of security for the alternative bounded task flow to make sure that users can view it should they fail to access a bounded task flow for which they do not have security permissions. This may involve making the alternative bounded task flow public, as described in Section 41.5.1, "How to Make an ADF Resource Public." For more information about securing your Fusion web application, including bounded task flows, see Section 41, "Enabling ADF Security in a Fusion Web Application."

23.12.1 How to Handle Access to Secured Task Flows by Unauthorized Users

You configure an alternative bounded task flow with the content that you want to display to users when they cannot access a bounded task flow because of a lack of security permissions. You specify the alternative bounded task flow as the value for the Unauthorized Region Taskflow property in your Fusion web application's adf-config.xml file.

Before you begin:

It may be helpful to have an understanding of why you may need to display a message to users without security permissions for a task flow. For more information, see Section 23.12, "Handling Access to Secured Task Flows by Unauthorized Users."

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

You will need to complete these tasks:

  1. Create an alternative bounded task flow to display to users when they cannot access a bounded task flow for which they do not have security permissions.

    For more information about creating a bounded task flow, see Section 20.2, "Creating a Task Flow."

  2. Configure this task flow so that users can access it.

    For more information, see Section 41.5.1, "How to Make an ADF Resource Public."

To display messages to users without security permissions for task flows:

  1. In the Application Resources panel, expand the Descriptors and ADF META-INF nodes, and then double-click the adf-config.xml file.

  2. In the overview editor, click the Controller navigation tab.

  3. In the Controller page, in the Unauthorized Region Taskflow field, enter the name of the bounded task flow to invoke or click Browse to select it.

23.12.2 What Happens When You Handle Access to Secured Task Flows by Unauthorized Users

JDeveloper writes the name of the bounded task flow that you selected as a value for the <unauthorized-region-taskflow> element in the adf-config.xml file, as illustrated in Example 23-18.

Example 23-18 Metadata Entry to Specify Task Flow Accessible Without Authentication

<?xml version="1.0" encoding="windows-1252" ?>
<adf-config xmlns="http://xmlns.oracle.com/adf/config"
    xmlns:config="http://xmlns.oracle.com/bc4j/configuration"
     xmlns:adf="http://xmlns.oracle.com/adf/config/properties">
...
<adf-controller-config xmlns="http://xmlns.oracle.com/adf/controller/config">
    <unauthorized-region-taskflow>/WEB-INF/task-flow-definition.xml
       </unauthorized-region-taskflow>
  </adf-controller-config>
...
</adf-config>

At runtime, the Fusion web application renders this alternative bounded task flow when users attempt to invoke a bounded task flow for which they do not have security permissions.