As Published In
Oracle Magazine
November/December 2008

DEVELOPER: Frameworks


Developing a Regional Accent

By Steve Muench Oracle ACE

Use task flows as regions to improve UI reuse.

My last column (“Task and You Shall Receive,” in the September/October 2008 issue) examined the basics of the new task flow feature in Oracle JDeveloper and Oracle Application Development Framework (Oracle ADF) 11g, which lets you assemble complex UIs from simpler units. I discussed two basic types of task flows: bounded , when the task flow behaves like an encapsulated function call, and unbounded , when users can start at any page in the flow. Each view activity I demonstrated last time corresponded to a distinct JavaServer Faces (JSF) page, resulting in a more powerful, declarative way to sequence pages and application logic.

In this column, I’ll show you how to create reusable UI components called regions . Think of regions as components with view activities that represent only a fragment of a JSF page and whose visual contents and runtime behavior are determined by a bounded task flow. Then I’ll show how easy it is to reuse a region, embedding it in the contents of another page. By the end, you’ll appreciate how this capability enables you to create reusable UI components using the full declarative functionality of task flows.

To begin, download the starter workspace and ensure that you’re using the Oracle JDeveloper 11.1.1.0 (production) release, available as a free download on Oracle Technology Network (OTN). Start by extracting the contents of the o68frame.zip file and opening the FrameworksNovDec2008.jws workspace in Oracle JDeveloper. The Model project in the workspace defines an Emp entity object, an EmpView view object, and an HRModule application module with a view instance named Employees. The ViewController project contains a BrowseEmployees.jspx page whose af:panelStretchLayout component contains an af:table in its left facet, showing employee numbers and names. Before proceeding, adjust the properties of the connection named scott in the Application Resources zone of the Oracle JDeveloper Application Navigator until you can successfully test a connection to a SCOTT schema. If you need to create the tables, use the provided CreateDeptEmpTables.sql script.

The steps in this column will enable you to create a Show Employee Details region and drop it into the center facet of this page to reuse it. The final application will allow you to select an employee from the table and display the corresponding details for that employee in the new task flow region.

Creating a Bounded Task Flow of Page Fragments

In the last column, we configured a few task flows that already existed in the starter project, so this time let’s walk step by step through creating a new task flow, adding view and method activities, configuring input parameters, and marking a default activity. Although the example is intentionally simple, it will nonetheless familiarize you with all the key concepts you need to know to create your own reusable regions. Task flows that are destined to be reused as embeddable regions must be bounded and must comprise JSF page fragments, because at runtime their contents become a part of the page (or other fragment) that contains them. So let’s start by creating a new bounded task flow.

With the sample workspace, FrameworksNovDec2008.jws, open in the Application Navigator, right-click the ViewController project and choose New... . In the New Gallery dialog box that appears, select Web Tier -> JSF and then double-click ADF Task Flow . When the Create Task Flow dialog box appears, enter show-emp-details.xml as the filename, leaving the default settings for the other fields. Note that the check boxes for Create as Bounded Task Flow and Create with Page Fragments are checked by default. These are the precise options required to create a region. Click OK to create the new task flow. Oracle JDeveloper opens the visual editor for this new task flow and displays the Diagram view.

Next, we’ll add the components of our region by dragging them onto the diagram. Drag a view activity from the Component palette and drop it onto the design surface. When the view activity shape appears, type directly on the diagram to change its name from view1 to ShowEmployee . Double-click the ShowEmployee view activity to create its JSF page fragment. When the Create New JSF Page Fragment dialog box appears, accept the default settings and click OK to continue. The visual editor will open for the ShowEmployee .jsff page fragment, showing an empty canvas. Expand the Data Controls section of the Application Navigator as well as HRModuleDataControl , and drag the Employees data collection onto the page. When the Create context menu appears, select Forms -> ADF Read-only Form... . When the Edit Form Fields dialog box appears, click OK to create the form with all of the items.

Next, we’ll enhance the task flow to accept a parameter named Empno and then to look up the employee row to display, based on the value of that Empno parameter. Select the show-emp-details.xml tab to activate the task flow design surface again. With the Property Inspector displayed, click somewhere on the task flow design surface. In the Property Inspector, expand the Parameters section and click the green plus-sign icon to add a new parameter. (You may need to widen the Property Inspector to see the button.) Set the name field to Empno, set the class field to java.lang.Integer , set the value field to #{pageFlowScope.Empno} , and finally check the required check box. The expression language (EL) expression in the value field configures the task flow to store the value of the incoming Empno parameter in the pageFlowScope attribute named Empno , so you can reference its value in any activities inside the task flow.

Performing an Operation Before the Page Renders

We want the completed application to find the employee row to display in the form before the ShowEmployee page fragment renders. To do that, we’ll add a method call activity that precedes the ShowEmployee view activity, with a built-in operation that uses the value of the Empno parameter we just created to look up the employee row. To do this, drag and drop a Method Call activity from the Component palette onto the task flow surface and place it to the left of the ShowEmployee view activity. Type on the diagram icon to change its name from methodCall1 to findEmployeeByEmpno . In the Data Controls palette, expand the Employees data collection and its nested Operations folder to find the setCurrentRowWithKeyValue operation. Drag and drop this built-in operation onto the findEmployeeByEmpno method activity icon in the diagram.

To configure the parameter value that will be passed to the default operation, right-click the new method call activity, findEmployeeByEmpno , and select Edit Binding... . In the Parameters table at the bottom of the Edit Action Binding dialog box, you’ll see the rowKey parameter entry. In the Value column for this parameter, enter the EL expression #{pageFlowScope.Empno} to use the value of the task flow parameter as the value of the primary key for the employee row to display and click OK.

Next we’ll connect the method activity to the view activity so that after executing its logic to find the desired employee row, it will forward control to render the page fragment. Click the Control Flow Case tool in the Component palette. This enables you to use your mouse as a tool to connect one item to another with two consecutive mouse clicks. Immediately click the new method activity first and then the ShowEmployee view activity. The default control flow case name will be setCurrentRowWithKeyValue . Press Enter to accept the default name.

Continue by again selecting the findEmployeeByEmpno activity and note that its fixed-outcome property is set to setCurrentRowWithKeyValue . The fixed-outcome property specifies the name of the navigation case to follow after the method activity completes.

Finally, note that the ShowEmployee view activity has a “halo” of color that surrounds its icon. This identifies it as the default activity in the task flow. Because we want the findEmployeeByEmpno method call activity to execute before the page fragment displays, we need to mark it as the default activity instead. To do this, right-click findEmployeeByEmpno and choose Mark Activity -> Default Activity . The color halo changes accordingly. After you save all your changes, your task flow should look like Figure 1.

 

figure 1
Figure 1: show-emp-details task flow


At this point, it’s useful to step through our application logic as a review of what we’ve done. As the task flow diagram indicates, when the task flow starts, it finds an employee by Empno and then forwards control to render the ShowEmployee page fragment. This is a simple example, and thus we were able to accomplish the page setup logic by using a built-in operation without writing any code, but keep in mind for your own future task flows that a method call activity can invoke a backing bean method if needed for more-complex custom setup processing. In fact, in Oracle ADF 11g, this more flexible, visual method call activity effectively replaces the often misunderstood, often misused invokeAction executable technique for doing page setup logic.

Adding the Task Flow as a Region

Let’s see how easy it is to reuse our task flow as a region in a page. In the ViewController project, expand the Web Content folder to expose the BrowseEmployees.jspx page. Double-click it to open it in the visual editor. Also in the ViewController project, expand the Page Flows subfolder inside the Web Content folder. Drag the show-emp-details task flow that appears there, and drop it into the center facet of the panelStretchLayout component that is already on the page. When the Create context menu appears, select Region . When Edit Task Flow Binding appears, enter the EL expression #{bindings.Employees.Empno} in the Value column for the Empno input parameter and click OK . This expression represents the value of the Empno attribute in the current row of the Employees table binding.

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 ADF Developer’s Guide

DOWNLOAD
Oracle JDeveloper 11g
starter workspace for this column

Run the page to see the result of including the region. To do this, right-click the BrowseEmployees.jspx page in the Application Navigator and click Run . When your browser appears, you’ll see the table of employee numbers and names at the left of the page, with the contents of the reusable show-emp-details region displaying the full details of the first employee to the right of the table. However, if you select a different row in the table, you’ll notice that the region does not update. To enable the update, we need to configure the task flow binding so that the region will refresh whenever the values of its input parameters change.

To accomplish this, right-click in the page and choose Go to Page Definition . In the Structure window, expand the executables folder and select the task flow binding named showempdetails1 . In the Common section of the Property Inspector, set the Refresh property to the value ifNeeded . That’s all that’s necessary to have the region “restart” when the values of its input parameters change. In this case, when a user clicks a different row in the table, the region will update to display the Empno value of the new row. To see it in action, rerun the BrowseEmployees.jspx page, and, when your browser launches, click any row in the table. Because the task flow’s input parameter is bound to the Empno attribute in the current row of the table, the region refreshes to show that row.

I’ve shown you only the simplest-possible region example in this column, but the bounded task flows you reuse as regions can utilize the full power of the Oracle Application Development Framework task flow feature. This means that they can include any combination of task flow activities, including multiple view activities whose “current” page fragment specifies the contents of the region at runtime. This allows great flexibility in creating reusable UI components, simple or complex. You can package them into libraries, which you or another developer on your project team can then drop onto pages wherever necessary.
 



Steve Muench
is a consulting product manager for Oracle JDeveloper and an Oracle ACE. Since 1990 he has developed and supported Oracle tools and XML technologies and continues to evangelize them. Muench coauthored the 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 OTN and in his Dive into ADF blog.

Send us your comments