TECHNOLOGY: Oracle ADF

As Published In
Oracle Magazine
July/August 2011

  

Add Advanced List Interaction

By Frank Nimphius

 

Use model-driven LOVs in Oracle ADF to implement smart lists with autosuggest behavior.

Using lists of values (LOVs) in Oracle Application Development Framework (Oracle ADF) is a great way to prevent end users from entering invalid data. With dependent LOVs, you can further enhance user efficiency by filtering lists on external conditions. This column will show you how the LOV features in Oracle ADF help you build rich, intelligent list and search capabilities without requiring full-blown Java coding.

To begin, download the starter workspace in a zip file called o41adf-359201.zip. Note that it contains two folders, one containing a starter workspace and the other a completed version. Ensure that you’re using the studio edition of the Oracle JDeveloper 11g 11.1.1.4 (or later) release, available as a free download on the Oracle Technology Network. The application uses the HR schema that’s available by default in Oracle Database. 

Sample Application Overview

The biggest challenge in developing LOVs in large enterprise applications is to maintain functional and user interface consistency across pages. Model-driven LOVs help you meet this challenge by enabling you to define an LOV in a single place; any subsequent modifications to the list propagate to all instances of the list. In this example, you’ll see how to use Oracle JDeveloper to create dependent, model-driven LOVs that provide smart lists—filtered lists with default selection values and autosuggest behavior. 

Launch Oracle JDeveloper, and browse to the directory where you unzipped the starter workspace. Open the AdfListOfValues.jws workspace in the AdfListOfValues folder. Before proceeding, adjust the properties of the connection named hrconn in the Application Resources zone of the Application Navigator until you can successfully test a connection to the HR database schema.

The sample workspace contains two projects: Model and ViewController. The Model project contains four view objects: DepartmentsView, JobsView, ManagersView, and EmployeesView. You’ll start by defining LOVs for attributes of the EmployeesView object. The other three view objects provide the data for the lists. The ViewController project contains a single page, SamplePage.jspx, that you’ll use to test the model-driven LOVs in a Web environment. 

Building LOVs for the EmployeesView Object

Double-click the EmployeesView object in the Model project’s adf.oramag.sample.model.vo package to open it in the object editor. Select the Attributes category, and then click DepartmentId in the list of attributes. Click the green plus sign (+) icon next to the List of Values: DepartmentId label to open the Create List of Values dialog box. Click the + sign next to the List Data Source field, and select DepartmentsView from the Available View Objects list. Click the right-pointing shuttle button to move the selected view object to the View Accessors list. Figure 1 shows the updated View Accessors list. (The existing JobsView1 view accessor is from an LOV that is predefined in the sample workspace.) Click OK

o41adf figure 2

Figure 1: Adding a view accessor

From the List Attribute list, choose DepartmentId. That selection automatically completes the List Return Values section so that the DepartmentId value is copied to the EmployeesView object’s DepartmentId.

On the UI Hints tab, perform the following steps to configure the display for the LOV and the component that renders it:

  1. For Default List Type, select Combo Box with List of Values.
  2. Under Display Attributes, shuttle DepartmentName, DepartmentId, and LocationId (in that order) from the Available list to the Selected list.
  3. For Show in Combo Box, select First.
  4. Check the Query List Automatically checkbox.
  5. Check the Filter Combo Box Using option to create a smart list that filters the list of departments to include only the departments that have employees. The filter is based on the DepartmentsWithEmployees view criteria defined for the DepartmentsView view object.

     

    Click OK to save the configuration and return to the ViewEmployees editor.

Figure 2 shows how the LOV you’ve just defined for the DepartmentId attribute will render at runtime. If you want to search in all departments, click Search to launch the Search and Select dialog box. Whenever the DepartmentId attribute is added to any page in the application, the UI will render consistently as shown in Figure 2.

 

o41adf figure 1

Figure 2: LOV for DepartmentID as displayed at runtime
 

The ManagerId LOV you’ll create next is dependent on the DepartmentId value. To synchronize the two attributes, the DepartmentId must issue a partial submit upon value change. With the DepartmentId attribute selected, open the Property Inspector from the Oracle JDeveloper main menu (View -> Property Inspector). In the Property Inspector, expand the UI Hints category and set the Auto Submit property to true. Save the project. 

Building the Dependent LOV for the ManagerId Attribute

The ManagerId attribute should also render as an LOV component at runtime. In the EmployeesView view object editor, select the ManagerId attribute and create an LOV definition as before. In the Create List of Values dialog box, create a new view accessor for List Data Source by clicking the green + and shuttling ManagersView from the Available View Objects list to the View Accessors list. 

Now assign a bind variable value that passes the DepartmentId attribute value to a view criteria that exists on the ManagersView object. Click Edit next to the View Accessors label. In the Edit View Accessor dialog box, enter DepartmentId as the value for the bind parameter, as shown in Figure 3.

 

o41adf figure 3

Figure 3: Adding a bind parameter value
 

You’ll allow users to query all employees who are managers via a Search and Select dialog box. You’ll also provide a smart list to help them find the manager for the current department as referenced in the DepartmentId attribute. The smart list is queried by the value provided for the bind variable. Click OK, and click OK again to close the Edit View Accessor dialog box. Back in the Create List of Values dialog box, select EmployeeId as the value of the List Attribute field. This selection ensures that at runtime the EmployeeId of the selected manager will be assigned as the current employee’s ManagerId value.

Click the UI Hints tab to configure the appearance of the LOV component:

  1. Choose Combo Box with List of Values for Default List Type.
  2. For Display Attributes, shuttle FirstName, LastName, Email, and DepartmentId (in that order) from the Available list to the Selected list.
  3. For Show in Combo Box, select First and 2 (indicating that the first two attributes will appear in the smart list).
  4. Check the Query List Automatically checkbox.
  5. Check the Filter Combo Box Using option, which automatically selects the ManagerInDepartment view criteria defined for ManagersView. Click OK to close the dialog box.
At runtime, the dependent smart list shows the manager for the selected DepartmentId. To query all managers, users click the Search link, as shown in Figure 4.

 

o41adf figure 4

Figure 4: Querying all managers
 

Congratulations—you’ve created an LOV with a dependent smart list.

Building the Oracle ADF Faces Form for Testing

Now you’ll build a Web page for testing the application. In the Application Navigator, expand the ViewController project; right-click the SamplePage.jspx file, in the Web Content folder; and choose Open. Open the Data Controls accordion panel in the Application Navigator, and expand AppModuleDataControl. Drag the allEmployees collection from the Data Controls panel, and drop it as Form -> ADF Form onto the visual page editor. In the Edit Form Fields dialog box, check the checkboxes to create navigation controls and to add a submit button; click OK

Next Steps


READ more about
 Oracle ADF
 Oracle Fusion Middleware Fusion Developer’s Guide for Oracle Application Development Framework 11g Release 1 (11.1.1.4.0)
 Oracle Fusion Developer Guide: Building Rich Internet Applications with Oracle ADF Business Components and Oracle ADF Faces (McGraw-Hill, 2010)
 Oracle ADF Insider
 Oracle ADF Code Corner

 

DISCUSS Oracle JDeveloper and Oracle ADF
 Oracle JDeveloper and Oracle ADF Oracle Technology Network Forum

 

 DOWNLOAD the starter workspace for this column

In the Application Navigator, right-click the SamplePage.jspx file and choose Run to test the application. Note that at runtime the dependent ManagerId value refreshes if you select a different DepartmentId value. Click Search in the list to show the Search and Select dialog box containing the full ManagerID list. 

Improving the JobId Field with Autosuggest Behavior

The LOV definition for the EmployeesView object’s JobId attribute, which is precreated in the sample, references the JobsView view object. Instead of using Combo Box with List of Values for Default List Type, it uses Input Text with List of Values. So far, the JobId field has LOV behavior only when the user clicks the magnifying glass icon at runtime. Now you’ll add autosuggest behavior to the JobId attribute. 

Return to Oracle JDeveloper with SamplePage.jspx open in the visual page editor. Open the Component Palette by choosing View -> Component Palette from the main menu. In the Component Palette, expand the Operations accordion, find the Auto Suggest Behavior component, and drag it onto the page’s JobId field. Open the Property Inspector, and enter #{bindings.JobId.suggestedItems} as the value of the Auto Suggest Behavior component’s SuggestedItems property.

At runtime, the bindings portion of the expression statement accesses the Oracle ADF binding container. The JobId portion is a list binding that is created for the model-driven LOV when the JobId attribute is added to the page. One of the properties on the list binding is suggestedItems, which returns an LOV that matches the user input in the JobId field.

Still working with the Auto Suggest Behavior component, enter 10 as the value of the MaxSuggestedItems property to restrict the number of display items.

Right-click the SamplePage.jspx file, and choose Run from the context menu to test the application. In the form that appears in your browser, clear the JobId field and type an uppercase A to produce the auto-suggested list of job IDs that begin with A. Try it again by entering an uppercase C. Your results should look similar to Figure 5.

 

o41adf figure 5

Figure 5: Autosuggest behavior
 

If you have not successfully completed this exercise, you can examine the finished application by opening the AdfListOfValues-Completed.jws workspace in the AdfListOfValues-Completed folder, and see it in action by running SamplePage.jspx

Conclusion

Using model-driven LOVs in Oracle ADF not only is the most consistent and manageable approach for building LOVs but also spares you from having to code your own solution. To learn more about model-driven LOVs, see section 25.3.2, “How to Create a Model-Driven List,” in Oracle Fusion Middleware Fusion Developer’s Guide for Oracle Application Development Framework 11g Release 1 (11.1.1.4.0)

  


Frank Nimphius is a senior principal product manager for Oracle JDeveloper and Oracle Application Development Framework. He coauthored Oracle Fusion Developer Guide: Building Rich Internet Applications with Oracle ADF Business Components and Oracle ADF Faces (McGraw-Hill, 2010).  


Send us your comments