As Published In
Oracle Magazine
January/February 2009

DEVELOPER: Frameworks

Easier Interactive Data Entry

By Steve Muench 

Improve the end-user experience with declarative LOVs and automatic partial page refresh.

This column shows you two new features in Oracle Application Development Framework (Oracle ADF) 11g that make data entry easier and more efficient for end users. You’ll configure a declarative list of values (LOV) with an autocompletion feature (similar to what you may have used in Oracle Forms). In the process, you’ll see how the automatic partial page refresh (auto-PPR) capability simplifies delivery of interactive pages that automatically update to reflect changed data.

To begin, download the starter workspace and ensure that you’re using the studio edition of the Oracle JDeveloper (production) release, available as a free download on Oracle Technology Network (OTN). Start by extracting the contents of the file and opening the FrameworksJanFeb2009.jws workspace in Oracle JDeveloper. The Model project in the workspace defines an Emp entity object; EmpView and EmployeeList view objects; and an HRModule application module with a view instance, named Employees , of type EmpView.

By following the steps in this column, you’ll complete the EditEmployees.jspx page in the ViewController project. This page will feature an interactive input field with autocomplete LOV functionality. 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. If you need to create the tables in SCOTT, use the provided CreateDeptEmpTables.sql script.

Adding Reference Information to a View Object

End users often find it helpful to see reference information related to numerical foreign key values. As an example, I’ll show you how easy it is to pull in the name and salary of an employee’s manager for reference.

Start by double-clicking the EmpView view object in the Application Navigator to open the View Object Editor. Select the Entity Objects page, and note that this view object currently includes employee information from a single Emp entity usage. Select the Attributes page, and note that it includes the Mgr attribute, which represents the employee ID of the current employee’s manager but doesn’t include this manager’s name. Back on the Entity Objects page, select the Emp entity object from the Available list. Click the Add arrow button to add a second entity usage to the view object—you’ll use it to show reference information about each employee’s manager. With the newly added Emp1 entity usage highlighted in the Selected list, change the alias below to Manager to reflect the role the second entity usage plays in this query. Note that the Reference box is checked, indicating that attributes from this entity usage will be treated as reference information and automatically kept in sync when the foreign-key value ( Mgr ) changes. The Association and Source Usage lists confirm that the association named Manages relates the Emp entity usage to the Manager entity usage.

Next you choose which attributes related to the manager will appear in the query. Select the Attributes page in the View Object Editor, and click Add from Entity . Hold down the Ctrl key, and in the Attributes dialog box, select the Ename and Sal attributes, indented under the Manager entity usage in the Available list; then click the Add arrow button to add both attributes to the Selected list. Note that the manager’s Empno was automatically added as well, because Oracle ADF requires the primary-key attribute for each entity usage in the view object to appear in the Selected list. Click OK to return to the Attributes page.

Note that Oracle JDeveloper added the number 1 to the end of the new attribute names to make them unique. Now let’s change them to more-meaningful names. Right-click the Ename1 attribute in the Attributes table, and select Rename . When the Rename Ename1 dialog box appears, enter MgrEname as the new name and click OK . Repeat these steps to rename Sal1 to MgrSal and to rename Empno1 to MgrEmpno.

The MgrEmpno attribute duplicates the information in the base employee’s Mgr attribute, so you’ll mark MgrEmpno as hidden so that it won’t appear in the user interface. To do this, first ensure that the Property Inspector is displayed. (If necessary, select View -> Property Inspector to make it appear.) Then, in the View Object Editor, select MgrEmpno from the Attributes table and expand the UI Hints section of the Property Inspector to reveal the Display Hint property. Use the list to set this property’s value to Hide . Later, when you create the edit form for this EmpView, you’ll notice that the MgrEmpno attribute doesn’t appear on the page.

Next, you add a calculated attribute that shows how the salary of an employee compares to the salary of that person’s manager. In the View Object Editor, at the top of the Attributes page, click the green plus ( + ) sign to add a new attribute. For the new attribute’s name, enter PercentOfManagerSal; for its type, select Number ; and for its value type, select Expression . Enter the Groovy expression (MgrSal==null||Sal==null)?null:Sal/MgrSal for its Value property, uncheck the Queryable box, and then click OK.

Your next step is to double-click the PercentOfManagerSal attribute in the Attributes table. When the Attribute Editor dialog box appears, select Dependencies , Ctrl-select Mgr and Sal from the Available list, and click the Add arrow button to shuttle them into the Selected list. This information is used at runtime to recalculate the PercentOfManagerSal attribute automatically whenever Mgr or Sal changes. Select Control Hints in the dialog box, set Format Type to Number , and enter ###.#% for Format Mask . Click OK.

Defining the LOV on a Reference Attribute

Next you define an LOV for the MgrName attribute. Because the manager name and salary are related to an entity usage that’s marked as reference information, these attributes are read-only. However, Oracle ADF still lets you define an LOV on MgrName so the end user can use the more meaningful employee name to look up the appropriate manager. Such an LOV requires an additional return item to be defined to return the selected manager’s Empno value into the current employee’s Mgr attribute; as you’ll see shortly, Oracle JDeveloper automates this task.

In the View Object Editor, select the MgrEname attribute from the Attributes table and click the green + sign in the List of Values: MgrEname section below. When the List of Values dialog box appears, note that the list for List Data Source is empty. Click the green + sign to the right of this list to define a new view accessor that will provide the valid choices for the LOV. When the View Accessors dialog box appears, select EmployeeList from the Available View Objects list, click the Add Instance arrow button to shuttle the selection to the View Accessors list, and then click OK . Back in the List of Values dialog box, ensure that Employeelist1 is selected for List Data Source and select Ename from the List Attribute list. Note that in the List Return Values section below, Oracle JDeveloper has automatically added an extra return value to assign the Mgr attribute in the view object the Empno value from the employee selected in the LOV.

Next you configure the type of LOV you’d like to see in the user interface. In the List of Values dialog box, click the UI Hints tab and set Default List Type to Input Text with List of Values . This choice corresponds to an input field with a button for displaying the List of Values dialog box so users can search for the name of a particular manager. This type of component is appropriate when the list of valid values is long and users would find it convenient to search for their choice. In the Display Attributes section, select Ename from the Available list and click the Add arrow button to shuttle it into the Selected list. Repeat to add the Deptno attribute to the Selected list.

The List of Values dialog box includes an Include Search Region list, whose default is All Queryable Attributes . Although this choice can provide flexible search options for end users, the number of attributes can be overwhelming in many cases. Typically, only a few attributes are useful for the user to search on in an LOV. To control which attributes appear in the LOV’s search region, you can define a view criteria on the view object used for your LOV datasource and select that criteria from the Include Search Region list. The EmployeeList view object in the example project has a view criteria named ManagerLOVSearch , which includes only the Empno, Ename, Job , and Deptno attributes. Select Use ManagerLOVSearch from the Include Search Region list. The Query List Automatically box controls whether or not the LOV dialog box will initially display queried rows. Leave that box unchecked, so users can enter some search criteria before performing a query to find a manager. Click OK to complete the LOV definition.

Configuring the LOV for Autocompletion

Next you build a data entry form for employees and then configure its MgrName LOV field to enable autocompletion. In the ViewController project, double-click the EditEmployees.jspx page to open it in the visual editor. Expand the Data Controls section in the Application Navigator, and expand the HRModuleDataControl node. Drag the Employees data collection, and drop it onto the EditEmployees .jspx page (in the editor). When the Create menu appears, choose Forms -> ADF Form . In the Edit Form Fields dialog box, note that the hidden MgrEmpno field is left out of the list of components to create and that the Component to Use column shows that an ADF List of Values Input component will be used for the MgrEname attribute. Check the Include Navigation Controls box, and click OK to create the form.

To add a Commit button so that users can save their changes, expand the HRModuleDataControl data control’s Operations folder, drag the Commit operation into the Panel Group Layout area containing the navigation buttons, and drop it to the right of the Last button. When the Create menu appears, choose Operations -> ADF Button . Repeat the preceding step to drop a Rollback operation as a Rollback button. To ensure that the Commit and Rollback buttons are never disabled, set their Disabled property to false : Hold down the Ctrl key, and select both the Commit and the Rollback buttons. Expand the Property Inspector’s Behavior section, click the down-pointing arrow to the right of the Disabled property, and choose Reset to Default.

The MgrEname LOV will perform autocompletion only when the component’s AutoSubmit property is set to true , so you’ll configure that next. Select the inputListOfValues component on the page. (It looks like a text field with a magnifying glass icon to the right.) In the Property Inspector, expand the Behavior category and set the AutoSubmit property to true . In the same way, set the AutoSubmit property to true for the Mgr and Sal input fields.

Now right-click EditEmployees.jspx in the Application Navigator and choose Run . Because the data is sorted by Empno value, the employee in the first row that appears when the page appears in your browser should be SMITH, whose manager is FORD. If you update the value of the Mgr attribute to 7839 and tab out of the field, note that the reference information for MgrEname (KING) and MgrSal (5000) will automatically be updated on the page. Also note that the calculated attribute for the percentage of the manager’s salary updates to reflect the percentage of KING’s salary. 

Next Steps

 READ more Frameworks

 READ more about Oracle JDeveloper and Oracle Application Development Framework

Oracle Fusion Middleware

 Oracle Fusion Developer’s Guide for Oracle ADF 11g

Oracle JDeveloper 11g
starter workspace for this column

Click the magnifying glass icon to the right of the MgrEname field to open the LOV dialog box. To search for a manager, enter manager in the Job field in the Search region and click Search . Select the row for CLARK in the table, and click OK . Again, note how the LOV’s return-item definitions ensure that the Mgr field is set to reflect CLARK’s employee ID and that the reference information for this new Mgr value is updated, in turn, to reflect CLARK’s MgrSal and MgrEname values. Again, the PercentOfManagerSal calculated field is updated to reflect the new percentage. Next, erase the CLARK value for the MgrEname field, type BL into the field, and press the Tab key. Because only a single employee has an Ename value starting with BL, the MgrEname field changes to BLAKE and all the related fields are updated. Finally, if you change the current employee’s salary from 800 to some other nonzero value and press the Tab key, the percent-of-manager-salary calculation will immediately be reflected again. You’ve built this slick, interactive data entry form completely declaratively.

Seeing Data Changes Reflected Automatically

In this example, Oracle ADF changes the MgrEname and MgrSal values when the new Mgr foreign-key value is either entered directly or selected from the LOV. The Groovy-calculated attribute is also recalculated when either the Sal or the Mgr attribute changes, thanks to the attribute dependency information you configured for the PercentOfManagerSal attribute.

In earlier Oracle JDeveloper/Oracle ADF releases, you could achieve interactive partial page refreshes of this type only by manually configuring the PartialTriggers property for the components you knew required refreshing. To configure that property, you needed to understand and remember all the possible ways back-end business logic might trigger a change in other attributes’ values—a configuration headache for all but the simplest kinds of pages.

Oracle ADF 11g’s new auto-PPR feature relegates such drudgery to the past. To enable it, you must set a single property on the iterator binding in the page definition where you want it to take effect. To see the property, click the Bindings tab at the bottom of the visual editor for the EditEmployees.jspx page. Select the EmployeesIterator binding in the Executables box, and expand the Property Inspector’s Advanced section. In the Active Events group at the bottom, note that the value of the ChangeEventPolicy property is set to ppr . In some cases, such as when you add navigation buttons to a form, Oracle JDeveloper design time automatically configures this property for you. In other situations, you need to set it yourself on the iterators where you want the feature to take effect.

With the new capabilities you’ve learned about in this column, you’ll soon be building data entry pages that are even more attractive and functional. For more information, see Section 5.11, “Working with List of Values (LOV) in View Object Attributes,” in Oracle Fusion Developer’s Guide for Oracle ADF 11g .

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