17 Using Task Flows as Regions

This chapter describes how to use ADF regions in pages.

This chapter includes the following sections:

Section 17.1, "Introduction to Using Task Flows in ADF Regions"
Section 17.2, "Creating ADF Dynamic Regions"
Section 17.3, "Creating Dynamic Region Links"

17.1 Introduction to Using Task Flows in ADF Regions

You can add a bounded task flow to a page as an ADF region. An ADF region (region) is a UI component whose content is based on a bounded task flow. When first rendered, the region's content is that of a first view activity in a task flow.

Any view activity used in the region must be created using page fragments, not pages. A page fragment is a JSF JSP document (.jsff) that can be rendered as content of another JSF page and cannot render independently. It is similar to a page, except that it cannot contain elements such as <f:view>. For more information, see Section 17.1.10.1, "Page Fragments and ADF Regions".

An ADF region appears as a sub-area on a page. The shopping cart summary shown in Figure 17-1 is a bounded task flow exposed as an ADF region on the Fusion Order Demo application home page. The task flow contains a single view activity summarizing the contents of the cart. The region drives the presentation of the shopping cart bounded task flow as it executes on the page.

Figure 17-1 Shopping Cart Summary in Fusion Order Demo Home Page

In a more complicated region, the bounded task flow can be comprised of a series of separate activities. The user might view each page fragment contained in the bounded task flow one after another. To navigate between page fragments, the user clicks UI controls located on each page fragment. As shown in Figure 17-2, the Checkout bounded task flow contains method call and view activities. The order view activity is a page fragment that displays an order before the end user clicks a button to transition to a page fragment that displays a summary.

Figure 17-2 Checkout Bounded Task Flow

A primary reason for executing a task flow as an ADF region is reuse. You can isolate a specific piece of application functionality as a region and reuse it throughout the application. ADF regions enable you to extract, parameterize, and package this reusable content within a bounded task flow so that it can be added to other pages. 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 are applied to any ADF region that uses the task flow.

The Fusion Order Demo application contains several functional areas that are candidates for reuse. The Shopping Cart Summary region, shown in Figure 17-1, might be on the home page so that an end user can view items in the cart saved from a previous session or on a Browse Results page in order to add the currently displayed item to the cart. You could pass different parameters to each bounded task flow instance to determine the list of products shown in each ADF region.

When you create the bounded task flow you plan to use as a region on one or more pages or page fragments, determine the pieces of information required by the task flow. You can define these declaratively as input parameter definitions on the bounded task flow and pass their values into the region. When you finish, you can drop the bounded task flow as a region on one or more pages.

All task flow activities that appear in the Component Palette can be added to a bounded task flow that you use as a region. 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 in a region's bounded task flow appropriately. Figure 17-3 shows an example where control flow returns to the beginning of the task flow.

Figure 17-3 Checkout Bounded Task Flow Recycling to Beginning

Checkout task flow recycling to beginning

17.1.1 How to Create an ADF Region

To create an ADF region, you must create a bounded task flow that contains at least one view activity or one task flow call activity. Otherwise, the ADF region may not have anything to display. View activities within the region must be associated with page fragments, not pages.

Before you begin the steps described below, create the following:

Bounded task flow containing page fragments.

For more information, see Section 14.2, "Creating a Task Flow".
Input parameter definition for the bounded task flow.

For more information, see Section 16.3, "How to Pass Parameters to an ADF Bounded Task Flow".
JSF page onto which you drop the bounded task flow as a region.

To add a bounded task flow as a region to a JSF page:

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

By default, task flows appear under the Application Navigator's Page Flows and WEB-INF nodes, as shown in Figure 17-4.

Figure 17-4 Bounded Task Flows in Application Navigator

A context menu with choices for adding the task flow as a region or dynamic region displays. In a dynamic region, the bounded task flow that executes within the region is determined at runtime. For more information, see Section 17.2, "Creating ADF Dynamic Regions".

Tip:
Bounded task flows can be packaged as ADF components and exposed in the Resource Palette. This is useful if you want to use a bounded task flow from a different application than the one in which you are currently working. You can search for the bounded task flow you want in the Resource Palette.
For more information about packaging bounded task flows as ADF components, see Section 33.2, "Packaging a Reusable ADF Component into an ADF Library".
From the context menu, choose Create > Region.

Tip:
The bounded task flow that you drop must contain only page fragments and no pages. If it contains pages, you will not see the Create > Region menu choice when you drop the task flow on the page.
For more information about adding a bounded task flow that contains pages to another JSF page, see Section 18.5, "Executing a Bounded Task Flow Directly From a JSF Page".

You can convert a bounded task flow that contains pages to one that contains page fragments. See Section 14.5.3, "How to Convert ADF Bounded Task Flows" for more information.
In the editor, select the region you just added to the JSF page.

The region displays inside a dotted boundary, as shown in Figure 17-5.

Figure 17-5 ADF Region in JSF Page
JDeveloper automatically populates with default values the following fields in the Property Inspector for the region:
- Id: An ID that the JSF page uses to reference the ADF region, for example, r1. By default, the ID includes the name of the bounded task flow for the region.
- Value: An EL reference to the region model, for example, #{bindings.region1.regionModel}. This is the region model that describes the behavior of the region.
- Rendered: If true, the region is rendered when the page is rendered.
To map parameters between the view activity associated with the JSF page and the ADF region, see Section 17.1.3, "How to Specify Parameters for an ADF Region".

17.1.2 How to Add a Task Flow Binding Declaratively

A task flow binding contains input parameter definitions for a bounded task flow that is running inside a region. If you drop a bounded task flow onto a JSF page as a region, JSF automatically creates a task flow binding for the region. You can also add the binding directly to the page definition, as described in the following procedure.

To create a new task flow binding in the page definition:

Right-click anywhere on the JSF page and choose Go to Page Definition.
Expand the Executables section.
Click the Add icon next to Executables.

The Insert Item dialog displays, as shown in Figure 17-6.

Figure 17-6 Insert Item Dialog
In the Insert Item dialog, select ADF Task Flow Bindings from the dropdown list at the top of the dialog.
Click OK.
Enter the value of the bounded task flow file's ID attribute in the id* field and the task flow ID in the dialog that appears.
Click OK.

17.1.3 How to Specify Parameters for an ADF Region

If a bounded task flow has input parameters defined, they can be exposed on a task flow binding associated with the ADF region. You can then use EL expressions to reference input values available in memory scopes, managed beans, or the ADF binding layer.

Before you begin:

Specify an input parameter definition for the bounded task flow you are adding as an ADF region following the steps in Section 16.3, "How to Pass Parameters to an ADF Bounded Task Flow"

Best practice:

A page or an ADF region within a page may require information from somewhere else on the page. There are two options for exchanging this information:

Use input parameters in the task flow.
Use contextual events (see Section 28.7, "Creating Contextual Events" for more information).

One of the main factors in choosing an option is the nature of the information being shared:

Use input parameters if the required information is at the very beginning of the task flow and a change of this information would require a restart of the task flow.

For example, you may have a page that contains a table of employees, and an ADF region on that page that contains a task flow for enrolling a selected employee in benefits. A change in the selected employee would require that you restart the benefits enrollment from the beginning for the newly selected employee. Using input parameters to the task flow is the right decision for this 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.
Use contextual events if the information being exchanged occurs after the start of a task flow or flows, and the change in the information shouldn't restart the task flow.

For example, you may have a page that contains an ADF region showing 360 degrees of a project. The page contains a tab for project setup, a tab for project customers, and a tab displaying team members. The page contains another ADF region on the page that provides a tree for the user to navigate to the various degrees of the project. If the user selects a node in the tree for team members, the region showing the 360 degrees of a project should display the Team Members tab. The distinction is that the 360 degree task flow wasn't restarted with a new project. It simply responded to the event by displaying a different view in the task flow. Using contextual events is the right decision for this case.

To map region input parameters to the page:

Add the ADF region to the page following the steps in Section 17.1.1, "How to Create an ADF Region".

If input parameter definitions have been specified on the bounded task flow added as a region, the Edit Task Flow Binding dialog displays, as shown in Figure 17-7.

Figure 17-7 Edit Task Flow Binding Dialog
Expand the Input Parameters section.

The Name list displays all input parameter definitions that have been specified for the ADF bounded task flow. An asterisk (*) indicates that the parameter is required.
For each required parameter, specify a value, for example, #{pageFlowScope.inputParameter1}.
If the parameter is not required, you can choose to map it to the page or ignore it. If you map it, the parameter is used. To map the parameter definition to the page, specify a value.
Click OK.

17.1.4 What Happens When You Create an ADF Region

When you drop a bounded task flow onto a page to create an ADF region, a task flow binding is automatically added to the page definition file. As shown in Example 17-1, the task flow binding contains a task flow ID that consists of a unique task flow identifier (for example, region-task-flow-definition) and the name and path to the XML source file containing the ID (for example, /WEB-INF/region-task-flow-definition.xml). If you drop the task flow onto the page as an ADF region, the task flow reference contains a static literal value for the task flow ID.

Example 17-1 Task Flow Binding for ADF Region

<taskFlow id="regiontaskflowdefinition1"
   taskFlowId="/WEB-INF/region-task-flow-definition.xml#region-task-flow- definition"
     xmlns="http://xmlns.oracle.com/adf/controller/binding"/>

taskFlowId can also contain an EL expression that evaluates to a String or to the public class TaskFlowId (oracle.adf.Controller.TaskFlowId). See Section 17.2, "Creating ADF Dynamic Regions" for more information.

An ADF region is comprised of the following:

A task flow binding
An ADF region tag (af:region)

A task flow binding is added to the page definition each time you add a region to the JSF page. The task flow binding is the bridge between the region UI component and the bounded task flow. It binds a specific region instance to its associated task flow, and maintains all the information specific to the bounded task flow.

When you drop a bounded task flow onto a JSF page, all of the data bindings in the task flow are preserved. A request made for a JSF page containing an ADF region is initially handled like any other JSF page. As the JSF page definition executes, data is loaded to the JSF page. The page contains a <region> tag. The page definition contains a task flow binding within the <executables> section.

The task flow binding creates an ADF Controller ViewPortContext for its task flow and then asks the ViewPortContext for its current view activity. A viewPort is a display area that has its own viewId and is capable of navigating independently of other viewPorts. A browser window and a region are examples of viewPorts. The ViewPortContext determines the initial view activity by executing its task flow until a view activity is reached. The binding container for the current view activity's page and any nested binding containers in this page are then executed.

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

A bo unded 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.

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

In the Application Navigator, double-click the XML file for the bounded task flow that runs in the ADF region.
In the ADF Task Flow page of the Component Palette, select Parent Action and drag it to the bounded task flow.
Select the parent action activity in the diagram for the bounded task flow.
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 must 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.
(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.1.6 How to Configure Refreshing of 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.

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.

To configure the refreshing of an ADF Region:

In the Application Navigator, select the page that contains the ADF Region, right-click and choose Go to Page Definition.
In the page definition file, expand the Model view and select the task flow binding in the Executables section, as illustrated in Figure 17-8.

Figure 17-8 Task Flow Binding
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.
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.
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.
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.1.7 What You May Need to Know About Refreshing an ADF Region

A n ADF region initially refreshes when the parent JSF page on which the region is located first displays. To execute the task flow at the same time that the region renders, you must trigger a task flow binding refresh at the same time that the region renders.

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.

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

There are no values other than ifNeeded for the Refresh attribute.

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 are passing parameters to the task flow binding using a dynamic parameter map. You must instead use the RefreshCondition="#{EL.Expression}".

RefreshCondition and Refresh are mutually exclusive. Refresh="ifNeeded" 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-2 contains a sample task flow binding located within the page definition of a page on which an ADF region has been added.

Example 17-2 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.1.8 How to Configure 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.

To configure the activation of an ADF Region:

In the Application Navigator, select the page that contains the ADF region(s), right-click and choose Go to Page Definition.
In the page definition file, expand the Model view and select the task flow binding in the Executables section, as illustrated in Figure 17-9.

Figure 17-9 Task Flow Bindings for ADF Region Configured for Activation
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.
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.1.9 What Happens at Runtime When ADF Regions Render

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

Figure 17-10 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-10 Default Activation of ADF Regions

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

Figure 17-11 Conditional Activation of ADF Regions

Figure 17-12 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-12 Deferred Activation of ADF Regions

17.1.10 What You May Need to Know About ADF Regions

Note that you cannot use certain tags within the source file for an ADF Region. You can configure security for an ADF Region and use EL expressions to determine an ADF Region's capabilities.

17.1.10.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 or 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-3 contains an example of a simple page fragment. Unlike a JSF JSP page, it contains no <f:view> or <f:form> tags.

Example 17-3 Page Fragment Source Code

<?xml version='1.0' encoding='windows-1252'?>
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.0"
          xmlns:af="http://xmlns.oracle.com/adf/faces/rich">
  <af:commandButton text="Go"/>
  <af:inputText/>
</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.10.2 View Port

A view port is a display area that is capable of navigating independently of other view ports. A browser window and a 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.

17.1.10.3 ADF Regions and Security

Y ou 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.10.4 Determining the Capabilities of an ADF Region

In some cases, an application page may need to determine the capabilities currently available within one of its contained regions. For example, the application page may need to initiate control flow within the 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:

A region within the page displays its associated page fragment.
A user selects a button or performs some other action in the region.
The parent page identifies the outcomes (region capabilities) for the region.
The parent page updates its buttons based on the region capabilities.

The syntax of the EL expression for region capabilities is:

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

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

Region capabilities require the availability of a specified 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. One case is a nested 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 ADF Dynamic Regions

An ADF dynamic region is similar to an ADF region, except that its task flow ID in the task flow binding is determined dynamically at runtime. This enables the application to determine, at runtime, which bounded task flow to execute within the dynamic region. For example, a page displays employee information. A dynamic region added to the page displays a form for updating employee address information when the user clicks a button. Then the same region switches to a different form for updating the social security number when the employee clicks another button on the page.

Or, you could create a dynamic region that first displays a customer's street address. The end user might click a link or button to display forms for changing the billing address or the shipping address. The page fragment that displays the customer address and the two forms are all within the same ADF dynamic region, which saves space on the main page where the region is located.

As shown in Example 17-4, the task flow binding for the ADF dynamic region contains an EL expression that returns the current taskFlowId. When the task flow ID value changes, the dynamic region refreshes automatically. New input parameter values are automatically passed to it.

Example 17-4 Dynamic Task Flow Binding for ADF Dynamic Region

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

When an ADF dynamic region is reinitialized, the application must reinitialize the task flow binding associated with the region. This includes evaluating whether there are new input parameters and input parameter values to be passed to the ADF dynamic region.

When you drop a bounded task flow onto a page to create an ADF dynamic region, you also specify any input parameters defined for the region in the task flow binding in the page definition file. For more information, see Section 17.1.3, "How to Specify Parameters for an ADF Region".

17.2.1 How to Create an ADF Dynamic Region

The steps for adding a bounded task flow to a page as an ADF dynamic region are similar to those for adding it as an ADF region.

For example, you might have an order page that displays products and services. If the user selects a product on a page, a details ADF dynamic region might show product details. If a service is selected, the same details region should show service details.

Before you begin:

Create two page fragments that display product details and service details.
Create two bounded task flows that use page fragments, each containing one of the page fragments. See Section 17.1.1, "How to Create an ADF Region" for more information
Specify parameters for both bounded task flows. See Section 17.1.3, "How to Specify Parameters for an ADF Region".

To create a dynamic region:

Open a JSF page in the editor.
Drop the first bounded task flow onto the JSF page as an ADF dynamic region.

Make sure that you click outside of the form on the JSF page to add the region.
From the context menu, choose Create > Dynamic Region.

A dialog displays asking you to specify a managed bean. The managed bean will be used to store the value of the ID for the bounded task flow that is displayed within the dynamic region.
In the Managed Bean dropdown list, select a managed bean.

The managed bean is used to swap the different bounded task flows 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.
1. In the Bean Name field, enter a name for the managed bean, for example, dynamicRegionBean.
2. In the Class field, enter or browse for the managed bean class.
  
  For example, you could name the bean DynamicRegionBean and specify DynamicTF as the class. This will generate DynamicTF.java with a property named taskFlowId that contains the ID of the task flow that will be rendered in the ADF dynamic region. Manipulating the value of this property (taskFlowId) at runtime enables you to switch between the task flows in the dynamic region.
  
  The managed bean is used to swap the different bounded task flows into the task flow binding of the ADF dynamic region.
3. In the Extends field, enter or browse for a package. The default is java.lang.object.
4. In the Package field enter or browse for a package containing the managed bean.
5. In the Extends field, enter or browse for a package. The default is java.lang.object.
6. Click OK.
In the Application Navigator, drag the second bounded task flow onto the page and drop it on the JSF page.

A menu with choices for adding the bounded task flow as a region or dynamic region displays. If your bounded task flow is not eligible to be dropped as an ADF region (for example, it contains pages, not page fragments), you will not see this menu.
From the context menu, choose Create > Dynamic Region.

A dialog displays asking you to specify a managed bean. The managed bean will be used to store the value of the ID for the bounded task flow that is displayed within the dynamic region.
In the Managed Bean dropdown list, select a a managed bean.

The managed bean is used to swap the different bounded task flows 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.
1. In the Name field, enter a name for the managed bean, for example, dynamicRegionBean.
2. In the Package field, enter or browse for a package containing the managed bean.
  
  The managed bean is used to swap the different bounded task flows into the task flow binding of the ADF dynamic region.
3. In the Class field, enter the class for the managed bean.
4. In the Extends field, enter or browse for a package. The default is java.lang.object.
  
  For example, you could name the bean DynamicRegionBean and specify DynamicTF as the class. This will generate DynamicTF.java with a property named taskFlowId that contains the id of the task flow that will be rendered in the ADF dynamic region. Manipulating the value of this property (taskFlowId) at runtime enables you to switch between the task flows in the dynamic region.
Click OK.
The Task Flow Binding field displays the task flow binding for the dynamic region. You can edit the binding by entering a new one in the field.
The Edit Task Flow Binding dialog also displays any input parameter definitions for the bounded task flows you dropped on the page. See Section 17.1.3, "How to Specify Parameters for an ADF Region" for more information.
Enter a method that sets the value of the taskFlowId property to a task flow parameter, for example parm.
Select an input parameter definition, for example, parm, and click OK.

When you are finished, a user should be able to click an order line in the page to invoke the method setTaskFlowId. This passes the corresponding taskFlowId as an input parameter value, which is used to specify the ID of the bounded task flow that should display.

17.2.2 How to Override Parameter Values

The various bounded task flows that display within the ADF dynamic region can each specify different input parameter definitions. You can choose to list all of the input parameters defined for the bounded task flows within the <parameters> element in the task flow binding, as described in Section 17.1.3, "How to Specify Parameters for an ADF Region". In addition, you can optionally use the <parameterMap> element to identify which input parameters are used and which are overridden.

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 a java.Util.map object. The object contains task flow input parameter name/value pairs. The parameter set for the task flow is built from the order that is specified in the task flow binding.

The <parameterMap> element specifies an EL expression that returns a java.Util.map object. The object contains task flow input parameter name/value pairs. The parameter set for the task flow is built from the order of values that are 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.1.7, "What You May Need to Know About Refreshing an ADF Region".

In Example 17-5, a parameter named regionParm1 in the parameter map overrides the first parameter value specified. The parameters named regionParm2 and regionParm3 in the parameter map are overridden by the last two parameter values specified in the example.

Example 17-5 Task Flow Binding for ADF Dynamic Region

<taskFlow id="Region1"
              taskFlowId="${RegionBean.TaskFlowId}"
              xmlns="http:xmlns.oracle.com/adf/controller/binding"/> 
    <parameters> 
                <parameter id="regionParm1" value="#{pageFlowScope.data.x}">                
                <parameterMap="#{pageFlowScope.data.taskFlowParams}">
                <parameter id="regionParm2" value="#{pageFlowScope.data.y}">
                <parameter id="regionParm3" value="#{pageFlowScope.data.z}">
        </parameters>
   </taskflow>

17.2.3 What You Should Know about JSF Life Cycle Phases

Swapping between dynamic regions occurs only in the prepare render phase.

When using dynamic regions in task flows, do not navigate off the RegionModel until the invoke application phase of the JSF life cycle. This gives the components from a previous .jsff fragment a chance to participate smoothly in the life cycle phases, before the navigation happens. A good practice therefore is not to navigate a task flow in response to a ValueChangeEvent.

17.3 Creating Dynamic Region Links

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 UI component such as a button or link to update the dynamic region with the new bounded task flow. For example, the original bounded task flow in the ADF dynamic region might display general information about an employee, for example an ID and photo. Clicking an ADF dynamic region link labeled Details updates the ADF dynamic region with a table containing more information about the employee.

When an end user clicks the UI component, a method is invoked on the dynamic region's managed bean. The value of the new bounded task flow is passed to the method, and the dynamic region is refreshed with the new task flow. The referenced bounded task flow then displays within the dynamic region.

By default, a dynamic region links 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 a 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 a dynamic region to the same page. After you drop the bounded task flow on the page and choose to create a dynamic region link, a menu displays all of the dynamic regions currently on the page, as shown in Figure 17-13.

Figure 17-13 Dynamic Region Link Menu

You select the dynamic region within which you want to display the contents of the bounded task flow. JDeveloper then adds a command link to the page, as shown in Example 17-6. JDeveloper also updates the Java class for the dynamic region managed bean and updates the corresponding task flow binding with any new parameters.

Example 17-6 Dynamic Region Link

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

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.

Before you begin:

Complete the steps for creating an ADF dynamic region and adding it to a page, described in Section 17.2.1.

To create a dynamic region link:

In the editor, open the JSF page you created in Section 17.2.1.
In the Application Navigator, drag a bounded task flow and drop it anywhere on the page.

The bounded task flow must contain page fragments, not pages.
From the context menu, choose Dynamic Region Link.

A menu displays a list of all ADF dynamic regions that have already been added to the page.
Select the name of the dynamic region in which you want to display the contents of the bounded task flow.
Click OK.