How To build an LOV with ADF UIX

An Oracle JDeveloper How To Document
Written by Jonas Jacobi
April 2004

Content

• Introduction
• Getting started
• Creating the Business Service
• Create a Struts Pageflow
• Create Input page
• Create the LOV Input field
• Creating the LOV Window
• Apply a filter to the Lov Window

Introduction

This HowTo demonstrates how to build an ADF UIX application that contains an LOV with Oracle JDeveloper 10g.  This Howto will show you how easy it is to create an LOV, and how you can apply a filter to your LOV in Oracle JDeveloper 10g. For more information and HowTos, please, refer to the JDeveloper HowTo documents on Oracle Technology Network (OTN). For this simple application we are using ADF UIX, Struts, and ADF Business Components.

Tasks

This session covers the following tasks:

• Create a simple business service with ADF Business Components
• Create a Struts pageflow diagram
• Create two ADF UIX pages, one with a LOV input field and one page that will be the LOV window page.
• Add code to be able to filter the LOV when launched

Prerequisites

In order to follow this HowTo and build this LOV application you need the Oracle JDeveloper 10g production release, and an Oracle database with the sample HR schema installed.

Getting started

Before we go on the path to create our views and pageflow we need some where to store our work in progress. 

Create a new Application Workspace

1. Create a new Application workspace (File -> New)
   
   
    
2. Select the Application Workspace node.
3. Click OK. This will launch a dialog which will allow us to define location, templates, and application package prefix.
   
   
    
4. Change the name of the Application workspace to - LovApplication
5. Change the Application Template to Web Application [default] and click OK. On completion you should have an application named LovApplication and two projects named Model and ViewController.
   Info: You can use the Edit Templates... button to change the names of your projects and define the technology scope for each project.)
   
   

Creating the Business Service

This is the first solution to pass string value from one page to another, and in this case the Java bean (and value) will exist during the entire session, whereas the second solution, which is covered later in this howto, the value only exist during the request.

This section is just going to cover how to generate a Java bean and make some small changes to it needed for this howto.

1. Right click on the Model project and select New. This will launch the New Gallery dialog
2. In the New Gallery dialog please select the Business Components node
3. In the Items pane select Business Components from Table node and click OK.
   
   
    
4. In the Business Components Project Initialization dialog please select your db connection and click OK.
5. In the Business Components from Table - Step 1 of 3 wizard select the Employees and Departments tables and click Next.
6. In the Business Components from Table - Step 2 of 3 wizard select both objects and click Next.
7. In the Business Components from Table - Step 3 of 3 wizard keep the defaults and click Finish.

Create a Struts Pageflow

Creating a Struts pageflow

The first step in our application is to create a Struts pageflow

1. In the ViewController project double click on the struts-config.xml file. This will open an empty Struts pageflow diagram.
2. On your right hand there should be a Component palette available. If not then you can open the Component palette from the View menu.
3. Click on the Data Page node and then on the empty Struts page flow.
4. Rename the node to mainDP

Create Input page

1. By double clicking on the Data Page node - / mainDP - you will be able to wire your page forward action to a specific page.
   
   Info: By default the name of the page will be the same as the page forward action, and depending on what type of technology you have set in your project there will be a list of available file types. Alternatively you can use the Browse button to open an already existing page.
    
2. For this application we are using UIX XML, so you should type in - main.uix - in the dropdown list.
    
3. Click OK to create a new page. This will open the UIX XML page in the visual editor.
   
   
   
   This is a UIX XML page and when you create a UIX XML page from the Strut pageflow diagram the page is empty apart from a few needed components - dataScope, Body, Form - which are applied to the page by default.

Add an Input form to your page

In the DataControl Palette you should see a list of all available data controls in your Application Workspace. In our case we can see one data control mapping to our Business Components - AppModule - in our Model project.

Note: If the Data Control Palette is not visible you can open the palette from the JDeveloper View menu.

1. Our Data Control has two nodes - EmployeesView1 & DepartmentsView1
   
   
   
   Note: For each data control there is a set of components that you can use to create your application.
    
2. Select the EmployeesView1 node under AppModuleDataControl and look at the different options available in the dropdown list " Drop As:"
3. Select the component type: Input Form (With Navigation)
4. Drag and drop the EmployeesView1 node into the center of your page. Your page should now contain one input form that can be used to enter values.
   
   Your page should look like this:
   
   
    

Create the LOV Input field

We now have a page called main.uix, and we would like to add a LOV to this page for the Departments filed. This field will be used to enter and change the department for a particular employee. The LOV should display the ID and Name of the department to make it easier the select the right department.

1. First we need to remove the current Department ID field. This field will be replaced with a new LOV Input field.
2. After removing the Department ID field in the form, select the DepartmentId attribute in the DataControl palette underneath the EmployeesView1 node.
3. Change the " Drag and Drop As:" type to - MessageLovInput
   
   
    
4. Drag and drop the DepartmentId node onto the page. Your page should look like this:
   
   
    
    
5. Save your work.

Creating the LOV Window

This chapter will focus on wiring up the MessageLovInput field we just added to our page to a LovWindow page, so that the end user can search for departments in a separate window.

The LOV Window page

When you used the Data Control palette to create your new MessageLovInput field the design time created a new UIX page - lovWindow0.uix - that is pre-wired to your MessageLovInput fieled. The only thing you have to do is to add the data source for the LOV window.

1. Open the lovWindow0.uix page. Your page should look like this:
   
   
    
2. In the Data Control palette select the DepartmentId attribute underneath the DepartmentsView1 node.
3. Change the " Drag and Drop As:" type to - LOV Table
4. Drag and drop the DepartmentId node onto the page.
5. When you drop the DepartmentId attribute on your page you will be prompted with the Select Page Flow Data Binding Option dialog. Keep the default value, this will add a new node in your Struts page flow that will represent your lovWindow0 page.
   
   Your page should look like this:
   
   
   Note: If you want you can remove the text item containing the description by clicking on the text and then hit the delete key.
    
6. Save your work

To run an application

1. Open your Struts pageflow diagram
2. Right click on the action you want to run - mainDP
3. Select Run /mainDP
4. Test you application by clicking on the "flash light" icon that is located to the right of the Department field. This should bring up the Lov Window.
   
   
    
5. Resulting Lov Window page:
   
   
    
6. Select a department by clicking on one of the radio buttons. To return to the main page click on the Select button and the selected value will be returned to the Department Id field.
   
   
    

Apply a filter to the Lov Window

As you noticed the Lov Window contains a Search field. This Search field is not wired up by default and in this session we will add some components in order to make this work.

Add a Drop Down List to the Search area

First we need to add a drop down list, so that the user can decide what search criteria to use.

In the listOfValues components there are several named children (slots) that can be used, and one of them is particularly designed to hold a dropdown list - filterChoice. In the ADF UIX land we call dropdown lists "choice" components.

1. Right click on the filterChoice slot and select " Show filterChoice Named Child"
   This will display the empty named child (slot) in the visual editor.
   
   
    
2. From the component palette select the messageChoice component and DnD into the empty filterChoice slot.
3. Remove the prompt from the messageChoice component by deleting the prompt text in the Property Inspector.
4. Change the name property to - filterBy
5. Right click on the messageChoice component and insert inside an option components
6. Set the text property on the option component to - Department_Id.
7. Repeat step 4 and 5 and set the text property to Department_Name.
   Note: The option component is a non-visual component and will not be displayed in the visual editor. If you need to change a property you can access the component (or any non-visual components) from the Structure Window.

Modifying the lovFilter event handler

Now we need to modify the event handler to make the filtering option to work: The event handlers are located at the bottom of the Structure Window.

1. Select the lovFilter event
2. Right click and select " Insert inside ..."
3. Select the invoke element
4. In the dialog that appears enter " setWhereClause" for the Method property.
   Note: This will call the setWhereClause method on the ViewObject.
   
   
    
5. Select the " Enter Advanced Properties" tab
6. Set the following properties:
   
   instance = ${bindings.DepartmentId.viewObject}
   java type = oracle.jbo.ViewObject
    
7. Inside the new invoke element add a Parameters element by right clicking on the invoke node in the Structure Window and selecting " Insert Inside ..."
8. Add one parameter to the new Parameters node in the Structure Window.
9. Set the following properties on the parameter
   
   java type = string
   value = ${empty param.filterBy ? 'DEPARTMENT_ID' : param.filterBy} LIKE '${param.searchText}'
    
10. Add another invoke element below the first one and set the following properties:
    
    method = executeQuery
    instance = ${bindings.DepartmentId.viewObject}
    java type = oracle.jbo.ViewObject
    
    Your event handler tree in the Structure Window should look like this:
    
    
    
     
11. Last piece is to set the searchAreaMode property on the actual listOfValues component to - filter
    Note: Filter mode allows the user to select the column to which their entered search text should be applied.
     
12. And, set the searchText property to - ${param.searchText}
    Note: The searchText property is the value or partial value being searched for.
    
    
     
13. Save your work and run your application from the Struts page flow diagram