Oracle® Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework 11g Release 2 (11.1.2.1.0) Part Number E16182-02 |
|
|
PDF · Mobi · ePub |
This chapter describes how to render task flows in pages or page fragments using ADF regions.
This chapter includes the following sections:
Section 21.4, "Specifying Parameters for ADF Regions Using Parameter Maps"
Section 21.7, "Navigating Outside an ADF Region's Task Flow"
Section 21.9, "Adding Additional Task Flows to an ADF Dynamic Region"
Section 21.10, "Configuring a Page To Render an Unknown Number of 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 Oracle Fusion Middleware 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 21-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.
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 is recommended so that you 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), it is also recommended to wrap 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 21-1, where r1
identifies the ADF region that renders the page fragment.
Example 21-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 21-2 contains an example of a simple page fragment. Unlike a JSF page, it contains no <f:view>
or <f:form>
tags.
Example 21-2 Page Fragment Source Code
<?xml version='1.0' encoding='UTF-8'?> <jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.1" xmlns:af="http://xmlns.oracle.com/adf/faces/rich"> <af:commandButton text="commandButton 1" id="cb1"/> </jsp:root>
You must nest a page fragment that you include in another JSF page within a region (af:region
tag). A bounded task flow that you add to a JSF page as a region cannot call pages; it must call page fragments.
A view port is a display area capable of navigating independently of other view ports. A browser window and an ADF region are both examples of view ports. The root view port displays the main page in a browser window. The root view port may have child view ports, for example, regions on the page, but does not have a parent view port.
Java classes that implement the ViewPortContext
interface in the oracle.adf.controller
package get you more information about view ports. For more information, see the Oracle Fusion Middleware Java API Reference for Oracle ADF Controller.
Figure 21-2 shows the Registration page (register.jspx
) in the Fusion Order Demo application which renders two ADF regions. One of these regions (Registration Help) is static; it appears regardless of actions that an end user invokes elsewhere on the Registration page. It displays help information for the end user by rendering the view activities defined in the Fusion Order Demo application's help-task-flow.xml
task flow. For more information about creating this type of region, see Section 21.2, "Creating an ADF Region."
The second region that register.jspx
renders is a dynamic region (ADF dynamic region). The task flow that it renders depends on the end user's action. If the end user clicks Register as a customer on the registration page, the ADF dynamic region renders the customer registration task flow (customer-registration-task-flow.xml
). Alternatively, if the end user clicks Register as an employee, the ADF dynamic region renders the employee registration task flow (employee-registration-task-flow.xml
). For more information about creating this type of region, see Section 21.8, "Creating ADF Dynamic Regions."
The task flows that you render in an ADF region can be simple (for example, the help task flow has one view activity that renders help information) or can involve a number of steps where you guide end users through a process to complete a task, as in the case of the customer registration task flow.
Figure 21-3 shows parts of the customer registration task flow. It contains view activities that allow end users to review information they enter (for example, reviewCustomerInfo
), an exception handler activity to display a message when an error occurs (errorPage
), and task flow return activities to cancel or commit the changes that end users make. All these task flow activities can be rendered within an ADF region.
One special case is the task flow return activity. In many cases, you cannot return control when the bounded task flow finishes execution because there is no caller (except the page or page fragment that hosts the bounded task flow) to which you can return control. For this reason, design control flow appropriately in a bounded task flow that you intend to render in an ADF region.
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.
You can set security on a bounded task flow that displays in an ADF region and associated page definitions. If an end user displays a page that contains an ADF region he or she is not authorized to view, the contents of the ADF region do not display. No authentication mechanism is triggered. For more information, see Chapter 35, "Enabling ADF Security in a Fusion Web Application".
Task flows can invoke managed beans. For more information about managed beans, see Section 24.4, "Using a Managed Bean in a Fusion Web Application."
You can use contextual events to exchange information with a bounded task flow. For more information, see Section 34, "Using Contextual Events."
You create an ADF region by dragging and dropping a bounded task flow that contains at least one view activity or one task flow call activity to the page where you want to render the ADF region. This makes sure that the ADF region you create has content to display at runtime.
The bound task flow's view activities must be associated with page fragments (.jsff
). If you attempt to drag and drop a bounded task flow that is associated with pages rather than page fragments, JDeveloper does not display the context menu that allows you to create an ADF region. You can convert a bound task flow that uses pages to use page fragments. For more information, see Section 18.6.3, "How to Convert Bounded Task Flows."
The context menu that JDeveloper displays to create an ADF region presents options to create a non-dynamic and a dynamic region. A dynamic region (ADF dynamic region) determines the bounded task flow that it renders at runtime. For more information about creating an ADF dynamic region, see Section 21.8, "Creating ADF Dynamic Regions." You determine, at design time, the bounded task flow that a non-dynamic region (ADF region) displays.
Before you create an ADF region, you need to do the following:
Create a bounded task flow with one or more view activities associated with page fragments or one task flow call activity to a task flow with view activities
For more information, see Section 18.2, "Creating a Task Flow.".
Create a page to host the ADF region
Drag a bounded task flow from the Application Navigator to the page where you want to render an ADF region.
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 21.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 21.1.4, "Additional Functionality for Task Flows that Render in ADF Regions."
In the Application Navigator, drag the bounded task flow onto the JSF page and drop it where you want to locate the ADF region.
From the context menu that appears, choose Create > Region.
The Edit Task Flow Binding dialog appears if the bounded task flow that you drop on the JSF page has an input parameter defined, as described in Section 20.3, "Passing Parameters to a Bounded Task Flow." For more information about specifying parameters for an ADF region, see Section 21.3, "Specifying Parameters for an ADF Region."
In the Structure window, right-click the node for the ADF region that you added (af:region) and choose Go to Properties.
Review or modify (as appropriate) the following properties which JDeveloper automatically populates with default values in the Property Inspector for the ADF region:
Id: An ID that the JSF page uses to reference the ADF region, for example, r1
.
Value: An EL reference to the ADF region model, for example, #{bindings.region1.regionModel}
. This is the region model that describes the behavior of the region.
Rendered: If true
(the default value), the ADF region renders when the JSF page renders.
For information about how to map parameters between the view activity associated with the JSF page and the ADF region, see Section 21.3, "Specifying Parameters for 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 21-3 shows a sample of the metadata that JDeveloper adds to the JSF page.
Example 21-3 Metadata Added to a JSF Page to Create an ADF Region
<af:region value="#{bindings.tf_register_employee1.regionModel}" id="r1"/>
JDeveloper also adds a task flow binding to the page definition file of the page that hosts the ADF region. Example 21-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 21-4 Metadata Added to Page Definition to Create a Task Flow Binding
<taskFlow id="tf_register_employee1" taskFlowId="/WEB-INF/tf_register_employee.xml#tf_register_employee" activation="deferred" xmlns="http://xmlns.oracle.com/adf/controller/binding"/>
The bounded task flow preserves all of the data bindings when you drop it on the JSF page. At runtime, a request for a JSF page containing an ADF region initially handles like any other request for a JSF page. As the JSF page definition executes, data loads in to the JSF page. When the component tree for the parent JSF page encounters the <af:region>
tag, it executes it in order to determine the first page fragment of content to display. Once it determine the first page fragment of content, it adds the appropriate UI components from the page fragment to the component tree for the parent JSF page.
The task flow binding creates an object for its task flow that implements the following interface in order to get the current view activity:
oracle.adf.controller.ViewPortContext
The task flow binding's taskFlowId
attribute can also reference an EL expression that evaluates to one of the following:
java.lang.String
oracle.adf.controller.TaskFlowId
You use this capability if you create an ADF dynamic region. For more information, see Section 21.8, "Creating ADF Dynamic Regions."
You can make input parameters that you defined for a bounded task flow available to an ADF region by adding them to the task flow binding that the ADF region references. Use EL expressions to reference input parameters available in memory scopes, managed beans, or the ADF binding layer.
Specifying input parameters is one method of providing information to an ADF region. An alternative method is to use contextual events. The nature of the information that you want to provide to the ADF region determines the method you choose to provide the information. For example, choose:
Input parameters if the required information is at the beginning of the task flow and a change in the value of this information requires a restart of the task flow.
For example, you have a page that contains a table of employees. An ADF region on that page contains a task flow to enroll a selected employee in a benefits program. A change in the selected employee requires that you restart the benefits enrollment task flow from the beginning for the newly selected employee. Using input parameters to the task flow is the right decision for this use case.
You can pass input parameters by reference or by value. If you pass by reference, an update on the main page for the selected employee's information, such as last name, is automatically reflected in the task flow running in the ADF region without restarting the task flow.
Contextual events if you can only determine the information to exchange after the start of a task flow and a change in the information does not require a restart of the task flow. For example, the Fusion Order Demo application uses contextual events to display the appropriate help topic when the customer registration task flow renders in the register.jspx
page. For more information about contextual events, see Chapter 34, "Using Contextual Events."
For information about creating an ADF region and adding task flow bindings, see Section 21.2, "Creating an ADF Region." For information about how to define an input parameter for a bounded task flow, see Section 20.3, "Passing Parameters to a Bounded Task Flow".
Use EL expressions to specify parameters available in memory scopes, managed beans, or the ADF binding layer as input for the ADF region.
It may be helpful to have an understanding of the requirements for specifying parameters for an ADF region. For more information, see Section 21.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 21.1.4, "Additional Functionality for Task Flows that Render in ADF Regions."
To specify input parameters for an ADF region:
In the Application Navigator, right-click the JSF page that holds the ADF region and choose Go to Page Definition.
In the overview editor for the page definition file, select the task flow binding for which you want to specify parameters.
Click the Edit icon to display the Edit Task Flow Binding dialog, as shown in Figure 21-5.
If you defined input parameters for the bounded task flow, as described in Section 20.3, "Passing Parameters to a Bounded Task Flow", the Edit Task Flow Binding dialog lists these parameters in the Input Parameters section.
Note:
You can write an EL expression that references a list of input parameters specified in a managed bean using the Input Parameters Map field of the Edit Task Flow Binding dialog. For more information about implementing this functionality, see Section 21.4, "Specifying Parameters for ADF Regions Using Parameter Maps."Write an EL expression that retrieves the value of each input parameter you want to specify for the ADF region. Note that you must write an EL expression for parameters that you defined as required. For example, write an EL expression similar to the following:
#{pageFlowScope.inputParameter1}
Click OK.
JDeveloper writes entries that are child elements of the taskFlow
element in the page definition of the JSF page, as illustrated in example Example 21-5.
Example 21-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.
In addition (or as an alternative) to listing all the input parameters on the task flow binding, as described in Section 21.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 21.8, "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 21.8, "Creating ADF Dynamic Regions."
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.
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 21.4, "Specifying Parameters for ADF Regions Using Parameter Maps."
You may also find it helpful to understand functionality that can be added using other task flow and ADF region features. For more information, Section 21.1.4, "Additional Functionality for Task Flows that Render in ADF Regions."
To create a parameter map to specify input parameters for an ADF region:
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 24.4, "Using a Managed Bean in a Fusion Web Application."
In the Application Navigator, right-click the JSF page that holds the ADF region and choose Go to Page Definition.
In the overview editor for the page definition file, select the task flow binding or multi task flow binding for which you want to specify a parameter map.
Click the Edit icon to display the appropriate dialog (Edit Task Flow Binding dialog or the Edit Multi Task Flow Binding).
Select Expression Builder from the Input Parameters Map dropdown menu.
Write or build an EL expression that references a parameter map. For example, write an EL expression similar to the following:
#{pageFlowScope.userInfoBean.parameterMap}
Click OK.
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 21-6 shows code snippets from a managed bean that puts two values (isLoggedIn
and principalName
) into a parameter map named parameterMap
.
Example 21-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 21-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 21-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 21-6.
Example 21-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 21-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 specifyRefresh="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 21.5.2, "What You May Need to Know About Refreshing an ADF Region".You can configure when an ADF region refreshes and whether it invokes a task flow. An ADF region can only invoke a task flow when the ADF region is in an active state. An ADF region in an inactive state cannot invoke a task flow and returns a null value for the ID of the referenced task flow to the parent page.
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.
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 21.5, "Refreshing an ADF Region."
You may also find it helpful to understand functionality that can be added using other task flow features and ADF region features. For more information, see Section 21.1.4, "Additional Functionality for Task Flows that Render in ADF Regions."
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, select the task flow binding or multi task flowing binding in the Executables section, as illustrated in Figure 21-7.
In the Property Inspector, select a value from the Refresh dropdown menu, 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 RefreshCondition dropdown menu 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 activation dropdown menu, 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.
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 and JDeveloper" 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 menu 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 active dropdown menu 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.
An ADF region initially refreshes when the parent JSF page on which the region is located first displays. During the initial refresh, any ADF region task flow binding parameter values are passed in from the parent page. The parameter values are used to display the initial page fragment within the ADF region. If the bounded task flow relies on input parameter values that are not available when the page is first created, make sure that your task flow behaves correctly if the input parameter values are null by, for example, using a NullPointerException
object. Alternatively (or additionally), make sure that the task flow does not activate until the input parameters become available by configuring the task flow binding's active
property.
An ADF region task flow binding can be refreshed again based on one of the following task flow binding attributes:
Neither Refresh
or RefreshCondition
attributes are specified (default)
If neither the Refresh
nor RefreshCondition
task flow binding attribute is specified, the ADF region is refreshed only once at the time the parent page is first displayed unless you configure a value for the task flow binding's active
property.
RefreshCondition="#{EL.expression}"
The ADF region is refreshed a single time when its RefreshCondition
evaluates true. The RefreshCondition
must evaluate to a boolean value.
At the time the RefreshCondition
is evaluated, if the variable bindings
is used within the EL Expression, the context refers to the binding container of the parent page, not the page fragment displayed within the ADF region.
RefreshCondition
is independent of the change of value of binding parameters. If the task flow binding parameters do not change, nothing within the ADF region will change.
Refresh="ifNeeded"
Any change to a task flow binding parameter value causes the ADF region to refresh.
If the ADF region task flow binding does not have parameters, Refresh="ifNeeded"
is equivalent to not specifying the Refresh
attribute.
If you set Refresh
to ifNeeded
, the RefreshCondition
attribute should not be specified.
Refresh="ifNeeded"
is not supported if you pass parameters to the task flow binding using a dynamic parameter map. You must instead use the RefreshCondition="#{EL.Expression}"
.
For more information about specifying parameter values using a parameter map, see Section 21.4, "Specifying Parameters for ADF Regions Using Parameter Maps."
The RefreshCondition
and Refresh
properties are mutually exclusive. The Refresh="ifNeeded"
property takes precedence over RefreshCondition
. If the bindings variable is used within the EL expression at the time RefreshCondition
is evaluated, the context refers to the binding container of the parent page, not the page fragment displayed within the ADF region. The expression is evaluated during the PrepareRender
phase of the ADF page lifecycle. For more information, see Chapter 25, "Understanding the Fusion Page Lifecycle".
Example 21-8 contains a sample task flow binding located within the page definition of a page on which an ADF region has been added.
Example 21-8 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.
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.
You configure the activation
property for the task flow binding associated with the ADF region to determine when to activate the ADF region.
It may be helpful to have an understanding of the configuration options for activating an ADF region. For more information, see Section 21.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 21.1.4, "Additional Functionality for Task Flows that Render in ADF Regions."
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, select the task flow binding or multi task flow binding in the Executables section, as illustrated in Figure 21-8.
In the Property Inspector, select a value from the activation dropdown menu, 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 and JDeveloper" 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 menu 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 active dropdown menu to invoke the Expression Builder and write an EL expression that returns a boolean value at runtime. If the EL expression returns true
, the ADF region invokes the task flow. If the EL expression returns false
, the ADF region deactivates a task flow that was active in the ADF region.
The behavior of the ADF region at runtime depends on the options that you set for the activation
property.
Figure 21-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 21-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 21-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
):
A task flow with an active transaction rolls back the transaction.
For more information about transaction options in task flows, see Section 22.2, "Managing Transactions in Task Flows."
If a task flow has a data control frame with a data-control-scope
value of isolated
, the task flow releases the data control frame and any data controls in the data control frame.
For more information about data controls, see Section 20.4, "Sharing Data Controls Between Task Flows" and Section 22.2.3, "What You May Need to Know About Data Control Scoping with Task Flows."
ADF Controller releases the view port data structures for the region (including pageFlow and view scopes).
For more information about view ports, see Section 21.1.2, "About View Ports and ADF Regions." For more information about memory scopes, see Section 18.2.4, "What You May Need to Know About Memory Scope for Task Flows."
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.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.
It may be helpful to have an understanding of the configuration options for activating an ADF region. For more information, see Section 21.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 21.1.4, "Additional Functionality for Task Flows that Render in ADF Regions."
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, from the Component panel, drag and drop a Parent Action onto the diagram.
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 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 the Fusion Order Demo application, you specify globalHome
as the value for Root Outcome, as illustrated in Figure 21-12.
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.
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 21-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 21-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 21-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 21-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.
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:
An ADF region within a page displays its associated page fragment.
A user selects a button or performs some other action in the ADF region.
The parent page identifies the outcomes (region capabilities) for the ADF region.
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.
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 21-13 shows a runtime example from the Fusion Order Demo application where the register.jspx
page renders a different registration task flow in its center facet in response to the command component button that the end user clicks. For example, if the end user clicks Register as an employee, the Fusion Order Demo application renders the employee-registration-task-flow
in the ADF dynamic region.
At runtime, the ADF dynamic region swaps the task flows that it renders during the Prepare Render lifecycle phase. To give components from a previous task flow the opportunity to participate smoothly in the lifecycle phases, do not navigate off the regionModel
until the JSF Invoke Application lifecycle phase. It is good practice, therefore, not to navigate a task flow in a dynamic region in response to contextual events. For more information about lifecycle phases, see Chapter 25, "Understanding the Fusion Page Lifecycle," and for more information about contextual events, see Chapter 34, "Using Contextual Events."
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 18.6.3, "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 21.9, "Adding Additional Task Flows to an ADF Dynamic Region."
Drag and drop bounded task flows to the page where you want to render the ADF dynamic region.
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 21.8, "Creating ADF Dynamic Regions."
You may also find it helpful to understand other functionality that can be added using other task flow and ADF region features. For more information, see Section 21.1.4, "Additional Functionality for Task Flows that Render in ADF Regions."
To create an ADF dynamic region:
In the Application Navigator, select and open the JSF page where you want to create the ADF dynamic region.
Drag and drop the first bounded task flow onto the JSF page.
From the context menu that JDeveloper displays, choose Create > Dynamic Region.
Choose the appropriate option in the Choose Managed Bean for Dynamic Region dialog that JDeveloper displays:
If you want an existing managed bean to store the bounded task flow's ID, select an existing managed bean from the Managed Bean dropdown list.
The managed bean passes the value of the bounded task flow's ID into the task flow binding of the ADF dynamic region. 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:
Bean Name: Enter a name for the new managed bean. For example, enter DynamicRegionBean
.
Class Name: Enter the name of the new managed bean class.
Package: Enter the name of the package that is to contain the managed bean or browse to locate it.
Extends: Enter the name of the Java class that the managed bean extends. The default value is java.lang.Object
.
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 18.2.4, "What You May Need to Know About Memory Scope for Task Flows."
Click OK to close the dialogs where you configure the managed bean.
Choose the appropriate option in the Edit Task Flow Binding dialog that JDeveloper displays:
Click OK if you do not want specify input parameters or an input parameter map for the ADF dynamic region.
Specify input parameters for the ADF dynamic region.
For more information, see Section 21.3, "Specifying Parameters for an ADF Region."
Figure 21-14 shows the Edit Task Flow Binding dialog that JDeveloper displays after you configure a managed bean.
Note:
You can write an EL expression that references a list of input parameters specified in a managed bean using the Input Parameters Map field of the Edit Task Flow Binding dialog. For more information about implementing this functionality, see Section 21.4, "Specifying Parameters for ADF Regions Using Parameter Maps."Click OK.
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 21-11 shows a sample of the metadata that JDeveloper adds to the JSF page.
Example 21-11 Metadata Added to a JSF Page to Create an ADF Dynamic Region
<af:region value="#{bindings.dynamicRegion1.regionModel}" id="r1"/>
JDeveloper also adds a task flow binding to the page definition file of the page that hosts the ADF dynamic region. Example 21-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 21-12 Metadata Added to Page Definition to Create a Task Flow Binding
<taskFlow id="dynamicRegion1" taskFlowId="${backingBeanScope.ManagedBeanName.dynamicTaskFlowId}" activation="deferred" xmlns="http://xmlns.oracle.com/adf/controller/binding"/>
The taskFlowId
attribute in the task flow binding metadata specifies the managed bean that determines at runtime what bounded task flow to associate with the ADF dynamic region. JDeveloper creates this managed bean or modifies an existing managed bean to store this data. Example 21-13 shows extracts of the code that JDeveloper writes to the managed bean.
Example 21-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.
An ADF dynamic region link swaps a bounded task flow for another bounded task flow within an ADF dynamic region. An end user clicks a command component (for example, a button or a link) to update the ADF dynamic region with the new bounded task flow.
For example, a bounded task flow in the ADF dynamic region displays general information about an employee such as an ID and photo. When the end user clicks a link command component labeled Details, the ADF dynamic region updates with a table containing more information about the employee from another bounded task flow. The end user's action (clicking the link) invokes a method on the ADF dynamic region's managed bean. The value of the new bounded task flow is passed to the method, and the ADF dynamic region refreshes with the new bounded task flow. The new bounded task flow now displays within the ADF dynamic region.
By default, a ADF dynamic region link swaps another bounded task flow in for the original, but cannot swap back to the original. To toggle back to the original bounded task flow, you could add a second ADF dynamic region link on the page that, when clicked, swaps the current task flow back to the original one.
You can add an ADF dynamic region link if you already have at least one ADF dynamic region on a page and are adding a new bounded task flow as an ADF dynamic region to the same page. After you drop the bounded task flow on the page and choose to create an ADF dynamic region link, a menu displays all of the dynamic regions currently on the page, as shown in Figure 21-15.
JDeveloper displays a list of the current dynamic regions in a document when you choose Dynamic Region Link from the menu that appears after you drag and drop a bounded task that you want to add as an option to an existing dynamic region in the document, as shown in Figure 21-15.
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.You drag and drop a bounded task flow to a page that already contains an ADF dynamic region and you select Dynamic Region Link on the context menu that JDeveloper displays to view a list of ADF dynamic regions to which you can create a link.
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 21.9, "Adding Additional Task Flows to an ADF Dynamic Region."
You may also find it helpful to understand functionality that can be added using other task flow and ADF region features. For more information, see Section 21.1.4, "Additional Functionality for Task Flows that Render in ADF Regions."
To create an ADF dynamic region link:
In the Application Navigator, select and open the JSF page where you want to create the ADF dynamic region link.
This procedure assumes that you have already added at least one ADF dynamic region to the JSF page that you open. For information about adding an ADF dynamic region to a JSF page, see Section 21.8, "Creating ADF Dynamic Regions."
Drag a bounded task flow and drop it anywhere on the page.
The view activities of the bounded task flow must be associated with page fragments You can convert a bounded task flow that uses pages to use page fragments. For more information, Section 18.6.3, "How to Convert Bounded Task Flows.".
From the context menu that JDeveloper displays, choose Dynamic Region Link.
A menu displays a list of all ADF dynamic regions that have already been added to the page.
Select the name of the ADF dynamic region in which you want to display the contents of the bounded task flow.
Click OK.
JDeveloper adds a command link to the page, as shown in Example 21-14. JDeveloper also updates the managed bean for the ADF dynamic region and updates the corresponding task flow binding with any new parameters.
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 21-15 shows the code for the class of a managed bean named MultiBean
that returns a list containing two task flows.
Example 21-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 Oracle Fusion Middleware 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 21-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.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
.
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 21.10, "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 21.1.3, "Task Flows and ADF Region Use Cases and Examples."
To configure a page to render an unknown number of regions:
Create a managed bean with a pageFlow scope. The managed bean that you create returns a list of type TaskFlowBindingAttributes
. Example 21-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 24.4.1, "How to Use a Managed Bean to Store Information."
In the Application Navigator, right-click the JSF page where you want to add or remove ADF regions at runtime and choose Go to Page Definition from the context menu.
Click Yes if a confirmation dialog appears.
In the overview editor for the page definition file, click the Add icon in the Executables section to display the Insert Item dialog.
Select ADF Task Flow Bindings from the dropdown list, then select multiTaskFlow as the item to create and click OK.
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 21-15, enter the following EL expression:
#{pageFlowScope.multiBean.taskFlowList}
In the Application Navigator, select and open the JSF page where you want end users to add or remove ADF regions at runtime.
In the ADF Faces page of the Component Palette, from the Operations panel, drag a For Each component and drop it on the component in the Structure window that you want to enclose the For Each component.
In the Property Inspector 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.
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 21-16.
Metadata similar to that shown in Example 21-17 appears in the JSF page definition file for the multi task flow binding.
Example 21-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.
We recommend that you 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 21.4, "Specifying Parameters for ADF Regions Using Parameter Maps."