25
1 ADF Hands-On Contextual Events Abstract: Contextual Events is an ADF Framework feature that allows developer to etsablish communication between two independent ADF Region. In this hands-on you create a contextual event between a region displaying a DVT graph component and a region displaying a table. You will set up the contextual event manually on the binding layer and also write some Java code that helps preserving the default click behavior on the graph. Duration: 45 minutes 2010 / 2011 ADF Internal Enterprise 2.0 Training

Contextual Events Hands On

Embed Size (px)

Citation preview

Page 1: Contextual Events Hands On

1

ADF Hands-On Contextual Events

Abstract:

Contextual Events is an ADF Framework feature that

allows developer to etsablish communication between two

independent ADF Region. In this hands-on you create a

contextual event between a region displaying a DVT

graph component and a region displaying a table. You will

set up the contextual event manually on the binding layer

and also write some Java code that helps preserving the

default click behavior on the graph.

Duration: 45 minutes

2010 / 2011 ADF Internal Enterprise 2.0 Training

Page 2: Contextual Events Hands On

2

ADF HANDS-ON Contextual Events

IntroductionThe contextual events framework in Oracle ADF defines a publish / subscribe mechanism that

leverages the ADF binding layer to notify ADF Regions about user interaction performed in other

regions, the parent page or a ViewPort (page fragment). Oracle JDeveloper provides declarative

help to setup contextual events for input and action components, but not yet for DVT components

like graphs. Setting up a data visualization component (DVT) to publish contextual events is more

challenging than from an input text field or a table, but it is a good use case to understand how

contextual events work. 

The image below shows the application you build in this hands-on. The DVT graph component is

selectable and allows users to click on the graph bars. Clicking on a bar does set the current row

on the underlying ADF binding, making sure the read only form displays the detail information for

the selected bar. At the same time, a contextual event is raised and published to the ADF Region

containing the employee table. The contextual event payload allows a managed bean to access

the selected department Id and query the business service for employees working in it.

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.

Page 3: Contextual Events Hands On

3

ADF HANDS-ON Contextual Events

The Oracle JDeveloper 11g starter workspace is contained in the ContextualEvent.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 ContextualEvent| ContextualEvent.jws

To change the RDBMS connection, select View | Database | Database Navigator from the Oracle JDeveloper menu. Select the database connection node in the "ContextualEvent" node and use the right mouse context menu to edit its properties and change the connect information.

Setting up Contextual Events between two Regions

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 as it 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 two collections (View Objects) to query a list of departments and employees. The employee list is filtered by a View Criteria that reads the department Id from a bind variable.

To shorten the time it takes to build the hands-on sample, the two bounded task flows and managed beans were pre-created. In addition, a Java class is provided

Page 4: Contextual Events Hands On

4

ADF HANDS-ON Contextual Events

in the adf.sample.view.ctx package that receives and handles the event broadcasted by the event producer.

In the first section of this hands-on, you set up the contextual event producer, consumer and the event mapping. In the second part, you go advanced and invoke the contextual event from Java.

1. Expand the adf.sample.view.pageDef package and select the BrowseDepartmentsPagedef.xml file, which is the ADF binding file of the page fragment containing the DVT graph component. The ADF binding file will become the event producer

2. Open the Structure Window (ctrl+shift+S)

3. Select the "bindings" node and choose Insert inside bindings | Generic Bindings | eventBinding to create a new ADF event entry

Page 5: Contextual Events Hands On

5

ADF HANDS-ON Contextual Events

4. Select the eventBinding entry you just created and choose Insert inside eventBinding | events from the context menu. An event binding can contain multiple events that can be mapped to different event consumers.

5. Select the "events" node and use the right mouse to open the context menu

6. Choose Insert inside events | event from the menu to create a new event item

7. Type "ChartEvent" as the event name into the opened dialog

Page 6: Contextual Events Hands On

6

ADF HANDS-ON Contextual Events

8. Open the Property Inspector with the "ChartEvent" event selected in the Structure Window. The event properties include "customPayLoad" and "raiseCondition".

The "customPayLoad" property allows developers to pass information other than what is contained in the event object to the event handler. The custom payload data can be read from the binding layer, a managed bean or a memory scope using Expression Language.

The "raiseCondition" provides control over when the event should be broadcasted to avoid unnecessary and unwanted invocations.

9. Select the "eventBinding" node

10. The "id" property is accessible from EL and Java, as we show later. For now, just set it to "ChartDrillEvent"

11. In the "Listener" property field, type

oracle.adf.view.faces.bi.event.ClickListener

It’s the listener class that matches the click event of the DVT component that is used in this hands-on to invoke the contextual event producer

Page 7: Contextual Events Hands On

7

ADF HANDS-ON Contextual Events

12. To configure the contextual event consumer, expand the adf.sample.view.ctx.handler package in the JDeveloper Application Navigator

13. Select the "ContextualEventHandler.java" file and choose "Create Data Control" from the right mouse context menu.

Contextual events are ADF binding events, which mean that event producers and event receivers must be exposed on the ADF binding. To do so for the event handler, it must be exposed by a Data Control, the JavaBean Data Control in this case

Page 8: Contextual Events Hands On

8

ADF HANDS-ON Contextual Events

14. After the DataControl configuration is generated by Oracle JDeveloper, double click the ContextualEventHandler.java file to open it

15. The handleEvent(Object payload) method received the click event broadcasted by the contextual events. At runtime, the class is loaded in the context of the employees task flow and therefore has access to the managed beans defined on this task flow. It uses this reference to invoke a method on the "employeeBackingBean" to re-query and refresh the employees table.

16. Select the "BrowseEmployeesPageDef.xml" file in the adf.sample.view.pageDef package.

17. Open the Structure Window (ctrl+shift+S)

18. Select the "bindings" node and choose Insert inside bindings | Generic Bindings | method Action from the right mouse context menu

Page 9: Contextual Events Hands On

9

ADF HANDS-ON Contextual Events

19. Select the "ContextualEventHandler" Data Control.

20. Ensure the "handleEvent(Object)" method is selected

21. Press "Ok"

Page 10: Contextual Events Hands On

10

ADF HANDS-ON Contextual Events

22. Double click onto the "ParentContainer.jspx"

23. Drag the "dvt-task-flow-definition.xml" task flow from the Application Navigator and drop it into the first facet of the Panel Splitter component in the ParentContainer.jspx file

Page 11: Contextual Events Hands On

11

ADF HANDS-ON Contextual Events

24. In the opened menu, select "Region" to create a static ADF Region

25. Drag the "employees-task-flow-definition.xml" task flow from the Application Navigator and drop it into the second facet of the Panel Collection in the PanelContainer.jspx file

26. Select "Region" in the opened context menu to create a static ADF Region

27. The employees task flow requires an input parameter for the initial query of the employees. Click into the parameter field …

Page 12: Contextual Events Hands On

12

ADF HANDS-ON Contextual Events

28. … and type 10

29. Press OK. When the task flow loads the first time, its page fragment shows a list of employees working in department 10

Page 13: Contextual Events Hands On

13

ADF HANDS-ON Contextual Events

30. Select the ParentContainerPageDef.xml file in the adf.sample.view.pageDefs package

31. Open the Structure Window

32. Select the top node entry and choose Insert inside ParentContainerDef | eventMap from the right mouse context menu. This creates the ADF binding entry to map the event produces with the event receiver

Page 14: Contextual Events Hands On

14

ADF HANDS-ON Contextual Events

33. Select the ParentContainerDef root entry again and choose "Edit Event Map" from the right mouse context menu

33. In the opened Event Map Editor, press the green plus icon to create a new event mapping

34. Expand the producer list box

Page 15: Contextual Events Hands On

15

ADF HANDS-ON Contextual Events

35. Select the BrowseDepartmentsPageDef.ChartDrillEvent entry and double click on it to close the list

Page 16: Contextual Events Hands On

16

ADF HANDS-ON Contextual Events

36. The Event Name is automatically added as there is only a single event defined in this binding

37. Expand the Consumer list and select the "BrowseEmployeesPagedef.handleEvent" entry

38. Press the green plus icon to create a new entry in the Consumer Params

39. Define a new parameter with the Param Name payload and the Param Value ${payLoad}. Note that the parameter name "payload" matches the name of the argument in the event handler method. The ${payload} EL access the event message, which is the event object if no custom payload was defined.

Page 17: Contextual Events Hands On

17

ADF HANDS-ON Contextual Events

40. Press Ok to close the dialog

41. Press OK to finish the event mapping configuration

Page 18: Contextual Events Hands On

18

ADF HANDS-ON Contextual Events

42. Select the DVT graph component in the BrowseDepartments.jsff page fragment. You can do this in the visual page editor as shown below, or in the Structure Window after selecting the page fragment

43. Open the Property Inspector (ctrl+shift+I)

44. In the Property Inspector, note the current Expression Language string added to the "ClickListener". When creating a DVT component graph, you can check a checkbox to make a click on a bar in the graph to mark the underlying row as selected in the ADF binding. In response to checking the check box, the EL string is added to the Click Listener property.

45. Select the Expression Language string as shown in the image below and copy it into the clipboard for later use. To invoke a contextual event in response to a user clicking onto a bar in the graph, while preserving the configured behavior to mark the underlying row as current in the binding, you will replace the EL string with a managed bean method reference.

Page 19: Contextual Events Hands On

19

ADF HANDS-ON Contextual Events

46. Click the arrow icon next to the "ClickListener" property field and choose "Edit" from the context menu.

47. Select the departmentBackingBean entry

Page 20: Contextual Events Hands On

20

ADF HANDS-ON Contextual Events

48. Press the "New" button to create a new managed bean method to handle the DVT click event

49. Name the method as "onGraphClick"

50. Press OK twice

51. Double click onto the DepartmentBackingBean.java file to open it in the code editor.

Page 21: Contextual Events Hands On

21

ADF HANDS-ON Contextual Events

52. To preserve the default behavior, use the EL you saved to the clipboard and invoke it from Java. For this type the following code into the "onGraphClick" method body

invokeDefaultClickEvent( "#{bindings.allDepartmentsWithEmployees.graphModel.processClick}",

clickEvent);

53. Next, add code to invoke the contextual event

Page 22: Contextual Events Hands On

22

ADF HANDS-ON Contextual Events

54. Type or copy the following code lines into the method

BindingContext bctx = BindingContext.getCurrent();BindingContainer bindings = bctx.getCurrentBindingsEntry();JUEventBinding eventBinding = null;//get a handle to the eventBindingeventBinding = (JUEventBinding) bindings.get("ChartDrillEvent");ClickListener cl = (ClickListener)eventBinding.getListener();cl.processClick(clickEvent);

Note: Oracle JDeveloper needs to import classes for the code to work. Either manually import the classes, or copy and paste the following lines to the top of the Java file (but still below the package name)

import oracle.adf.model.BindingContext;import oracle.adf.view.faces.bi.event.ClickListener;import oracle.binding.BindingContainer;import oracle.jbo.uicli.binding.JUEventBinding;

The code lines above access the ADF Binding Context to access the Binding Container at runtime. It then looks up the "ChartDrillEvent" binding to access and invoke the ClickListener

55. Select the PageContainer.jspx file and choose "Run" from the right mouse context menu

Page 23: Contextual Events Hands On

23

ADF HANDS-ON Contextual Events

56. In the opened page, click onto a graph bar and watch the read only form and the table refreshing.

RELATED DOCOMENTATION