Functional Pattern Pattern Revision Technologies Keywords Publisher Publish date ADF Region Interaction 1.

0 JDeveloper 11g, ADF, ADF Faces, ADF Controller Region David Giammona January 22, 2009

Problem Description
There are often times when application interaction is required between an ADF region and its containing page. This communication typically involves initiating navigation or sharing application data. Since an ADF region represents a separate task flow definition with its own boundaries, any interaction across those boundaries must be considered carefully. Depending on the specific ADF region interaction use case, different approaches are utilized to implement the desired behavior. The many different approaches involved under the umbrella of ADF region interaction can make selecting the appropriate solution a challenge. This document describes each of these ADF region interaction approaches to assist in determining which best fits any given situation. If the initiation of navigation is required, the table below identifies the recommended approach based on the corresponding region use case. Each approach is described further within the document.
Navigation Navigate Root View Port (Browser) Navigate Containing Page From Region Navigate Region From Containing Page Identify Navigation Within Region Recommended Approach Task Flow URL View Activity Task Flow Parent Action Activity queueActionEventInRegion(…) Method regionNavigationListener

If data sharing is required, the table below identifies the recommended approach based on the corresponding region use case. Each approach is described further within the document.
Data Shared Entire Data Control Frame Small Subset When Restarting Region Task Flow Small Subset Without Restarting Region Task Flow Available Outcomes Based on Current State of Region Recommended Approach Task Flow Definition <data-control-scope> Task Flow Definition Input Parameters Contextual Framework Events - or Task Flow Definition Input Parameters for Objects Passed By Reference Region Capabilities

ADF Region Interaction 1

No matter where the URL view activity is performed. optionally a different outcome can be specified for an alternate navigation back within the same region. ADF Region Interaction 2 . They also have an advantage in that if the outcome specified for navigation of the parent task flow is not found at runtime.google. "Using URL View Activities". Parent action activities aren’t limited to only initiating navigation for the root browser page like task flow URL view activities.com</url> </url-view> For further details on task flow URL view activities.Functional Implementing the Pattern Navigation – Task Flow URL View Activity If a region needs to initiate navigation of the root browser page.3. even from within a nested region. Task flow URL view activities incorporate the following metadata within a task flow source file: <url-view id="urlView1"> <url>http://www. it will always navigate the root browser page. a task flow URL view activity can be used. a task flow parent action activity can be used. Navigation – Task Flow Parent Action Activity If a region needs to initiate navigation of the parent page. A task flow URL view activity redirects the root browser page (view port) to a specified URL. refer to the Oracle Fusion Middleware Fusion Developer's Guide for Oracle ADF within Section 14.

It will initiate navigation within the adfc-config parent task flow using the outcome “globalHome” as specified within its metadata. ADF Region Interaction 3 . The customer-registration-task-flow is utilized as a region on the register page within the adfc-config shown below.Functional Task flow parent action activities incorporate the following metadata within a task flow source file: <parent-action id="Exit"> <parent-outcome>globalHome</parent-outcome> </parent-action> In the customer-registration-task-flow shown above. the activity labeled “Exit” is a parent action activity. The “home” page within the adfc-config will then be displayed. If the “exitRegistration” outcome is perfomed within the customer-registration-task-flow region. the parent action activity will be executed.

the recommended approach is to utilize the queueActionEventInRegion(…) method located within the oracle.adf. Example used taken from the Oracle Fusion Store Front Demo Application. refer to the Oracle Fusion Middleware Fusion Developer's Guide for Oracle ADF within Section 14.1. For example.RichRegion class.view. the buttons on the page shown below navigate the contained region between the Employees and Departments page fragments.rich.rich. "Using Parent Action Activities". ADF Region Interaction 4 . Additional information can also be found in section 16.component.Functional For further details on task flow parent action activities.9. The queueActionEventInRegion(…) method queues an ActionEvent to behave as if it was queued on a UIXCommand component existing inside the region or nested region.6 “How to Trigger Navigation of an ADF Region's Parent Task Flow”.fragment. Navigation – queueActionEventInRegion(…) Method When a page needs to initiate navigation within one of its contained regions.

outcome = "departments". The queueActionEventInRegion(…) method initiates the “employees” or “departments” outcome depending on which button is selected. The Java methods performed by the “Employees” and “Departments” buttons on the parent page might be similar to the following: private String region = "taskf1". handleOuterPageAction(actionEvent). ADF Region Interaction 5 . private String outcome = "departments". public void handleOuterPageActionDepartments(ActionEvent actionEvent) { region = "taskf1". the buttons are disabled accordingly using region capabilities.Functional The contained region’s task flow definition includes the “Employees” and “Departments” view activities along with the control flow between them. Based on the region’s current state.

} When passing a String to identify the region or nested region component to a findComponent() method the following syntax can be used (“R1”=region.RegionModel class.createMethodExpression(elc.class.getOutcomeExpression}". false. } public void handleOuterPageAction(ActionEvent actionEvent) { UIComponent regionComponent = actionEvent.findComponent(region). For further details on the queueActionEventInRegion(…) method. “:R1:R2:R3…” – always looks for R3 starting from the root of the component tree. ELContext elc = fc. ExpressionFactory ef = fc. null. outcome = "employees". This syntax wouldn’t work if the button were located inside R1. if (regionComponent instanceof RichRegion) { FacesContext fc = FacesContext.getCurrentInstance().rich. String. “R2”=nested region”.getExpressionFactory(). -1. null.getELContext(). ((RichRegion)regionComponent). "#{ADFRegionNavigationBean. new Class[] { }). etc…):   “R1:R2:R3…” – looks for R3 relative to the button initiating the ActionEvent.model. } } public String getOutcomeExpression() { return outcome.ANY_PHASE). MethodExpression me = ef. this syntax should always work. Therefore.view.adf. refer to the Initiate Control Flow within a Region from its Parent Page pattern document on OTN or the oracle.Functional } public void handleOuterPageActionEmployees(ActionEvent actionEvent) { region = "taskf1". -1.getComponent(). handleOuterPageAction(actionEvent).queueActionEventInRegion(me.getApplication(). PhaseId. ADF Region Interaction 6 .

Then the RegionNavigationEvent triggers the regionNavigationListener EL method reference specified on the <af:region> tag.event.PopupDynamicRegionBean. <af:popup id="popupRegion1" contentDelivery="lazyUncached" launcherVar="source" eventContext="launcher"> <af:setPropertyListener from="#{source.popupTaskFlowId}" to="#{pageFlowScope.RegionNavigationEvent is raised. The event provides both the old and new page fragment viewIds. if any. an <af:region> regionNavigationListener is required if the dynamic region within an <af:popup> provides the ability to “exit” via navigation flow to task flow return activities.view. When the page fragment displayed within a region changes an oracle.attributes. Therefore. For example. any application logic required when the region navigation can be incorporated into its regionNavigationListener.adf.Functional Navigation – regionNavigationListener An <af:region> regionNavigationListener is used if a containing page or page fragment needs to identify when navigation occurs within a region.dynamicTaskFlowId}" ADF Region Interaction 7 .rich. The regionNavigationListener would be specified on the <af:region> UI component as shown below.employeeId}" type="popupFetch"/> <af:setPropertyListener from="#{pageFlowScope. its <af:region> regionNavigationListener should programmatically hide the <af:popup> after executing either the “save’ or “cancel” task flow return activities to exit the task flow definition. Using the employee-update task flow definition below for the region.employee}" to="#{pageFlowScope. The regionNavigationListener identifies when the region “exits” so the <af:popup> can be programmatically dismissed without the user manually selecting its close icon.PopupDynamicRegionBean.

PopupDynamicRegionBean.getParent().Functional type="popupFetch"/> <af:panelWindow id="window" title="Employee Popup"> <af:region value="#{bindings.regionModel}" id="dynam1" regionNavigationListener="#{pageFlowScope. do { if (component instanceof RichPopup) { found = true.navigationListener}"/> </af:panelWindow> … </af:popup> The regionNavigationListener Java method would be similar to the following. // look for the parent popup boolean found = false.getSource(). The method identifies when the region exists via task flow return activity (“newViewId == null”) and then programmatically hides the <af:popup>.dynamicRegion1. } } } while (!found). if (found) { ADF Region Interaction 8 . // null new view id indicates the taskflow has ended if (newViewId == null) { RichRegion region = (RichRegion)event. public void navigationListener(RegionNavigationEvent event){ String newViewId = event. if (component == null) { break. UIComponent component = region.getNewViewId().getParent(). } else { component = component.

getClientId(context) + "'). popup. Default value of the <data-control-scope> property is “shared”. multiple regions can share the data controls of their same containing page or page fragment. nested regions can share the data controls of their parent regions to any depth. Share Data – Task Flow Definition <data-control-scope> If a region should share all the same application data controls as the task flow of its parent page or page fragment. data controls can be shared. Also. Example used taken from the Embedding Regions Inside Popup Windows pattern document on OTN. only its parent page or page fragment.class). If the region and its parent page or page fragment are part of the same transaction or one/both don’t reside within any transaction. By setting the region task flow definition <data-control-scope> property to “shared” all the same data controls of the parent page task flow will be used by the region. "var popup = AdfPage. ExtendedRenderKitService."). A region can’t share the data controls of another region.PAGE.addScript(context. However. } } } For further details on the <af:region> tag.getRenderKitService(context.hide(). Service. refer to the Oracle ADF Faces <af:region> Tag Documentation.findComponent('" + component. Setting the task flow definition <data-control-scope> property explicitly to “shared” incorporates the following metadata within a task flow definition source file: <data-control-scope> <shared/> </data-control-scope> ADF Region Interaction 9 .Functional // send script to the client to hide the popup FacesContext context = FacesContext.getCurrentInstance(). the recommended implementation approach utilizes the task flow definition <data-control-scope> property. The task flow definition <data-controlscope> property can also be set to “isolated” if the data controls of the region should remain completely separate. Data controls cannot be shared between two different task flows residing within two different transactions.

Input parameters are very useful if a regions task flow must be restarted when any of the values passed to the region change. When a taskFlow binding Refresh attribute is set to “ifNeeded”. ADF Region Interaction 10 . refer to the Oracle Fusion Middleware Fusion Developer's Guide for Oracle ADF within Section 15. Changing the selected employee requires restarting the benefits enrollment region from the beginning for the newly selected employee. For further details on task flow definition input parameters. the region will be refreshed and restarted automatically whenever an input parameter value changes. refer to the Oracle Fusion Middleware Fusion Developer's Guide for Oracle ADF within Section 15. "Sharing Data Control Instances". Share Data – Task Flow Definition Input Parameters A region cannot directly reference the binding values of its containing page or page fragment. Task flow call activities support overriding the passing of object instance input parameters by reference to passing them by value. The same holds true for a containing page or page fragment being unable to directly reference binding values within a region.7. Task flow definition input parameters are typically used as a means of sharing a small subset of data with a region when the values are well known and EL-accessible to the containing page or page fragment. "Passing Parameters to an ADF Bounded Task Flow" and Section 16. Using this approach. a page might contain a table of employees and a region for enrolling the selected employee in benefits. however. "What You May Need to Know About Refreshing an ADF Region".2. task flow definition input parameters can be specified. This is not a recommend approach to pass values back to the parent. Therefore. by passing the value of the selected employee as an input parameter to the region and setting its taskFlow binding Refresh=”ifNeeded” the region will be refreshed and restarted automatically whenever the selected employee changes. All object input parameters are passed to a region by reference. do not provide the same override capability. Each time the ADF task flow within a region is restarted. In order to share a small subset of values between the two. they will always be passed by reference. any updates to the passed object instance by the parent page or page fragment will then be automatically reflected back within the region without restarting the corresponding ADF task flow. care should be taken to ensure values passed by reference are updated appropriately. Regions.3.1. When object instances are passed as a region input parameter. For example. the updated object instance values will be visible to the parent page or page fragment. if the region updates a mutable object instance after it’s passed as an input parameter.Functional For further details on the task flow definition <data-control-scope> property. All primitive value input parameters are passed to a region by value. fresh input parameter values will be passed. Therefore. Likewise. A regions taskFlow binding Refresh and RefreshCondition attributes can also be useful to ensure the region will be refreshed and restarted under the appropriate conditions to accept new input parameter values.

It simply responds to a contextual framework event to display a specified tab. support calls. tree bindings. After checking the same binding container where the contextual framework event was raised. contextual framework events are passed to their binding container for dispatch. Contextual framework event is raised after the attribute is set successfully. Contextual framework events are always consumed by methods. Once raised. The regions page fragment displays a separate tab for the customers products purchased. the 360-degrees customer view region will display the Support Calls tab. The table below describes when each binding type raises contextual framework events. Can also be triggered by navigational changes. This process continues until the topmost parent binding container is reached. List) When Contextual Framework Event Raised Contextual framework event is raised when the action or method is executed. event propagation is then delegated to check for consumers within the parent binding container event map. Contextual framework event is raised after the currency change has succeeded. Method result forms the contextual framework event payload of data to share. Contextual framework events are recommended if the ADF region interaction use case fits the following two conditions:   Notification occurs after the regions corresponding ADF task flow has started Changes in any data shared by the notification shouldn't restart the regions corresponding ADF task flow For example. or list bindings. If the “Support Calls” node in the tree is selected. table bindings. The binding container’s contextual framework event dispatcher checks the event map defined within the binding containers page definition file for interested consumers. It’s also possible for a contextual framework event to include a payload of data to share. Can also be triggered by navigational changes. Table. the contextual framework event is delivered to the consumers at the end of the ADF lifecycle. and contact information. If interested consumers are identified. A second region on the same parent page provides a tree to display one of the three tabs within the 360-degree customer view region. method action bindings. Binding Type Action and MethodAction Bindings Value Attribute Bindings Range Bindings (Tree. ADF Region Interaction 11 . The 360-degree customer view regions task flow isn’t restarted with a new customer. value attribute bindings. a page might contain a region providing a 360-degree customer view. the contextual framework event is then dispatched to child region binding containers to check event maps defined with an event producer set to wildcard "*".Functional Share Data – Contextual Framework Events Contextual framework events are often used for notifications between an ADF region and it’s containing page or page fragment. After the topmost binding container is reached. Contextual framework events can be raised by the execution of action bindings.

oracle. In the example below. The HelpId methodAction result will be placed within the contextual framework event payload and passed along to any event consumers. or list bindings. RowIterator helpItr = helpVO.Functional Event Producer Contextual framework events are produced by page definition action bindings. ADF Region Interaction 12 .createViewCriteria().setAttribute("HelpUsage".String"/> <events xmlns="http://xmlns. method action bindings. ViewCriteria vc = helpVO.addElement(vcr). the contextual framework event will be raised.dataProvider" DataControl="LookupServiceAMDataControl" RequiresUpdateModel="true" Action="invokeMethod" MethodName="setHelpId" IsViewObjectMethod="false" ReturnName="LookupServiceAMDataControl. vc. When the methodAction binding is executed. Row helpRow = helpItr. the queueHelpTopic event is defined within the setHelpId methodAction binding. ViewCriteriaRow vcr = vc.findByViewCriteria(vc. table bindings. -1. vcr. The methodAction passes in a “usage” parameter and returns a corresponding HelpId value.first(). value attribute bindings.getHelpTranslations(). tree bindings.lang.QUERY_MODE_SCAN_DATABASE_TABLES). ViewObject. <methodAction id="setHelpId" InstanceName="LookupServiceAMDataControl.createViewCriteriaRow().com/adfm/contextualEvent"> <event name="queueHelpTopic"/> </events> </methodAction> The setHelpId method executed by the methodAction binding might be similar to the following: public Long setHelpId(String usage){ ViewObjectImpl helpVO = this. "=" + usage).setHelpId_LookupServiceAMDataC ontrol_dataProvider_setHelpId_result"> <NamedData NDName="usage" NDValue="CREATE_PROFILE" NDType="java.methodResults.

Functional return (Long)helpRow. The helpTopicId parameter of the consumer method is assigned the value of the contextual framework event payload passed from the producer. The consumer is identified as the helpPageDef. the JDeveloper Event Map Editor can also be used to greatly simplify the procedure. the “region” attribute is not needed within the event map <producer> and <consumer> elements. To access the Event Map Editor.com/adfm/contextualEvent"> <event name="queueHelpTopic"> <producer region="*"> <consumer region="helptaskflow1" handler="helpPageDef. the eventMap relates the queueHelpTopic event producer to its consumer. The producer is identified as any region.findHelpTextById method binding within the helptaskflow1 region. <eventMap xmlns="http://xmlns. In the example below.getAttribute("HelpId"). ADF Region Interaction 13 . } Event Map Contextual framework event maps relate together the producer and consumer of a given event. If the producer or consumer is not contained within a region.findHelpTextById"> <parameters> <parameter name="helpTopicId" value="${payLoad}"/> </parameters> </consumer> </producer> </event> </eventMap> Instead of manually creating page definition event map metadata. The consumer handler will be a specified method. Then in the eventMap element Property Inspector select the Edit toolbar button. add an eventMap element to a page definition in JDeveloper.oracle.

currently don’t incorporate values from any dynamic regions. and its consumer. After selecting the Event Map Editor Edit or Add toolbar buttons. The dropdowns incorporate values from the current page definition. It makes modifying or creating event map metadata easier by using dropdowns for the selection of the event. its producer. however. The dropdowns. the Modify Event Map Entry dialog is displayed.Functional The Event Map Editor dialog will be displayed to Edit an existing event or Add a new event within the event map. ADF Region Interaction 14 . but also the page definitions of any child regions. Those must be entered manually.

The value of the helpTopicId parameter is assigned within the event map as the value of the contextual framework event payload.lang. It passes in a helpTopicId and returns the corresponding HelpText.Functional Event Consumer The contextual event consumer will always be a method. Parameter values of the method can be assigned by the event map using the contextual framework event payload.findHelpTextById_LookupServiceA MDataControl_dataProvider_findHelpTextById_result"> <NamedData NDName="helpTopicId" NDValue="" NDType="java.methodResults.Long"/> </methodAction> The findHelpTextId method identified as the event consumer might be similar to the following: public String findHelpTextById(Long helpId){ ADF Region Interaction 15 . The value of the payload was set when the event was raised by the result of the producer method. <methodAction id="findHelpTextById" Action="invokeMethod" MethodName="findHelpTextById" IsViewObjectMethod="false" DataControl="LookupServiceAMDataControl" InstanceName="LookupServiceAMDataControl. In the example below. the contextual framework event consumer is the findHelpTextById methodAction binding.dataProvider" ReturnName="LookupServiceAMDataControl.

"Creating Contextual Events". ViewCriteria vc = helpVO.getAttribute("HelpText").QUERY_MODE_SCAN_DATABASE_TABLES). For this to occur automatically.setAttribute("HelpTranslationsId". ViewCriteriaRow vcr = vc. } For further details on implementing contextual framework events. return helpRow.createViewCriteriaRow(). ViewObject. the buttons are assigned a region capability EL Expression for their disabled property. refer to the Oracle Fusion Middleware Fusion Developer's Guide for Oracle ADF within Section 26.: displaying or enabling different icons and buttons).createViewCriteria(). Based on the regions current state. RowIterator helpItr = helpVO.g. either the “Employees” or “Departments” button should be disabled.5.first(). Example used taken from the Oracle Fusion Store Front Demo Application.addElement(vcr). vcr. -1.getHelpTranslations().Functional ViewObjectImpl helpVO = this. Row helpRow = helpItr. the “Employees” and “Departments” buttons on the parent page navigate between the Employees and Departments view activities within the region.toString(). In the following example. ADF Region Interaction 16 .findByViewCriteria(vc. The current capabilities of a region might dictate how the parent page responds (e. vc. Share Data – Region Capabilities Region capabilities can be used by a parent page to identify the current outcomes available based on a regions current state. "=" + helpId).

: nested regions). the buttons respond automatically by disabling as appropriate based on the regions state change.: #{bindings.taskflowdefinition1}). Therefore in cases where a regionModel cannot be reached within the current binding container (e. the queueActionEventInRegion(…) method is executed to initiate the corresponding “employees” or “departments” outcome within the region. Region capabilities require the availability of the specified regions regionModel through an EL Expression. This is because a nested regions nested binding container might not exist yet or might have already been released. Once the region navigates to the new view activity. An EL expression should never access bindings in any binding container other than the current binding container (e.Functional When each button is selected. region capabilities cannot be used. ADF Region Interaction 17 .g.g.

the “Employees” button disabled attribute was assigned the region capabilities EL Expression shown below.actions} getActions() In the example described previously. There will be a corresponding RegionAction outcome for every outcome returned by getCapabilities().the “Departments” button should be enabled and the “Employees” button disabled).RegionModel class. refer to the Initiate Control Flow within a Region from its Parent Page pattern document on OTN or the oracle.capabilities['outcome']} Returns the list of valid RegionActions based on the current state of a given region. EL Expression syntax: #{bindings. A RegionAciton is a combination of the outcome and display name of the associated control flow case.model.view.adf.capabilities} EL Expression returns “true” if the outcome specified is available based on the given regions current state: #bindings. It consists of the following methods: Region Capabilities Method getCapabilities() Description Returns the set of outcomes (capabilities) available based on the current state of a given region. Each region capability is represented as a String.regionModel.regionModel.view. ADF Region Interaction 18 .e. <af:commandButton text="Employees" disabled="#{bindings.taskflowdefinition1. taskFlowBinding. EL Expression syntax: #{bindings..regionModel.rich.model.RegionModel class.capabilities['departments']}" /> For further details on region capabilities. taskFlowBinding.regionModel.rich.adf. It disables the “Employees” button if the “departments” outcome is currently available within the taskflowdefinition1 region (i.taskFlowBinding.Functional The region capabilities APIs reside within the oracle.

rich. "Creating Contextual Events" in the Fusion Developer's Guide for Oracle ADF oracle. "Using Parent Action Activities" in the Fusion Developer's Guide for Oracle ADF Oracle ADF Faces <af:region> Tag Documentation.5. "Using URL View Activities" in the Fusion Developer's Guide for Oracle ADF Section 14.2. "Passing Parameters to an ADF Bounded Task Flow" in the Fusion Developer's Guide for Oracle ADF Section 16.3.view.Functional Related Patterns   Embedding Regions Inside Popup Windows Initiate Control Flow within a Region from its Parent Page Related Documentation Documentation Related to the Pattern Artifacts Task Flow URL View Activities Task Flow Parent Action Activities <af:region> Tag Task Flow Definition <data-controlscope> Task Flow Definition Input Parameters taskFlow Binding Refresh and RefreshCondition Attributes Contextual Framework Events RegionModel Section 14. Section 15.RegionModel class ADF Region Interaction 19 .9.3.adf. "Sharing Data Control Instances" in the Fusion Developer's Guide for Oracle ADF Section 15.7.1.model. "What You May Need to Know About Refreshing an ADF Region" in the Fusion Developer's Guide for Oracle ADF Section 26.

Sign up to vote on this title
UsefulNot useful