An Oracle JDeveloper How To Document
Written by Frank Nimphius, Oracle Corporation
The default List-Of-Values (LOV) dialog in ADF JClient is defined by an inner class,
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.
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
This document assumes the following:
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.
The default List-of-Values dialog is defined as an inner class,
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
To define a custom title string for the default LOV dialog,
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.
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,
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).
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
Open the context menu and
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.
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:
void bindRowSetIterator(DCDataControl dc, RowSetIterator rsi, String lovVODisplayedAttrNames);
void helpAction(ActionEvent ev);
JULovDialogInterface createLovDialog(javax.swing.JComponent control);
void bindRowSetIterator(RowSetIterator rsi, String lovVODisplayedAttrNames); // deprecated since 9.0.5
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.
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
UIModel.xml file entry for this panels looks like shown in the image below.
UIModel.xmlfile attributes Title and AllowSearch, if set, will not work with a custom LOV in ADF JClient. The functionality that reads this information from the
UIModel.xmlfile belongs to the
oracle.jbo.uicli.jui.JULovButtonBindingclass and is available to the default LOV dialog only because it is defined as an inner class.
UIModel.xmlfile is updated to the default setting for the LOV dialog whenever the binding is changed using the binding editor. For example, changing the list of display attributes, after configuring the
UIModel.xmlfile to use a custom LOV dialog panel, will reset the configuration to use the default.
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();
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:
// 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
if ((((JULovButtonBinding) panelBinding.getControlBinding(LOVButton)).getLovPanelInterface())
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:
Run the sample with application with the Basic custom LOV:
The CustomLOVPanel behaves like the default LOV panel, with only some minor changes added.
UIModel.xmlfile with a text editor. The
UIModel.xmlfile can be opened on the file system if no editor is configured as an external tool in JDeveloper.