How to Create Custom LOV Panels for ADF JClient in Oracle JDeveloper 10.1.2

An Oracle JDeveloper How To Document
Written by Frank Nimphius, Oracle Corporation
January, 2005

Executive Summary

The default List-Of-Values (LOV) dialog in ADF JClient is defined by an inner class, MyLovPanel, in oracle.jbo.uicli.jui.JULovButtonBinding. Because the LOV panel is defined in an inner class, no public methods of the LOV dialog can be accessed in an ADF JClient application. Some information, like the LOV dialog's title string and whether or not a search toolbar is displayed, can be set as a parameter in the UIModel.xml file. Other information, like the position of the LOV dialog or the size of the LOV dialog can't be set without replacing the default LOV panel with a custom panel. This document explains how to create a custom implementation of the ADF JClient LOV dialog to customize the LOV functionality and to make public method accessible to ADF JClient applications. An example for customization is a LOV dialog that shows a search field for the user to provide search criteria to reduce the number of values shown in the LOV. An Oracle JDeveloper 10.1.2 workspace can be downloaded from the Oracle Technology Network (OTN) that contains the source codes for this paper.

Content

      Prerequisites
      Introduction
      About the Default LOV Panel
      Building a LOV Button in Oracle ADF JClient
      Building a Custom LOV panel
      Configuring the LOV Button to Use a Custom LOV panel
      Accessing Methods Exposed by the Custom LOV Panel
      Running the Example

Prerequisites

This document assumes the following:

Introduction

The JULovButtonBinding class in ADF JClient binds a JButton component to a LOV dialog. The LOV dailog is displayed when pressing the LOV button. With the Oracle Application Development Framework (Oracle ADF), the JClient application developer visually defines the data source and target for the LOV dialog by editing the UIModel.xml binding configuration file. A LOV title string and a search bar can be added to the default LOV dialog by editing the UIModel.xml file in a text editor.

If more customization is required, then ADF JClient allows developers to replace the default LOV dialog with their own LOV panel implementation. All custom LOV panels must implement oracle.jbo.uicli.jui.JULovPanelInterface and provide implementations of the methods defined by this interface. This document explains the building of custom LOV panels for ADF JClient and also provides a sample workspace for Oracle JDeveloper 10.1.2 that can be used as a starting point. All descriptions referring to building custom LOV panels will reference the example in the demo workspace.

About the Default LOV Panel

The default List-of-Values dialog is defined as an inner class, MyLovPanel, in oracle.jbo.uicli.jui.JULovButtonBinding. Visually, the default LOV dialog is a table that shows display attributes (declaratively configured in the UIModel.xml file) as columns.

The default LOV panel also implements the oracle.jbo.uicli.jui.JULovPanelInterface. It allows customization of the LOV dialog's title string and search toolbar through parameters - AllowSearch and Title - set in the UIModel.xml file.

To define a custom title string for the default LOV dialog, open the UIModel.xml file of the JClient form in a text editor and add the Title attribute as shown in the image above. Similarly, set the AllowSearch attribute to true to show the query mode (search) icons ( )in the LOV toolbar.

Because the default LOV dialog is defined as an inner class in oracle.jbo.uicli.jui.JULovButtonBinding, it is not possible to access it directly from within an ADF JClient application to set additional properties at runtime.

Building a LOV Button in Oracle ADF JClient

To create a LOV button in ADF JClient, select a View attribute in the Data Control Palette (Ctrl+Shift+D) of Oracle JDeveloper 10g. For example, in the image below, we show DepartmentId as the selected View attribute. In the Drag and Drop As selection list, choose the Button LOV entry. Drag and drop the attribute to the ADF JClient panel. This creates an instance of JButton in the JClient panel and defines an entry for the binding in the UIModel.xml file ( LovFormUIModel.xml in this example).

Select the UIModel.xml entry in the Application Navigator and open the Structure Window (Ctrl+Shift+S). In the Structure window, select the entry created for the LOV button, which is named for the View attribute that was dragged as a LOV button to the JClient panel. In the example shown in the image below, this attribute name is DepartmentId. Open the context menu and select the Edit entry.

In the List Binding Editor, as shown in the image above, select the Data Collection for the LOV source and for the target. The Target Data Collection is where the LOV writes the selected value back to. If an Iterator doesn't exist for one of the collections, create one by pressing the New button. Finally, select the LOV attributes, which values should be copied to the target Collection. Select the LOV Display Attributes tab and choose the display attributes that will display in the LOV dialog and that will be searchable.

Building a Custom LOV Panel

A custom LOV dialog provides the application developer with maximum flexibility in which dialog functionality to expose at runtime. A custom LOV dialog needs to implement the oracle.jbo.uicli.jui.JULovPanelInterface interface so that it can be used with the JULovButtonBinding class in the ADF JClient framework. The following methods are defined by the interface and need to be implemented in a custom LOV panel:

The demonstration that comes with this document starts with a basic custom LOV dialog and subclasses to build more sophisticated LOV panels. Because general functionality, like setting the dialog title, will never change, this approach is sensible.

The basic LOV class used in the sample workspace is named oracle.sample.jbo.uicli.jui.custom.utility.CustomLOVPanel and exposes methods to set the title of the LOV dailog, change the location and set the size of the LOV dialog. In addition a method, setAddSearch(boolean), is provided to dynamically show or hide the search toolbar at runtime.

The image above shows a specialized LOV dialog, oracle.sample.jbo.uicli.jui.custom.utility.SearchFieldLov, which is a subclass of oracle.sample.jbo.uicli.jui.custom.utility.CustomLOVPanel and also provided in the sample workspace for this document. The SearchFieldLov dialog inherits all the methods to set the dialog properties, like the LOV dialog title string, from the CustomLOVPanel class. Instead of showing a search toolbar, the SearchFieldLov displays a text field, like in Oracle Forms, that the application user can use to filter the values shown in the LOV dialog.

Configuring the LOV Button to Use a Custom LOV Panel

Before configuring the custom LOV panel for a JClient application, build the application using the default LOV panel. This is important to make sure that all the databinding work is done for the LOV display attributes, the data source and target. All changes that are performed in the List Binding Editor are written to the UIModel.xml file, overriding any custom settings.

To use a custom LOV dialog instead of the default, the CustomPanel attribute needs to be set in the UIModel.xml file. The value of the CustomPanel is the absolute class name of the custom LOV. As an example, the absolute name of the SearchFieldLov dialog shown in the image above is oracle.sample.jbo.uicli.jui.custom.utility.SearchFieldLov. The UIModel.xml file entry for this panels looks like shown in the image below.

Note:

Accessing Methods Exposed by the Custom LOV Panel

Public methods exposed on the custom LOV panel can be accessed  in an ADF JClient application through calls to the getControlBinding(Object) method on the panel binding. In the example code below, CustomLovPanel is a custom LOV panel that exposes a public method setAddSearch(boolean) to show or hide the search bar in the LOV dialog. The "LOVButton" object is an instance of JButton and is bound to the data model in ADF.

JULovButtonBinding juLovButtonBinding = (JULovButtonBinding) panelBinding.getControlBinding(LOVButton);
CustomLOVPanel custLovPanel = (CustomLOVPanel)juLovButtonBinding.getLovPanelInterface();
custLovPanel.setAddSearch(true);

When working with a subclass of a CustomLOVPanel (like SearchFieldLov in the example workspace), an application can use the following code to avoid runtime exceptions when calling methods on this specialized LOV:

if (juLovButtonBinding.getLovPanelInterface() instanceof oracle.sample.jbo.uicli.jui.custom.utility.SearchFieldLov)
{
  // cast panel to SearchFieldLov and call specific method on the SearchFieldLov
}

Methods of SearchFieldLov that are inherited from the CustomLOVPanel are accessible by casting the panel instance to CustomLOVPanel, as shown in the first example.

The example JClient form LovForm.java uses similar code to define the table column in the LOV panel that the search string entered in the search field should be added to before querying the LOV data. Because setting this column is a method in SearchFieldLov and not CustomLOVPanel, the application has to check first which custom LOV panel was configured in the UIModel.xml file. The code below defines the second column in the table , DepartmentName, as the query column. To query the DepartmentId column instead, change the argument in the call to setSearchColumn to 0.

if ((((JULovButtonBinding) panelBinding.getControlBinding(LOVButton)).getLovPanelInterface()) instanceof oracle.sample.jbo.uicli.jui.custom.utility.SearchFieldLov)
{
 ((SearchFieldLov)((JULovButtonBinding)panelBinding.getControlBinding(LOVButton)).getLovPanelInterface()).setSearchColumn( 1);
}

Running the Example

The demo workspace that comes with this document provides two LOV panels, a basic custom LOV panel - CustomLOVPanel - and a more sophisticated LOV - SearchFieldLov - that show a text field for filtering the set of values shown in the LOV dialog. Instead of going through the code details within this document, the Java files contain comments where needed to explain what the code does. Use both files as a starting point for building your own custom LOV panels that work within ADF JClient.

To run the sample workspace:

  • Open the workspace in Oracle JDeveloper 10.1.2.
  • Create a database connection hr_conn in Oracle JDeveloper that has a connection to the HR database schema.
  • Compile the workspace.
  • Select LovForm in the Application Navigator and choose run from the context menu.
  • Define a new title for the LOV dialog and press the button to set it.
  • Check the checkbox that defines the search bar to be shown.
  • Press the LOV button to show the LOV dialog.
  • Enter a search string into the search field. You can use % as wildcards.
  • Press Enter to query the LOV or Esc to cancel search.
  • After filtering the LOV dialog, press Enter on an empty search field to show all LOV entries again.

Run the sample with application with the Basic custom LOV:

The CustomLOVPanel behaves like the default LOV panel, with only some minor changes added.

  • Open the UIModel.xml file with a text editor. The UIModel.xml file can be opened on the file system if no editor is configured as an external tool in JDeveloper.
  • Change

    CustomPanel="oracle.sample.jbo.uicli.jui.custom.utility. SearchFieldLov"

    to

    CustomPanel="oracle.sample.jbo.uicli.jui.custom.utility. CustomLOVPanel"
  • Run the LovForm from the Application Navigator in JDeveloper.
  • Set the title for the LOV dialog as before and also check the checkbox to show the search toolbar icons.
  • In the LOV dialog, press the Set Find Mode button.
  • Add the search criteria directly into the table columns. Make sure you navigate out of the column where you set the search criteria before executing the query.
  • Execute the query to show the filtered list of values.

Download the demo workspace