As Published In

Oracle Magazine
July/August 2010

TECHNOLOGY: Frameworks

Compelling Dialog

By Steve Muench Oracle Employee ACE

Call bounded task flows as inline pop-ups.

Two of the more interesting new features in the 11g release of Oracle Application Development Framework (Oracle ADF) are task flows and the ability to easily create inline dialog boxes. Prior to the 11.1.1.2 production maintenance release, however, combining these two features was tedious and error-prone. In this column, you’ll see how simple it is to invoke a bounded task flow in an inline dialog box. This column assumes that you have downloaded the starter workspace and that you will follow along by using the Studio Edition of the Oracle JDeveloper 11.1.1.2 production release, available as a free download at oracle.com/technetwork/jdev on Oracle Technology Network. After extracting the contents of the o40frame.zip file, open the FrameworksJulAug2010.jws workspace in Oracle JDeveloper.

Before proceeding, adjust the properties of the connection named scott in the Application Resources zone of the Application Navigator until you can successfully test a connection to a SCOTT schema. Run the provided CreateDeptEmpTables.sql script in the Model project to create the necessary tables and sequence that the example requires. To find the script, expand the Application Sources folder in the Model project of the Application Navigator. To run the script, start by double-clicking the file to open it in the editor. Then, along the bottom left side of the editor window, click the SQL Worksheet tab. Use the list (with the database “can” icon) in the upper right corner of the editor to select the scott (FrameworksJulAug2010) connection. Finally, click the “Run Script” editor toolbar icon (the second from the left).

Overview

The example includes a manage-employees bounded task flow that calls an employee-details bounded task flow to handle viewing, editing, and creating an employee. The employee-details task flow is similar to the one built in the September/October 2008 Frameworks column (“Task and You Shall Receive”), in that it uses a required mode parameter with an acceptable set of values. In this column’s project, the value must be “create,” “view,” or “edit.” In addition, it accepts an empno parameter that provides the ID of the employee to view or edit. (See the September/October 2008 Frameworks column for more information about bounded versus unbounded task flows, if necessary.)

Start by running the application to familiarize yourself with its basic functionality. Right-click the ViewController project, and choose Run . When the home page appears, click the Manage Employees link to start the manage-employees task flow. When the Manage Employees page appears, select an employee in the table and click the View link in the selected row to view the employee details. This calls the employee-details task flow, passing “view” for the value of the mode parameter. Click OK to return to the Manage Employees page.

If you click the Edit link next to a selected employee in the table, the task flow will be called in edit mode and you can modify the employee data. To create a new employee, click the New Employee button. This calls the same task flow in create mode. Enter the details of a new employee, and click OK .

Note that in all three cases, the page of the called task flow replaces the calling page in the browser and the calling page is restored when the task flow completes or you cancel and return from the called task flow. By following the steps in this column, you’ll see how easy it is to render a called task flow as an inline dialog box rather than completely replacing the current page. As shown in Figure 1, with this technique in your application, your end users will see the calling page in the background as they interact with the related information in the pop-up dialog box.

 

figure 1
Figure 1: An inline dialog box bounded task flow

Calling a Task Flow in a Dialog Box

Start by opening the manage-employees task flow in the editor. To do this, expand the Page Flows folder inside the Web Content folder of the ViewController project in the Application Navigator and double-click the manage-employees node. Select the employee-details task flow call activity in the diagram. Note that the employee-details task flow icon looks like a Web page linked to another Web page. Show this activity’s properties by choosing View -> Property Inspector from the Oracle JDeveloper main menu. In the Behavior section, set the Run as Dialog property to true and set the Display Type property to inline-popup. As you change these settings, observe the icon on the task flow call activity as it changes from a Web page to a dialog box. This gives you visual feedback that the called task flow will appear in a pop-up dialog box at runtime.

Next, double-click the manageEmployees view activity in the diagram to open the page in the visual editor. You’ll need to perform the same few configuration steps for each command component that calls the task flow, which, in our example, consists of one button and two links. Start by selecting the New Employee button. In the Behavior section of the Property Inspector, set the Partial Submit property to true . This ensures that the calling page will not “flicker” or repaint when calling the task flow in a pop-up dialog box.

Next, lower in the Behavior section, find the Secondary Window group of properties and set Use Window to true, Window Embed Style to inlineDocument , and Window Modality Type to applicationModal . These three settings configure the button to open the called task flow in an inline pop-up dialog box that will be modal with respect to the calling page. This means that users must dismiss the pop-up dialog box before they’ll be able to interact again with the calling page. Set the Window Height property to 210 and Window Width to 210 . Repeat these configuration steps for the View link and the Edit link in the Actions column of the table.

Configuring Return Values

Sometimes you will find it useful to have a called task flow return information to the calling task flow. For example, in a later step in this article, you will display a confirmation message to the user, indicating the employee number of a newly created employee returned from the called task flow. Accomplishing this task will be a two-step process. In this section, you will configure the employee-details task flow to have a return parameter. Then, in the next section, you will reference the value of the return parameter in a “return listener” event handler in the calling page.

Start by double-clicking the employee-details task flow in the Application Navigator to open it in the editor. At the bottom left side of the editor, click the Overview tab to see the task flow overview. On the Parameters page, click the green plus ( + ) icon in the Return Value Definitions section to add a row to the table and define a named return value. In the new row, double-click in the Name column to edit the name of the return value. Change the name to empnoReturned . In the Class column, enter oracle.jbo.domain.Number to define the type of the return value, and in the Value column, enter the expression language (EL) expression #{pageFlowScope.empno} , and press Enter. This defines a named return parameter whose value will be calculated by evaluation of the supplied EL expression before the task flow is exited. Given the expression you’ve entered, the return parameter will be equal to the value of the empno attribute in the page flow scope at the time the task flow completes.

Next you’ll configure the setPropertyListener component on each of the two buttons on the employeeDetails.jspx page in the employee-details task flow to copy a value into the empno attribute in the page flow scope before the task flow is exited. Click back on the Diagram tab in the lower left corner of the editor to see the task flow diagram again. Double-click the employeeDetails view activity to open the page in the editor. Right-click the OK button, and choose Insert inside Button -> OK -> ADF Faces . In the Insert ADF Faces Item dialog box, select Set Property Listener and click OK . In the Insert Set Property Listener dialog box, in the From field, enter the #{bindings.Empno.inputValue} EL expression; in the To field, enter the #{pageFlowScope.empno} expression; and set the Type to action. This step declaratively assigns the current value of the empno attribute to the page flow scope attribute named empno. Click OK to complete the listener you’ve configured.

 

Next Steps

 READ more Frameworks
 

READ more about
Oracle JDeveloper and Oracle ADF
 oracle.com/technetwork/products/jdev

 oracle.com/technetwork/products/jdev/tips/muench/designpatterns
 Oracle Fusion Middleware Fusion Developer’s Guide for Oracle Application Development Framework 11g

Oracle Fusion Middleware
 oracle.com/technetwork/documentation

DOWNLOAD
 Oracle JDeveloper 11g
 the starter workspace for this column

Repeat these steps to insert a setPropertyListener component inside the Cancel button, using the same #{pageFlowScope.empno} EL expression for the To field and the same action setting for the Type field, but set the From field to the expression #{null} and click OK to create the listener. This will assign the “null” value to the page flow scoped attribute named empno when the user clicks Cancel . You’ll use this null return value as a signal that the user canceled the dialog box.

Implementing a Return Listener

On a page that launches a task flow in a dialog box, you can reference the value of one task flow return parameter as the dialog box return value. You will typically configure this for each command component that launches a task flow as a dialog box. To do this, start by configuring the task flow call activity to select the task flow return parameter that will provide the dialog box return value. Activate the manage-employees task flow editor tab again, and select the employee-details task flow call activity. In the Behavior section of the Property Inspector, set Dialog Return Value to empnoReturned , the name of the return parameter you defined in the previous step.

The next step is to configure an event handler in a backing bean that will fire when the dialog box returns. You accomplish this by setting the returnListener property of the command component (button/link) that launches the dialog box. Activate the editor for the manageEmployees.jspx page, and then select the New Employee button. In the Behavior section of the Property Inspector, click the down-arrow to the right of the returnListener property and choose Edit . When the Edit Property: Return Listener dialog box appears, choose the ManageEmployees managed bean from the Managed Bean list. (This bean was configured ahead of time as part of the starter project.)

To define a new event handler method in this bean, click the New button to the right of the Method list. When the Create Method dialog box appears, enter afterNewEmployeeDialog as the method name, click OK , and then click OK again. To go to the backing bean class where the event handler method was created, right-click the New Employee button and choose Go to -> ManageEmployeesPage.java . Inside the afterNewEmployeeDialog() method, at the end of the file, add the following code: 

Number returnValue = 
(Number)returnEvent.getReturnValue();
if (returnValue != null) {
  showMessage("New employee 
"+returnValue+" created.");
}
repaintTableAndMessageBox();

The first two lines retrieve the dialog box return value from the dialog box return event object. As you configured it above, this value will reflect either the employee ID of the new employee created or “null” if the user canceled the dialog box. The next three lines conditionally invoke the showMessage() helper method and display a confirmation message on the page if the user did not cancel the dialog box. The last line invokes a helper method to cause the employees table and message box UI components to repaint in the browser to reflect the latest data.

Repeat the steps above to create an afterEditEmployeeDialog return listener event handler for the Edit link on the page, but with an appropriate confirmation message, such as 

showMessage("Employee "+ returnValue +" updated."); 

The completed settings look like those in Figure 2. To test the application, right-click the ViewController project and choose Run again.
 

figure 2
Figure 2: The afterNewEmployeeDialog and afterEditEmployeeDialog methods

You can see that with minimal work, you’re now employing an attractive pop-up dialog box for viewing, editing, and creating employees. As you begin to experiment with using this technique in your own applications, keep in mind that for a bounded task flow to run as a dialog box, it must comprise complete JSPX pages rather than page fragments. If you have already built your task flow with fragments, not to worry: you can convert it to a bounded task flow with pages, using the handy Convert to Task Flow With Pages option on the task flow diagram’s right-mouse context menu.

 


Steve Muench
Steve Muench is a consulting product manager for Oracle JDeveloper. He has developed and supported Oracle tools and XML technologies since 1990 and continues to evangelize them. Muench coauthored Oracle ADF Developer’s Guide for Forms/4GL Developers (Oracle, 2006), wrote Building Oracle XML Applications (O’Reilly Media, 2000), and shares tips and tricks on Oracle Technology Network ( oracle.com/technetwork ) and in his Dive into ADF blog ( blogs.oracle.com/smuenchadf ).

Send us your comments