ADF Hands-On: - Oracle Software Downloads | Oracle ...download.oracle.com/.../TryIt/dynamic-region-hands-on.docx · Web viewThe static region configuration points the ADF Region binding,

1

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

2

ADF HANDS-ON Dynamic Regions

IntroductionADF 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

3


edit form. This can be done using anavigation command in the ADF Region or the select list and "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

4


don't have to type the Java code, you may want to have a look at what the bean methods are actually doing.

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

5


2. Close the employees bounded task flow diagram view.

3. On the ViewController project, choose New from the context menu

4. In the New Gallery, choose General | We Tier | JSF

5. Select ADF Task Flow in the "Items" list

6


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

7


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.

10. Name the Method Call Activity "executeQuery"

11. Drag and Drop two View Activities from the Component Palette and name them "allDepartments" and "editDepartment

8


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.

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.

9


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.

18. Select the "Managed Beans" category

10


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.

11


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.

12


13


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

14


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

15


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

16


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

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"

17


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

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.

18


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.

19


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

20


52. Accept the suggested name for the page fragment and again choose the "Blank Page" option

53. Press OK

21


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

22


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"

60. Save the application

23


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

24


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.

25


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"

26


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.

27


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

28


20. Press OK

29


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

30


Package adf.sample.view.managed.bean

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

31


30. Click onto the "arrow" icon next to the "Value" field.

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

32


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.

33


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

34


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.

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

35


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.

36


50. OK the dialog. The "taskFlowId" property should be updates as shown in the image below

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"

37


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.

55. Select the "employees-btf-definition.xml" file entry in the ViewController | Web Content | WEB-INF folder and drag and drop it next to the link you created before. Make sure the link is added in the Panel Group Layout

38


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.

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

39


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.

40


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.

41


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

42


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

43


7. Type "Navigation Options" into the Label field.

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

44


node. Select the "currentNavOption" property of the "taskFlowCapabilities" bean entry.

10. OK the dialog

11. Press the Finish button

45


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.

46


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

47


20. Press the arrow icon and again choose Edit from the displayed menu

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.

48


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.

49


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.

50


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

51


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

52


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

Documents

ADF Hands-On: - Oracle Software Downloads | Oracle ...download.oracle.com/.../TryIt/dynamic-region-hands-on.docx · Web viewThe static region configuration points the ADF Region binding,