ADF Hands-On
Dynamic Regions
Abstract:
In this hands-on, you create a dynamic ADF Region and
configure it with partial refresh to update the region
content based on an input parameter passed in from the
parent page. In addition, it shows you how to detect and
work with region capacities to navigate regions from the
outside.
Duration: 90 Minutes
2010 / 2011
ADF Internal Enterprise 2.0 Training
1
ADF HANDS-ON Dynamic Regions
Introduction
ADF bounded task flows that are built with JSF page fragments are exposed as static or dynamic
regions on a paremt view.
The static region configuration points the ADF Region binding, which is created in the parent
page's PageDef.xml file in after dropping a task flow definition as a region onto a page, to the
document location and task flow id of the task flow to render in the ADF Region.
With dynamic regions, the task flow id of the task ADF Region binding is pointing to a managed
bean method that returns a string with the task flow definition to load. Dynamic regions thus can
show different task flow processes depending on user selections or context settings.
The application you are building in this hands-on is shown in the image below:
A tree component to the left shows locations that are already filtered by the business service to
ensure they all have associated departments in the data model. Users select a location to refresh
the ADF Region display to either show a list of departments or employees working in departments
related to the chosen location. Users can switch between Departments and Employees using the
two command buttons on top. Users then select and employee or department and navigate to an
edit form. This can be done using anavigation command in the ADF Region or the select list and
2
ADF HANDS-ON Dynamic Regions
"Navigate" button outside of the ADF Region. The image above shows the edit form opened for
the Finance department.
Note: This hands-on is created to focus on the ADF Contextual Event functionality. The UI is
functional and no time is spend on making it look beautiful.
Prerequisite and Setup
This hands-on requires a database to be available that has the HR schema installed and enabled. The
Oracle XE and Oracle enterprise database both have this schema available and no scripts need to be run.
The Oracle JDeveloper 11g starter workspace is contained in the DynamicRegionSample.zip file. Open
the zip file and extract its content to a local directory on your computer.
Open Oracle JDeveloper and choose Application | Open from the file menu. Navigate to the folder you
extracted the zip file to and select DynamicRegionSample | DynamicRegionSample.jws
To change the RDBMS connection, select View | Database | Database Navigator from the Oracle
JDeveloper menu. Select the database connection node in the "DynamicRegionSample" node and use the
right mouse context menu to edit its properties and change the connect information.
Building the Departments Browse / Edit Task Flow
Using ADF, the business service implementation technology is not really important to know about for the
application developer. What's important is the functionality and data exposed by the business service. This
information is displayed in the Data Controls panel.
In this hands-on we use ADF Business Components as a business service. The ADF BC model exposes
three collections (View Objects) to query a list of departments, employees and locations. The departments
and employee list are parameterized using a bind variable. For both, you need to pass a location Id in to
query departments and employees. The locations collection is filtered by a View Criteria, which ensures
you only see locations with departments. There is nothing however you need to do in this hands-on to get
this functionality working.
To reduce the time for you to build the sample, the bounded task flow for querying and editing employees
is pre-created.
To save you from typing Java, all managed beans that aren't auto-generated by Oracle JDeveloper are
contained in the ViewLayer project. However, though you don't have to type the Java code, you may want
to have a look at what the bean methods are actually doing.
3
ADF HANDS-ON Dynamic Regions
1. The departments bounded task flow you are going to build first is a copy of the employees bounded
task flow. For you to have an idea how it looks, double click onto the employees-btf-definition.xml file in
the Application Navigator
2. Close the employees bounded task flow diagram view.
3. On the ViewController project, choose New from the context menu
4
ADF HANDS-ON Dynamic Regions
4. In the New Gallery, choose General | We Tier | JSF
5. Select ADF Task Flow in the "Items" list
5
ADF HANDS-ON Dynamic Regions
6. In the "File Name" field, type departments-btf-definition.xml. Make sure the "Create as Bounded Task
Flow" and "Create with Page Fragments" checkbox is selected
7. Press OK. This closes the dialog and – after a few seconds – opens the task flow visual editor showing
the empty task flow definition you just created
8. Open the JDeveloper Component Paletter (ctrl+shift+P)
9. Select the "Method Call" activity and drag it onto the diagram. This adds the method call activity to the
diagram and also renders it with a green halo to indicate this to be the default activity. Bounded task flows
always start with the default activity, which in this case is a method ensuring the departments are queried
by the location Id parameter passed in.
6
ADF HANDS-ON Dynamic Regions
10. Name the Method Call Activity "executeQuery"
11. Drag and Drop two View Activities from the Component Palette and name them "allDepartments"
and "editDepartment
12. Select the "Control Flow Case" entry in the Component Palette and draw a line between the
"executeQuery" Method Call Activity and the "allDepartments" View.
7
ADF HANDS-ON Dynamic Regions
13. Leave the navigation case name as "*". We don't have other navigation cases to define for the
"executeQuery" method call, so there is no need to be specific about it. The "*" basically says that all
navigation calls will go to the "allDepartments" view.
14. Create two additional navigation flows.
15. Name the flow between the "allDepartments" view and the "editDepartment" view as
"editDepartment.
16. Name the flow between the "editDepartment " view and the "allDepartments " view as
"submitDepartment.
17. To configure the managed bean to hold the location Id value passed into the task flow, click onto the
"Overview" tab at the bottom of the editor.
8
ADF HANDS-ON Dynamic Regions
18. Select the "Managed Beans" category
19. Type "inputParameterBean" into the Name field. This will become the name of the managed bean
when referenced from EL
20. In the Class field, type "taskFlowInputBean" and choose the bean from the select list
21. Set the Scope to "pageFlow". Note that input parameters may be needed on different activities in a
page flow. Using page flow scope ensures the availability of the input parameters throughout the lifetime
of the managed bean session, which ends when users exit the task flows.
9
ADF HANDS-ON Dynamic Regions
22. Select the "departments-btf-definition.xml file in the JDeveloper Application Navigator
23. Open the Structure Window (ctrl+shift+S)
24. Select the departments-btf-definition entry under the "ADF Task Flow" node
25. Open the Property Inspector (ctrl+shift+I)
26. In the Property Inspector, navigate to the "Parameters" section
27. Press the green plus Icon to create a new input parameter
28. Type "locationId" into the Name field.
29. In the Class field type "oracle.jbo.domain.Number" as the type of the argument object passed in. This
information is actually not used by the IDE and not at runtime either. However, it allows you to describe
the task flow input parameters.
30. Click the arrow icon next to the "Value" field and choose "Expression Builder". The Value field
allows you to determine where the input parameter value becomes available in the called bounded task
flow.
Note: For this hands-on, we have the value stored in a managed bean. The benefit of using a managed
bean to hold input parameters is that managed beans are discoverable in the Expression Builder at design
time, in opposite to memory scoped attributes.
10
ADF HANDS-ON Dynamic Regions
31. Navigate to the ADF Managed Beans | paheFlowScope | inputParameterBean entry and select its
"locationId" property.
Note: Don't select the locationId entry with the green square icon. This is a representation of the input
parameter name, which should not even be displayed in the EL editor (it’s a known issue)
32. Select the Required field checkbox. This ensures developers do map the input parameter to a value
when adding the task flow to a page
11
ADF HANDS-ON Dynamic Regions
33. Go back to the task flow diagram
34. In the Data Controls panel, select the "setLocIdVar(Number)" method and drag and drop it to the
"executeQuery" method call activity. This creates a PageDef.xml file for the method call activity and
creates an entry for the setLocIdVar method. In addition, it binds the method call activity to ADF
method entry.
35. In the opened "Edit Action Binding" dialog, click the arrow icon next to the "Value" field and bring
up the Expression Builder
12
ADF HANDS-ON Dynamic Regions
36. In the Expression Builder, type the following Expression before closing the dialog pressing Ok
#{pageFlowScope.inputParameterBean.locationId}
The EL string added to the Value field ensures the task flow input parameter value is passed as an
argument to the business service, where it is used to set the bind variable to filter the departments query.
Note: Oracle JDeveloper 11.1.1.4 doesn't show the full expression for declarative selection. This is a
known issue with the build used to create the hands-on
37. Press OK to close the "Edit Action Dialog".
38. Double click on to the "allDepartments" view activity to create a page fragment
39. Keep the default name
40 Select the "Blank Page" option and press OK
13
ADF HANDS-ON Dynamic Regions
41. Open the Component Palette (ctrl+shift+P) and expand the "layout" category
42. Select the "Panel Splitter" component and drag it to the page fragment
43. With the Panel Splitter selected, open the Property Inspector (ctrl+shift+I) and set its "Orientation"
property to "vertical"
44. Select the "allDepartmentsInLocations" collection in the Data Controls panel and drag it onto the top
facet of the Panel Splitter
45. In the opened context menu, choose Table | ADF read-only Table
14
ADF HANDS-ON Dynamic Regions
46. In the "Edit Table Columns" dialog, select the "Single Row" row selection option and enable sorting
and filtering as well.
Note: If you use JDeveloper 11.1.1.3 or earlier, then the dialog differs from the screenshot below.
47. From the ADF Faces Component palette, select the Panel Group Layout component in the Layout
category and drag it to the bottom facet of the Panel Splitter.
48. Drag a Button component into the Panel Group Layout component.
15
ADF HANDS-ON Dynamic Regions
49. Change the button text property to "Edit Department"
50. Set the "Action" property to "editDepartment" so that when the button is pressed, navigation happens
to the edit form
51. In the task flow diagram, double click the editDepartment view activity
16
ADF HANDS-ON Dynamic Regions
52. Accept the suggested name for the page fragment and again choose the "Blank Page" option
53. Press OK
17
ADF HANDS-ON Dynamic Regions
54. Drag and drop the "allDepartmentsInLocations" collection from the Data Controls panel onto the
page fragment.
55. Choose Form | AD Form from the opened menu
56. Select the "Include Submit Button" checkbox. This adds a command button to the edit form
57. Press OK
58. With the "Submit" button selected, open the Property Inspector
59. Set the button's "Action" property to "submitDepartments"
18
ADF HANDS-ON Dynamic Regions
60. Save the application
19
ADF HANDS-ON Dynamic Regions
Creating the Dynamic Region
A dynamic region is created by dragging task flows as a region and region links onto a parent view or
page.
1. Select the ViewController project and choose "New" from the right mouse context menu. Select the
JSF entry and create a new JSF Page.
2. Define the File Name as "LocationsView" and ensure the "Create as XML Document (*.xml) box is
checked.
3. Select the "Quick Start Layout" radio group and press the "Browse" button
4. In the Quick Layout Component Gallery, select the "Two Column" category and select the layout
shown in the image below
5. Press OK to close the Layout Gallery
20
ADF HANDS-ON Dynamic Regions
6. Press OK to close the JSF page creation dialog
7. Drag and drop a Panel Splitter component from the ADF Faces Component Palette to the "center"
facet of the JSF page fragment.
21
ADF HANDS-ON Dynamic Regions
8. With the Panel Splitter component selected, open the Property Inspector
9. Set the Panel Splitter "Orientation" property to vertical.
10. In the Data Controls panel, select the "allLocationsWithDepartments" collection and drag and drop it
to the left facet area.
11. In the opened context menu, select Tree | ADF Tree
12. In the "Edit Tree" dialog, move the City attribute from the list of "Available Attributes" to the list of
"Display Attributes"
13. Press "OK"
22
ADF HANDS-ON Dynamic Regions
14. Press the "Bindings" tab at the bottom of the JSF page fragment
15. In the binding editor, click the green plus icon to create a new attribute binding. We use an attribute
binding as a little trick to simplify access to the selected location id in the tree component.
23
ADF HANDS-ON Dynamic Regions
16. Select "attributeValues" to create a new attributes binding
17. Press OK
18. In the opened "Create Attribute Binding" dialog, select the "allLocationsWithDepartments" data
source, which is the same source the tree component is bound to
19. Select the "LocationId" attribute
20. Press OK
24
ADF HANDS-ON Dynamic Regions
21. Drag the "departments-btf-definition.xml" task flow definition you created earlier and drop it to the
bottom facet of the Panel Splitter component you added earlier.
22. On the opened "Create" dialog, choose the "Dynamic Region" entry
23. Dynamic regions reference a managed bean to obtain the task flow Id of the task flow to display. The
managed bean is created using the "Choose Managed Bean for Dynamic Region" dialog
24. Provide the following values to the dialog
Bean Name
locationsViewBean
Class Name
LocationsViewBean
Package
adf.sample.view.managed.bean
25
ADF HANDS-ON Dynamic Regions
25. Note the "Scope" of the managed bean. Its "backingBean", a scope that you need to change in a next
step
26. Press OK to close the Create Managed Bean dialog
27. Press OK to close the "Choose Managed Bean for Dynamic Region" dialog
28. "The Edit Task Flow Binding" dialog opens for you to define input parameters and parameter values
for the task flows to call. In the hands-on, both task flows have the same input parameter "locationId".
To create this parameter reference, press the green plus icon
29. The Input Parameter name must match the name of the input parameter defined on the task flow. If
the name does not match, then no input value is passed to the task flow and the task flow fails to query
the departments or employees. Type "locationId" into the Name field
30. Click onto the "arrow" icon next to the "Value" field.
26
ADF HANDS-ON Dynamic Regions
31. Select the "Expression Builder" entry on the menu
32. In the Expression Builder dialog, expand the ADF Bindings | bindingsLocationId node and search
for the "inputValue" attribute.
33. Select the "inputValue" attribute and press OK to close the dialog
34. Press OK to finish the task flow editing.
Note: If task flows have different sets of input parameters, you would use an input parameter map
instead of a named input parameter configuration.
27
ADF HANDS-ON Dynamic Regions
35. Next, select the adfc-config.xml configuration file in the ViewController | Web Content | WEB-INF
folder in the JDeveloper Application Navigator. The " locationsViewBean", which is referenced from the
task flow binding is defined in this file.
36. Open the Structure Window (ctrl+shift.S)and select the "locationsViewBean" bean entry
37. Open the Property Inspector (ctl+shift+I)
38. Select the "Managed Bean Scope" property value list box and choose "view". The viewScope is longer
than the backingBean scope, which has the same duration as "request". This ensures the selected task flow
reference does not change between requests.
39. In the visual page editor, select the ADF Region and open the Property Inspector
40. Select the "PartialTriggers" property and click the "arrow" icon at its end
41. Choose the "Edit" option on the opened menu
42. In the hierarchy of available page components, select the tree component and move it to the list f
Selected components. This ensures the ADF Region is refreshed when the tree node selection is changed
by a user.
28
ADF HANDS-ON Dynamic Regions
43. Ok the dialog
44. Click on the "Bindings" tab at the bottom of the visual page editor
45. In the binding's "Executables" section, select the "taskflow – dynamicRegion1" entry and open the
Property Inspector
46. For the ADF Region to refresh and re-query the departments or employees collection, the Refresh
property must be set to "ifNeeded", as shown in the image below
29
ADF HANDS-ON Dynamic Regions
47. Note that the "taskFlowId" property still has the "backingbeanScope" referenced in its EL expression.
This reference needs to be changed as the bean no longer is in backingBeanScope but viewScope.
48. Press the button next to the "taskFlowId" property field
49. In the Expression Builder dialog, expand the "viewScope" node under the ADF Managed Bean entry
and select the locationsViewBean | dynamicTaskFlowId property. The property references the managed
bean getter /setter method that returns the task flow Id to display in the region.
50. OK the dialog. The "taskFlowId" property should be updates as shown in the image below
30
ADF HANDS-ON Dynamic Regions
51. Next, drag the Panel Group Layout component onto the top facet of the Panel Splitter, as shown
below.
52. Open the Property Inspector and set the "layout" property of the Panel Group Layout component to
"horizontal"
53. Drag and drop the departments-btf-definition.xml file from the ViewController | Web Content |
WEB-INF folder.
54. In the dialog that is opened by the drop action, choose Dynamic Region Link | dynamicRegion1.
31
ADF HANDS-ON Dynamic Regions
55. Select the "employees-btf-definition.xml" file entry in the ViewController | Web Content | WEBINF folder and drag and drop it next to the link you created before. Make sure the link is added in the
Panel Group Layout
56. Choose Dynamic Region Link | dynamicRegion1 in the opened menu
Note: the two links reference methods in the locationsViewBean to set the task flow id of the task flow to
display when the ADF Region refreshes
57. To turn the link into command buttons, use the right mouse button to select the "Button" component
in the Component Palette. Then, still with the right mouse button pressed, move the button onto the link.
32
ADF HANDS-ON Dynamic Regions
58. In the opened popup menu, select "Convert to Button"
59. Repeat this step for the second link too
60. Rename the "Text" property of the command buttons to
Departments
Employees
61. Open the LocationsViewBean.java class, which is the managed bean class that got created for you
when creating the Dynamic Region. Note the two methods to set the task flow document references.
These methods are referenced from the two buttons, which at runtime are used to switch between the
departments and employees task flow.
62. Select the LocationsView.jspx document in the Application Navigator and choose the "Run" option
from the right mouse context menu.
33
ADF HANDS-ON Dynamic Regions
63. Select a location in the tree. The departments table is updated showing those departments that belong
to the selected locations node.
64. Use the "Employees" button to switch to the employees task flow showing employees working in a
department belonging to the selected location.
65. Use the "Edit Department" or "Edit Employee" button to navigate to the edit form.
34
ADF HANDS-ON Dynamic Regions
Navigating the Dynamic Region from the parent view
Dynamic regions are task flows that allow users to navigate between page fragments. You can get
information about the navigation options for the current displayed view in a region and also perform
navigation triggered from the parent page.
1. In the ADF Faces Component Palette, select the "Select One Choice" component and drag it onto the
page, dropping it next to the Employees button in the Panel Group Layout. The Select One Choice
component is used in this example to list the navigation options for the current displayed task flow and
page fragment.
2. In the opened dialog, click the "Bind" button next to the Value field.
3. Expand the ADF Managed Beans | viewScope node
35
ADF HANDS-ON Dynamic Regions
4. Select the "navList" property of the taskFlowCapabilities bean. The taskFlowCapabilities bean has been
pre-created and configured for you. It contains code to access the ADF Region and to determine the
navigation options for the current displayed view.
5. Click Ok
6. Click Next
7. Type "Navigation Options" into the Label field.
36
ADF HANDS-ON Dynamic Regions
8. Click the arrow icon at the end of the Value field and choose "Expression Builder" in the opened menu
9. The Select One Choice component updates a managed bean property. To reference the managed bean,
Expand the ADF Managed Beans | viewScope node. Select the "currentNavOption" property of the
"taskFlowCapabilities" bean entry.
10. OK the dialog
11. Press the Finish button
37
ADF HANDS-ON Dynamic Regions
12. Add a Button next to the Select One Choice component. When the user presses the button, the
navigation option that is selected in the list will be performed.
13. With the command button selected, open the Property Inspector and set the command buttons
PartialSubmit property to true.
38
ADF HANDS-ON Dynamic Regions
14. Select the Select One Choice component
15. Open the Property Inspector and search for the PartialTriggers property
16. Press the arrow icon at the end of the PartialTriggers property field.
17. Select "Edit" on the popup menu to bring up the PartialTriggers Edit dialog
18. In the dialog, find the two command button and the region components and move them to the list of
"Selected" components. Doing so causes a partial refresh of the Select One Choice component whenever
an event, like action on the buttons or navigation on the ADF Region, is invoked on the selected
components.
19. Still, with the button selected, find its "Action" property
20. Press the arrow icon and again choose Edit from the displayed menu
39
ADF HANDS-ON Dynamic Regions
21. In the Action editing dialog, select the "taskFlowCapabilities" managed bean and the navPickerAction
method. The navPickerAction reads the property holding the current Select One Choice component
selection to navigate the region.
40
ADF HANDS-ON Dynamic Regions
22. Select the ADF Region component in the page and open the Property Inspector
23. Click the arrow icon next to the RegionNavigationListener property
24. In the opened menu, choose Edit
25. In the RegionNavigationListener dialog, select the taskFlowCapabilities managed bean
26. Select the "regionNavigationListener" method for the "Method" option. The region navigation listener
is invoked whenever navigation is performed in the current displayed task flow. The region listener makes
sure the navigation options displayed in the Select One Choice component are updated for the current
page fragment.
41
ADF HANDS-ON Dynamic Regions
27. Open the departments-btf-definition.xml file in the visual editor by double clicking on the file in the
Oracle JDeveloper Application Navigator
28. Open the Component palette and drag and drop a Wild Card Control Flow Rule as shown in the
image below. The additional control flow rule is needed to show a choice of navigation options when
testing the sample.
29. Create a Control Flow case between the Wildcard Control Flow Rule and the editDepartment view
activity.
30. Name the rule "wildCardEditDepartment". A wild card rule basically means that the navigation can be
called from anywhere in the flow.
42
ADF HANDS-ON Dynamic Regions
31. Open the employees-btf-definition.xml file in the visual editor by double clicking on the file in the
Oracle JDeveloper Application Navigator
32. Repeat steps 28 and 29 for the employees task flow.
33. Name the rule "wildCardEditEmployees".
34. Before you run the application! Make sure the ADF Region id property is set to "r1".
35. Select the ADF Region component on the page
36. Open the Property Inspector and find the Id property
43
ADF HANDS-ON Dynamic Regions
37. If the Id property value is not r1, change it to r1. The taskFlowCapabilities bean makes the
assumption that the ADF Region ID is set to "r1".
38. Select the LocationsView.jspx file in the Application Navigator and choose the "Run" option from the
context menu
39. Navigate between the Departments and Employees task flow using the Departments and Employees
buttons. Note how the content of the Select One Choice is updated with each change. Also navigate to an
edit form and see the change of options for this.
40. Select a navigation option
41. Press the "Navigate" button
44
ADF HANDS-ON Dynamic Regions
42. Pressing the Navigate button queues the navigation event on the ADF Region. As a result the edit
form is shown.
Note: The ability to navigate a region from its parent view is an important pattern in ADF Region
interaction.
RELATED DOCOMENTATION
45