Building Enterprise JSF Applications with Oracle JHeadstart for ADF (10.1.3)

A step-by-step, end-to-end tutorial on how to be effective immediately with J2EE application development using Oracle tools.

Abstract

There is good chance you've heard that developing database-centric business applications for the J2EE platform is a complex endeavor. Luckily, there is hope. Over the past few years, analysts like Gartner Group coined the term "J2EZ" for a class of tools and frameworks that make J2EE application development easy. These so-called "J2EZ" tools target developers for whom time to market, low implementation costs, and productivity are driving factors, by providing a visual, declarative, and highly productive environment. This document provides step-by-step instructions to evaluate what you can achieve today using production versions of Oracle's offerings in this "J2EZ" space by combining the 10.1.3 versions of Oracle's JDeveloper 10g IDE, the Oracle Application Development Framework (ADF), and the Oracle JHeadstart 10g Application Generator for Oracle ADF.

By following this tutorial, you'll experience first-hand how Oracle JHeadstart 10g turbo-charges your developer productivity for Oracle ADF-based web applications. You will build an attractive, consistent, interactive, and skinnable web application with browse, search, insert, update, and delete functionality against six related database tables from the Oracle HR sample schema. Your application will feature single- and multi-row editing, page-by-page scrolling, master/detail handling, tabbed pages, dropdown lists, a pop-up list of values (LOV) window, a wizard, a shuttle picker, a tree control and a graph. Since no Java coding is required to implement the tutorial, even developers with minimal-to-no Java skills can follow along. This is possible because Oracle ADF-powered J2EE applications only require custom code to add application-specific business logic or to augment default framework behavior.

Contents

1 Overview of Oracle ADF and Oracle JHeadstart 10g

On their own, the Oracle Application Development Framework (ADF) together with the Oracle JDeveloper 10g IDE give developers a productive, visual environment for building richly functional J2EE applications without having to implement J2EE design patterns and low-level plumbing code by hand. As its name implies, Oracle JHeadstart 10g offers a significant additional productivity advantage in creating sophisticated web-based, J2EE business applications. Standing squarely on the shoulders of the base Oracle ADF framework, Oracle JHeadstart adds an additional capability for generating fully-working JavaServer Faces (JSF) web tier for the data model exposed by your ADF application module. The ADF web applications you generate with JHeadstart leverage the powerful ADF Faces components for JSF so can easily support multi-row editing, lists of values (LOVs) with validation, tree and shuttle displays, and consistent search pages, among many other features.

JHeadstart automates creating and iteratively evolving the web tier of your ADF application based on a declarative application definition. Once you've allowed JHeadstart to generate the bulk of your application's web user interface, you can spend your time using JDeveloper's productive environment to tailor the results or to concentrate your effort on real showcase pages that need special attention.

Like all Oracle ADF-based applications, those leveraging Oracle JHeadstart are J2EE compliant and therefore easy to deploy to any J2EE application server. They also inherit Oracle ADF's implementation all of the best practice J2EE design patterns ^[3] required to implement robust, functional business applications.

As we'll see in this step-by-step demo, the JHeadstart Application Generator does not generate any Java code. Instead, it generates web pages, ADF metadata describing the data needed on those pages, JavaServer Faces (JSF) metadata describing the page flow, and translatable message bundle files. We'll also see that all of the basic functionality provided by the underlying Oracle ADF framework components in the demo does not require any generated Java code either. We hope you'll walk away impressed by what you can do without writing a single line of Java code using this powerful combination of J2EE tools and frameworks from Oracle. Any lines of code that you would eventually write in a real application would be squarely focused on enhancing all of the built-in functionality provided with your own custom business application logic.

2 Tutorial Setup

This section outlines the steps you'll need to follow to get your machine ready to go through this tutorial. We recommend not skipping any steps in this section without reading them!

2.1 Download the Tutorial Files

If you are reading this tutorial online, download the jhs-step-by-step.zip ^[5] file that contains the database setup scripts. Extracting this zip file into the root directory of your C:\ drive will create a jhs-step-by-step directory. You can browse the index.html page to read this same tutorial offline. The database setup scripts (described more in detail below) are in the hr_schema subdirectory.

2.2 Start with JDeveloper 10g, Release 10.1.3.2

This tutorial requires Oracle JDeveloper 10g Studio Edition, release 10.1.3.2 Production. If you have a version of Oracle JDeveloper installed, you can verify what version it is by selecting the Help | About option from the main menu.

If you need to download JDeveloper 10g Release 10.1.3.2 look for the correct version on this JDeveloper Downloads ^[6] page.

To install JDeveloper, create a convenient directory (e.g. C:\jdev1013) and extract the jdevstudio10132.zip file into this directory using the standard Java jar utility, WinZip, or other zip-compatible tool you prefer.

To start JDeveloper 10g, double-click on jdeveloper.exe in the C:\jdev1013 folder as shown in Figure 1. You can create a desktop shortcut for C:\jdev1013\jdeveloper.exe to make launching JDeveloper easier on future occasions.

Figure 1: Launching JDeveloper 10g on Windows

Upon starting JDeveloper 10g for the first time, the Migrate User Settings alert may appear asking "Would you like to migrate from a previous version of JDeveloper?" If it does, just click (No) to continue.

Dismiss the Tip of the Day dialog if it appears by clicking (Close).

2.3 Install Oracle JHeadstart 10g 10.1.3.1 Using "Check for Updates"

Oracle JHeadstart is an Oracle JDeveloper extension (or "plug-in") that you install using JDeveloper's "Check for Updates" functionality. If anything about these installation instructions doesn't work for you as indicated, check the JHeadstart 10g Product Center ^[4] on OTN, under the Downloads heading, for further assistance.

To install the JHeadstart 10g Evaluation Version into your JDeveloper 10g 10.1.3 environment, perform the steps below.

• Run the "Check for Updates" wizard

  With JDeveloper 10.1.3 running, choose Help | Check for Updates... from the main menu.

  
  
  

• Select the Source for Extensions

  In Step 1 of 3: Source ensure that you have selected both the Official Oracle Extensions and Updates as well as the Open Source and Partners Extensions update centers, then click (Next >).

  
  
  

• Select the Oracle JHeadstart Evaluation Version Extension to Install

  In Step 2 of 3: Updates, as shown in Figure 2 choose the Oracle JHeadstart Evaluation Version 10.1.3.1.23 extension, then press (Next >).

  
  Figure 2: Selecting the JHeadstart Evaluation Version Extension to Install
  
  

• Acknowledge the Legal Agreement

  Read and acknowledge the Oracle Technology Network license for the evaluation version of Oracle JHeadstart by clicking (I Agree). JDeveloper begins the download of the selected updates...

  
  
  

• Exit and Restart JDeveloper

  When the download is completed, on the Summary page of the wizard, click (Finish). The Confirm Exit alert appears because you need to exit and restart JDeveloper to install the service update. Click (Yes) to exit. On Windows, JDeveloper will exit and automatically restart. On Mac, Linux, or other platforms, JDeveloper will exit and you will need to launch it again.

  
  
  

• Acknowledge the Installation Alerts

  When JDeveloper restarts, you may see the Confirm Overwrite alert, making you aware that the automatic installer will be replacing a file in your JDeveloper installation. This is expected, so check the Skip this Message Next Time checkbox, and click (Yes) to continue. When the Migrate User Settings alert appears, click (No) to continue.

  
  
  

• Acknowledge the Successful Installation Alert

  After the installation is completed, you'll see the alert shown in Figure 3 confirming the successful installation. Press (OK) to continue.

  
  Figure 3: Acknowledging the Successful Install of JHeadstart
  
  

• Rename the Velocity Version 1.3 JAR File

  As noted in the successful installation alert in Figure 3, you must perform one manual step of renaming a file that is supplied with JDeveloper. This step is required because the JHeadstart extension provides a later version of this library than the one that ships with JDeveloper. To rename this file, do the following:

  • Exit from JDeveloper

    Choose File | Exit to exit JDeveloper.

  • Rename the velocity-dep-1.3.jar File in the Windows Explorer

    As shown in Figure 4, find the velocity-dep-1.3.jar in the C:\jdev1013\jdev\lib directory, and use the Rename option on the right-mouse menu to rename it to velocity-dep-1.3.jar_old.

    
    Figure 4: Renaming velocity-dep-1.3.jar to velocity-dep-1.3.jar_old in Windows Explorer

  • Restart JDeveloper

    After renaming the jar file as indicated above, you can restart JDeveloper 10g 10.1.3 to continue.

  
  
  

2.4 Setup the Oracle HR Schema and Sample Data

The demo steps are based on the standard Oracle sample HR schema of human resources information. For your convenience, this tutorial comes with the SQL scripts to create the HR schema tables if you didn't install the sample schemas when you installed your database.

2.4.1 Create the HR Schema If Necessary

If you don't already have an HR user account created in your database, you can follow these steps to create it.

C:\jhs-step-by-step> sqlplus /nolog
SQL> connect sys as sysdba
SQL> create user hr identified by hr;
created.
SQL> alter user hr default tablespace users;
altered.
SQL> grant connect, resource to hr;
SQL> connect hr/hr
connected.
SQL> quit

2.4.2 Create the HR Schema Sample Tables

In the hr_schema subdirectory of this tutorial, you'll find the hr.sql script. This script drops, recreates, and repopulates all the tables in the HR sample schema. Change directory to the hr_schema subdirectory, and run the script as the HR user, with the command:

C:\jhs-step-by-step> cd hr_schema
C:\jhs-step-by-step\hr_schema> sqlplus hr/hr @hr.sql

2.5 Define a JDeveloper Connection for the HR Schema

Select View | Connection Navigator to show the Connection Navigator and follow these steps:

• Create a New Database Connection

  Click on the Database folder, and select New Database Connection... from the right-mouse menu as shown in Figure 5.

  
  Figure 5: Defining a New Database Connection
  
  

• Enter a Connection Name

  On step 1 of the wizard, as shown in Figure 6, provide a connection name of hr and click (Next>).

  
  Figure 6: Naming Your Connection
  
  

• Provide the Username and Password Details

  On step 2, provide the username and password information for the hr connection. Make sure to check the Deploy Password option as shown in Figure 7, then press (Next>).

  
  

  NOTE:

  It's OK to deploy the password in the connection definition since it gets saved in an encrypted format.

  
  
  Figure 7: Providing Username/Password for the Connection
  
  

• Provide Host, Port, and SID Information

  In step 3, provide the host, port, and SID information for the database where you've installed the HR schema tables. The defaults shown in Figure 8 are right for a default Oracle database installation on the current machine. You may have to change the settings if you're database is on another machine or has a different SID. Press (Next>) when done with this step.

  
  Figure 8: Providing Database Connection Details
  
  

• Test the Connection

  As shown in Figure 9, click the (Test Connection) button to test the connection. If you don't see the "Success!" message, press (<Back) and double-check the information you've provided on the previous wizard pages. When you see "Success!", click (Finish) to complete the process of defining a connection.

  
  Figure 9: Testing the Database Connection
  
  

2.6 Set ADF Business Components Java Generation Preferences

By default, the ADF Business Components design time is configured to generate skeleton Java classes where developers could eventually write their code. Producing these skeleton classes by default is not required, and there is an IDE preference to control it. If you don't generate them by default, you can easily add them on a case-by-case basis should custom Java code ever become required for a given component type.

In order to better understand what ADF application functionality requires Java code and what does not, it's useful to set the ADF Business Components Java generation preferences at the IDE level so that the wizards and editors create no custom Java classes by default. By doing this, at the end of the demo we can see what Java classes actually are part of our working, finished application to get a better understanding of what combined, built-in functionality Oracle ADF and Oracle JHeadstart 10g provide.

To change this preference, select Tools | Preferences... from the JDeveloper main menu and click on the Business Components category. Uncheck any of the checked boxes in the panel at the right as shown in Figure 10, then click (OK).

Figure 10: Setting ADF Business Components to Generate No Java by Default

3 Creating a Default Web Application

In this section we will:

• Create a new workspace,
• Create the ADF Business Components to handle our backend database access, and
• Generate a default set of web pages with JHeadstart

Then, we'll run the application inside JDeveloper 10g to see what default behavior we get before starting to iteratively modify the application to further tailor it to work like our end users want.

3.1 Create and Configure a New Workspace

1. Create a new Application Workspace

   Choose File | New... from the JDeveloper main menu, and double-click the Application icon in the General category of the New Gallery. In the Create Application dialog, select the application template named Web Application [JSF, ADF BC] as shown in Figure 11. To make it easier to follow along in this tutorial, please enter the Application Name (MyDemo), Directory Name (C:\MyDemo), and Application Package Prefix (mydemo) exactly as shown. By doing this you'll make it easiest to follow this tutorial's step-by-step instructions.

   
   Figure 11: Creating a New Application Workspace

   When you click (OK) to create the workspace, JDeveloper will create your new MyDemo workspace that will contain two (initially empty) projects named Model and ViewController.

   
   
   

2. Give Your Web Application a Meaningful Web Context Root Name

   Select the ViewController project still selected in the Application Navigator, and choose Project Properties... from the right-mouse menu. Visit the J2EE Application category and notice that the default web context root name is MyDemo-ViewController-context-root. The J2EE web context root name is the first part of your application's web URL that users will see, so having a short, meaningful name is preferable to this long default name. So let's set the J2EE Web Context Root to just “MyDemo” instead. Technically, this step is optional, but it gives your application a nicer-looking runtime URL and it's nice to know where you would change it for your own applications.

   
   
   

3. Simplify Running the Application By Changing a Project Setting

   While still in the Project Properties dialog, to make it easier to quickly run the application, disable JDeveloper's default behavior of trying to run the current file. To do this, do the following:

   • Visit the Run/Debug category
   • Select the Default configuration in the Run Configurations list
   • Click (Edit...)
   • Uncheck the checkbox Attempt to Run the Active File before Default.
   • Click (OK) to dismiss the Edit Run Configuration dialog.
   
   
   

Finally, click (OK) to dismiss the Project Properties dialog, saving your changes.

3.2 Create Default ADF Business Components

The ADF Business Components handle all of the database access for you in a way that is cleanly separated from the user interface. The application module provides the transactional component clients use to browse and modify view object data. The view object performs SQL queries and coordinates with entity objects to handle updates. The entity object encapsulates business domain data and validation for rows in a table. In this step we'll use wizards to create all three types of components based on existing tables in the database.

1. Create Default Business Components for Tables in HR Schema

   • Run the Business Components from Tables Wizard

     Select your Model project and choose New... from the right-mouse menu. In the New Gallery, expand the Business Tier node, select the Business Components category, and choose Business Components from Tables.

     
     
     

   • Set the Database Connection to Use

     When the Initialize Business Components Project dialog appears, select the name of the HR connection you defined above as shown in Figure 12.

     
     Figure 12: Selecting the HR Connection to Work With
     
     

   • Create Entity Objects for Selected HR Tables

     On the Step 1 of 5: Entity Objects page of the wizard, if it is not already checked, toggle the Auto-Query checkbox to see all of the available tables.

     As shown in Figure 13 shuttle the six tables COUNTRIES, DEPARTMENTS, EMPLOYEES, JOBS, LOCATIONS, and REGIONS tables into the Selected list, and enter the Package name of mydemo.model.entities in which to create the entity objects.

     
     

     TIP:	Providing a different package name for each different kind of ADF Business Component helps make your model project more manageable.

     
     
     Figure 13: Selecting Tables for Which to Create Entity Objects
     
     

   • Create Updateable View Objects for All Entity Objects

     On the Step 2 of 5: Updateable View Objects page of the wizard, enter a Package name of mydemo.model.queries as shown in Figure 14, and shuttle all of the available entity object names into the Selected list in order to create default view objects for them.

     
     Figure 14: Creating Updateable View Objects for All Entity Objects
     
     

   • Skip Past the Read-Only View Objects Panel

     As shown in Figure 15, just skip past the Step 3 of 4: Read-Only View Objects page of the wizard since we don't need any read-only view objects for this demo.

     
     Figure 15: Skipping the Read-Only View Objects Panel
     
     

   • Give Your Application Module Component a Meaningful Name

     On the Step 4 of 5: Application Module page of the wizard, as shown in Figure 16 enter a package name of mydemo.model and choose a meaningful name for your application module like HRModule, then click (Finish) to create all of your business components.

     
     Figure 16: Naming the Application Module
     
     
   
   

   NOTE:

   For a more detailed explanation of this step, see the "Setting Up the Business Components Package" section in Chapter 2. Getting Started from the JHeadstart Developer's Guide [10].

   
   
   
   

2. Organize Your Application Navigator

   After creating your default set of business components in the mydemo.model, mydemo.model.entities and mydemo.model.queries packages, your Application Navigator may look like what you see in Figure 17. The Flat Level control in the Application Navigator toolbar controls how many levels of dot-separated package names should be flatted for presentation in the tree. The Sort by Type toggle button switches between sorting your components:

   • Alphabetically, and
   • By component type, then alphabetically.
   
   Figure 17: Model Project in the Application Navigator with Default Flat Level of 3 and Sorted Alphabetically

   For example, if you set the Flat Level to 1 and enable the Sort by Type toggle button, your navigator will change to look like what you see in Figure 18.

   
   Figure 18: Model Project in the Application Navigator with Flat Level 1 and Sorted By Type
   
   

3. Add Five-level Master/Detail to the Application Module's Data Model

   In the Application Navigator, inside your Model project find the HRModule component. It's in the mydemo.model package. Edit the HRModule application module by double-clicking it. This will open the Application Module Editor. Visit the Data Model panel, and as shown in Figure 19 you'll see both the list of Available View Objects from the current project, and the named, master/detail-coordinated usages of those view objects in this application module's Data Model. The view object usages in the data model are also known as view object instances since at runtime they represent an instance of the reusable view object component.

   
   Figure 19: Initial HRModule Data Model

   We're going to modify the default data model to add nested view object usages in order to get a 5-level deep nesting of region → country → location → department → employee.

   We start by adding a LocationsView view object instance as a child/detail of CountriesView2, by doing the following:

   • In the Data Model tree control, select the existing view instance CountriesView2 that will become the new master (for the next-level detail we're about to add).
     
     
   • Expand the CountriesView view object in the Available View Objects list
     
     
   • Select the LocationsView view object that is indented under CountriesView in the Available View Objects list. This indenting means that it is an available detail view for any instance of a CountriesView master in the data model.
     
     
   • Click the (>) button to shuttle a new LocationsView3 instance into the data model as detail of the existing, selected CountriesView2.
     
     

   We can repeat the process to add an instance of DepartmentsView as a detail of the LocationsView3, and then again to add an instance of EmployeesView as a detail of the DepartmentsView4.

   When finished adding the three extra levels, your application module's data model will look like what you see in Figure 20. Click (OK) to save your changes.

   
   Figure 20: Default Application Module Modified to Have Five-Level Master/Detail
   
   

3.3 Generate Default Web Tier with JHeadstart

The Oracle JHeadstart extension for JDeveloper uses metadata to capture the high-level definition of the layout and features of your desired web application. The JHeadstart application generator then uses that application definition metadata to generate the set of web pages that comprise your web application user interface. In this section we'll enable our project to use JHeadstart, ask JHeadstart to create a default application definition metadata file, and then kick off the JHeadstart application generator to see what kind of web application we get before proceeding to tailor the output further in subsequent steps of the tutorial.

1. Enable JHeadstart on the ViewController Project

   Select the ViewController project in the navigator and choose Enable JHeadstart on this Project from the right-mouse menu. Click (Next>) from the welcome page, then click (Finish) to proceed with enabling JHeadstart.

   As shown in Figure 21, after clicking (Finish) the first time the wizard will proceed to create a number of necessary files and configure your project appropriately to contain them. Each step it performs is listed in the text box in this panel of the wizard. When done, click (Finish) again to close the wizard. Then, click the Save All button in the JDeveloper main toolbar to save all the changes.

   
   Figure 21: Enabling JHeadstart on ViewController Project
   
   

2. Create the Default JHeadstart Application Definition

   Select the ViewController project in the navigator, and choose the New JHeadstart Application Definition item from the right-mouse menu. After clicking (Next>) to leave the welcome screen, on the next panel as shown in Figure 22, select the HRModuleDataControl to use, leave the Create default Groups for all Data Collections checkbox checked, and click (Next>) again.

   
   Figure 22: Selecting the Application Module (Data Control) to Use

   On the following panel, take the defaults for the service/application name as shown in Figure 23 , and click (Next >).

   
   Figure 23: Choosing a JHeadstart Service/Application Name

   On the next panel, take the defaults for the default layout styles as shown in Figure 24.

   Before proceeding, take a moment to notice the option to Generate LOV's instead of dropdown lists?. While we won't enable this preference for this tutorial, it's worth remembering that this option may be useful to you when you try the Oracle JHeadstart Evaluation Edition on a subset of your own production schema. JHeadstart can generate foreign key lookups as dropdown lists or as pop-up list-of-values (LOV) windows. Dropdown lists are more appropriate for smaller-sized lists of choices (e.g. less than 100 rows), while pop-up LOV windows are more appropriate to select an foreign key value when many choices exist and your end user might need to perform a search to find what they are looking for.

   Now, click (Next >) to continue.

   
   Figure 24: Choosing Default Layout Styles

   On the final panel click (Finish) to create the new application definition file. As shown in Figure 25 the wizard will display each of the steps it performs. When done, click (Finish) again to close the wizard.

   
   Figure 25: Creating the Default Application Definition File
   
   

3. Save Your Changes

   Click the Save All button in the JDeveloper main toolbar to save all the changes.

   
   
   

4. Observe the Default Application Definition

   To view the JHeadstart application definition you just created, select the ViewController project and choose Edit JHeadstart Application Definition from the right-mouse menu. This opens the JHeadstart Application Definition Editor, which is a modeless window that you can keep open while you continue to work with the main JDeveloper window.

   Notice that JHeadstart has used the hierarchical structure of the application module's data model to create the default application definition for the web tier. In practice you will end up iteratively changing the default application definition, but having a nice default definition to start with is a big plus as we'll see.

   As shown in Figure 26, you can see the 5-level nesting of the view object instances for regions, countries, locations, departments, employees . You also notice that the JHeadstart New Application Definition wizard has created you a rich set of default lookup definitions (called domains) where foreign key relationships exist in the base business component model. These domains are referenced by items in the application definition for which drop-down lists will be generated for the end-user to select a valid choice.

   
   Figure 26: Application Definition Editor Showing Default Structure
   
   

5. Generate the Application

   To run the JHeadstart application generator, select your ViewController project in the Application Navigator and choose Run JHeadstart Application Generator from the right-mouse menu as shown in Figure 27.

   
   Figure 27: Running the JHeadstart Application Generator for the First Time

   During the generation process, the JHeadstart Application Generator log window tab will display the detailed progress, including errors (if any), warnings, and informational messages. Figure 28 shows what this log window tab should look like after your first successful generation run. If you should see entries in an Errors category, which would appear at the top of the list with a "red ball" icon, the message always gives helpful details about how to correct the problem. Note that even when you see a few Warnings, these are suggestions of "next steps" you need to do as the developer or best-practices suggestions that the Generator cannot do automatically. Scrolling through the messages in the Information section gives you an idea of the amount of work that the JHeadstart application generator is saving you. In this case, it has generated twenty-two (22) JSF pages and their corresponding declarative databinding metadata, along with numerous other declarative artifacts that support the application!

   For your convenience, on future runs of the JHeadstart application generator, in addition to the right-mouse menu option we picked here, you can also just click on the Run JHeadstart Application Generator toolbar button () at the top of the JHeadstart Application Definition Editor window. Both actions do the same thing.

   
   Figure 28: Warnings and Informational Messages in the JHeadstart Application Generator Log Window
   
   

3.4 Run the Application

Run the ViewController project by selecting it in the application navigator and then pressing F11 (or clicking on the toolbar run icon ). JDeveloper will launch your default browser, startup the embedded OC4J container with your web application deployed, and show you the initial page of the application that will look like what you see in Figure 29.

Figure 29: Initial JHeadstart-Generated Web Application

TIP:

If instead of seeing the initial application page you see some kind of timeout error in your browser as shown in Figure 30, then you'll need to change a configuration property of JDeveloper's embedded J2EE container (OC4J) to avoid this problem. This typically occurs when you are on a network using DHCP to get a dynamically-assigned IP address. Figure 30: Running Web App in JDeveloper Times Out in Browser Before changing the necessary setting, terminate the currently running embedded server by selecting the Run | Terminate > Embedded OC4J Server. Next, select the Tools | Embedded OC4J Server Preferences... main menu item in JDeveloper, and change the Host Name of IP Address Used to Refer to Embedded OC4J setting to Specify Host Name, and enter a hostname of localhost as shown in Figure 31. Then, try rerunning the application and it should work this time. Figure 31: Changing IDE Preference for Embedded OC4J Host Name

3.5 Observe Default Application Functionality

By playing with the default application yourself, you can experience some of the built-in features that Oracle ADF and JHeadstart support by default, and which the Oracle JHeadstart Application Generator generates for you based on your declarative application definition file.

Highlights of these features include:

• Switch Between Top-Level Application Functionality with Tabs

  
  
  
  
• Browse Data and Drill-Down to Details or Related Information
  
  
  

• Automatic "Breadcrumbs" Provide User Hierarchical Navigation Assistance

  
  
  
  

• Create and Edit Data for Any Table Out of the Box

  
  
  
  

• Insert, Update, and Delete Multiple Rows on a Page

  
  
  
  

• Select Related Data from Automatically Created Lookups

  
  
  
  

• Scroll Through Data Without Refreshing Entire Page

  
  
  
  

• Rapidly Find Data Using Quick Search Region

  
  
  
  

• Search More Precisely Using Advanced Search Region

  
  
  
  

• Easily Set Optional Fields to Null Using Drop-Down Lists

  
  
  
  

• Avoid Accidentally Losing Pending Changes When Switching Top-Level Application Function

  
  
  
  

• Never Wonder Whether Changes are Saved with Positive User Feedback

  
  
  
  

4 Change Layout Styles and Query Behavior

In this step of the demo, we'll change a number of declarative application definition properties about the Employees, Departments, Jobs, and Regions groups to affect how the JHeadstart application generator generates the web tier pages. We'll wait until making them all before re-running the application generator.

To make the changes described here, make sure you have the JHeadstart Application Definition Editor open. If you don't, just select your ViewController project and select Edit JHeadstart Application Definition from the right-mouse menu.

4.1 Change How Employees Group Gets Generated

• Use an Inline "Table Overflow" Area to Hide Less Common Employee Fields

  As shown in Figure 32, in the Employees group, set the Table Overflow Style property (in the Group Layout category) to the value "inline".

  
  Figure 32: Selecting Detail Disclosure for Employees Group
  

  TIP:	If you have trouble finding a property, you can click on the "Binoculars" search icon in the JHeadstart Application Definition Editor and type in some characters of the name you're looking for.

  
  
  

  TIP:	Every property in the JHeadstart editors is documented with a helpful usage message in the help zone below the property table as shown in Figure 33. Figure 33: Detailed Usage Information for Every Property

  
  

  Next, we need to indicate which attributes should be hidden by default when displayed in a table. To accomplish this, expand the Employees group and its Items folder to see the names of the items in that group. The default application definition includes an item for each attribute of each view object in the data model. Set the Display in Table Layout? property (in the Display Settings category) to false for all attributes except: EmployeeId, FirstName, LastName, and Email. As shown in Figure 34, we can multi-select attributes using the mouse in combination with the Shift or Control keys, then set the desired property.

  
  Figure 34: Quickly Setting a Property for Multiple Attributes

  Next, on the same set of attributes, set the Display in Table Overflow Area? property to true as shown in Figure 35.

  
  Figure 35: Setting Attributes to Display in the Table Overflow Area
  
  

• Set the Prompt of DepartmentId to be More User-Friendly

  As shown in Figure 36, set the Prompt in Form Layout property of DepartmentId to be the more user-friendly string “Department”. This will make more sense to the user since what they see at runtime is a dropdown list of department names for this field.

  
  Figure 36: Making DepartmentId Prompt More User-Friendly
  
  

• Allow End-User to Choose Query Operator for LastName

  Set the Query Operator property of the LastName attribute to “setByUser” as shown in Figure 37. This property is in the Query Settings category.

  
  Figure 37: Allowing User to Choose LastName Query Operator
  
  

• Allow End-User to Perform "Between" Search on Salary

  Set the Query Operator property of the Salary attribute to “between” as shown in Figure 38.

  
  Figure 38: Allowing User to Search on Salary Range
  
  

• Make the Table Display for Employees be Browse-Only

  Select the Employees group and, as shown in Figure 39, uncheck the Multi-Row Insert Allowed, Multi-Row Update Allowed and Multi-Row Delete Allowed checkboxes for the Employees group. These properties are in the Operations category.

  
  Figure 39: Making the Table Display for Employees Browse-Only
  
  

• Force User to Find Employees Instead of Auto-Querying Them

  Uncheck the Auto Query checkbox in the Search Settings category, as shown in Figure 40.

  
  Figure 40: Avoiding an Automatic Employees Query
  
  

• Force User to Refine Search Criteria to be More Selective

  As shown in Figure 41, set the Maximum Number of Search Hits to 50. This property is also in the Search Settings category.

  
  Figure 41: Limiting the Maximum Number of Employees Search Hits
  
  

• Default the Quick Search Item to an Employees Last Name

  Set the Single or Default Search Item property to LastName, as shown in Figure 42.

  
  Figure 42: Setting the Default Search Item to LastName for Employees Group
  
  

• Cause Child Groups to Display as Subtabs on the Same Page

  As shown in Figure 43, check the Stack Detail Groups on Same Page? property (in the Group Layout category).

  
  Figure 43: Setting Child Groups to Stack into Tabs on the Same Page

  Expand the top-level Employees group and its Detail Groups folder. As shown in Figure 44, check the Same Page? property of all the detail groups of Employees.

  
  Figure 44: Setting Both of Employees' Child Groups to Display on the Same Page as the Parent Group

  Select the Employees2 group and set its Tabname, Display Title (Plural), and Display Title (Singular) properties (in the Labels category) as shown in Figure 45. Since this group represents employees managed by the current employee in the Employees group, we choose a more understandable name like "Subordinates".

  
  Figure 45: Changing Tab and Display Titles for Employees2 Child Group

  Repeat the same steps to change the Tabname, Display Title (Plural), and Display Title (Singular) properties of the Departments2 group to be "Managed Departments" as shown in Figure 46.

  
  Figure 46: Changing Tab and Display Titles for Departments2 Child Group
  
  

4.2 Change How the Departments Group Gets Generated

• Display Employees in Department on Same Page

  In child group Employees3 check the Same Page checkbox in the Group Layout category as shown in Figure 47.

  
  Figure 47: Showing a Child Group's Information on Same Page as Parent
  
  

• Configure Table Overflow Area to Display Some Items Below the Table

  As shown in Figure 48, set the Table Overflow Style of the Employees3 detail group to below.

  
  Figure 48: Setting Employees3 Group to Overflow Items Below the Table

  For all items except EmployeeId, FirstName, and LastName, as shown in Figure 49 set Display in Table Layout? to false and Display in Overflow Area? to true.

  
  Figure 49: Setting Multiple Employee3 Group Items to Display Only in Table Overflow Area
  
  

• Changing the Creation of New Employees Through this Detail Group

  As shown in Figure 50, ensure that the New Rows property has a blank value, and check the Show Add Row Button? and Show Duplicate Row Button? properties on the Employees3 detail group.

  
  Figure 50: Changing Insert for the Employees Group
  
  

4.3 Change How the Jobs Group Gets Generated

To apply the changes in this section, make sure you've selected the top-level Jobs group in the JHeadstart Application Definition Editor.

• Allow End-User to Select Job to Edit Using a List Display

  As shown in Figure 51, select the Jobs group and set its Layout Style property to select-form.

  
  Figure 51: Using a List to Select the Current Job to Edit
  
  

• Disable Advanced Search for Jobs

  As shown in Figure 52, set the Advanced Search? property of the Jobs group to none. The property is in the Search Settings category.

  
  Figure 52: Disabling Advanced Search for Jobs Page
  
  

• Limit Quick Search Feature to the JobTitle Field

  First, set the Quick Search? property of the Jobs group to singleSearchField as shown in Figure 53.

  
  Figure 53: Limiting Quick Search for Jobs to a Single Field

  Then, set the Single Search Attribute property to JobTitle as shown in Figure 54. These properties are also in the Search Settings category.

  
  Figure 54: Specifying Attribute to Use for Single-Field Quick Search
  
  

• Define JobTitle as the Descriptor Item for the List

  For each group you can specify the attribute JHeadstart will use to show context information. This attribute is called the descriptor item. The New JHeadstart Application Definition Wizard derives a default descriptor item for each group based on its underlying view object. If you want to use a different attribute, just set the Descriptor Item property yourself to the attribute name you prefer.

  As shown in Figure 55, set the Descriptor Item property of the Jobs group to JobTitle.

  
  Figure 55: Changing the Descriptor Item
  
  

4.4 Change How the Countries Group Gets Generated

We'll change the Countries group and its Locations2 child group to display as a table with a nested table display.

• Set Layout Style of Countries Group to 'Table' with Inline Table Overflow

  As shown in Figure 56, change the default Layout Style of the Countries group from table-form to just table instead. This will avoid having a drill-down detail form along with the table. Also, set the Table Overflow Style to inline as shown.

  
  Figure 56: Setting the Countries Group to Display as a Table (Without a Drill-Down Detail Form)

• Set the Countries Table to Display Five Rows per Page

  As shown in Figure 57, set the Table Range Size property of the Countries group to 5 rows.

  
  Figure 57: Changing the Default Number of Rows Displayed Per Page in a Table

• Set Child Locations2 Group to Display on Same Page as Parent

  As shown in Figure 58, check the Same Page? property of the Locations2 child group.

  
  Figure 58: Setting the Locations2 Child Group to Display on the Same Page as its Parent

4.5 Change How the Regions Group Gets Generated

We're going to change the Regions group, and its four child groups, to display as a tree with multi-level form editing by doing the following steps...

• Make Regions Edit Fields Layout in a Single Column

  As shown in Figure 59, set the Columns property of the Regions group to 1 in the Form Layout category.

  
  Figure 59: Setting Edit Form Fields to Layout in Single Column
  
  

• Disable Searching on Regions Group

  The user will see all the regions in the tree so searching won't be that useful in this case. We'll disable both Quick Search and Advanced Search for the Regions group by setting the Quick Search and Advanced Search properties both to none as shown in Figure 60.

  
  Figure 60: Disabling Search for Regions Group
  
  

• Shorten Display Width of RegionId

  Set the Width property of the RegionId item in the Regions group to 5 as shown in Figure 61.

  
  Figure 61: Setting the Display Width of an Attribute
  
  

• Change Regions Group to Display as a Tree with Edit Form

  As shown in Figure 62, start by setting the Layout Style property to tree-form, set the Data Collection (to be used for editing) to RegionsViewLookup, and set the Tree Data Collection to RegionsView1.

  
  Figure 62: Setting Up Regions to Display as a Tree
  
  

• Change Countries2 Group to Display as a Tree with Edit Form

  Next we setup the Countries2 child group to also display as a tree by setting the four properties as shown in Figure 63. Specifically, we set the Layout Style to tree-form, the Data Collection to CountriesViewLookup, the Tree Data Collection to CountriesView2, and the Descriptor Item to CountryName

  
  Figure 63: Setting up Countries2 Group as a Tree
  
  

• Repeat to Change Remaining Child Groups to Tree

  After selecting the 3rd-level child group Locations3, we set its Layout Style to tree-form, its Data Collection to LocationsViewLookup, the Tree Data Collection to LocationsView3. The Descriptor Item is already defaulted to City, so we don't need to change it.

  Next, after selecting the 4th-level child group Departments4, we set the Layout Style to tree-form, the Data Collection to DepartmentsViewLookup, the Tree Data Collection to DepartmentsView4. The Descriptor Item is already defaulted to DepartmentName, so we don't need to change it.

  Lastly, after selecting the 5th-level Employees5 child group, we set the Layout Style to tree-form, the Data Collection to EmployeesViewLookup, the Tree Data Collection to EmployeesView5. The Descriptor Item is already defaulted to LastName, so we don't need to change it.

  
  
  

4.6 Regenerate and Run the Application

At this point we're done making our goodly number of iterative, declarative changes to the application definition, so all that's left is to regenerate the application using the JHeadstart application generator, and running it to see the effects of our changes.

• Regenerate the Application

  From the JHeadstart Application Definition Editor, click the Run the JHeadstart Application Generator toolbar button (). Alternatively, you can select your ViewController project in the Application Navigator and choose Run JHeadstart Application Generator from the right-mouse menu. When completed, the Generation Finished alert will appear confirming the generation has finished successfully.

  
  
  

• Run the Application

  Run the ViewController project by selecting it in the application navigator and then pressing F11 (or clicking on the toolbar run icon ).

  
  
  

After regenerating, once the application is running in your default browser, we can try the following things to see how our changes to the application definition were realized in the generated pages...

• User Needs to Search for Desired Employees

  On the initial Employees tab, notice that employees no longer get auto-queried, as shown in Figure 64.

  
  Figure 64: User Needs to Search for Desired Employees
  
  

• User Warned to Refine Employees Search Criteria

  Using the Quick Search region for Employees, press the (Go) button without entering any search criteria. This would cause 107 rows to be queried, and since that is greater than our limit of 50, you get an error as shown in Figure 65.

  
  Figure 65: User Warned to Refine Employees Search Criteria
  
  

• Employee Table is Browse-Only with Detail Disclosure

  Set the Filter By field to LastName name, enter a search criteria of “p”, and press (Go). As shown in Figure 66, the Employees table is now browse-only and supports a Hide/Show button in each row to expand or collapse the visibility of the less frequently used detail information.

  Also note in the expanded detail information for Valli Pataballa that the prompt for the DepartmentId field is now Department as we set above.

  
  Figure 66: Employee Table is Browse-Only with Detail Disclosure
  
  

• Customized Child Group Tab Names Appear on Same Page as Employee Detail

  Selecting an employee with subordinates like Karen Partners, and clicking on the (Details) button to drill-down to her employees detail form, you can see as shown in Figure 67 that the "Subordinates" and "Managed Departments" child groups appear on the same page and stacked into tabs with our customized tab names.

  
  Figure 67: Child Groups Appear on Stacked Tabs on the Same Page with Custom Tab Names
  
  

• User Can Perform Advanced Search With Custom Criteria Treatment

  Click on the "Employees" breadcrumb navigation like (or on the top-level "Employees" tab) to return to the employees summary page. Then click the Advanced Search button next to the Quick Search area to see the advanced search criteria for Employees. Notice as shown in Figure 68 that we can set the query operator for LastName to "contains" and enter a criteria like "ta" to find any last name that contains those consecutive letters. We can enter low and high values like 2000 and 5000 for Salary to perform a "between" search on salaries. Clicking (Find) shows the matching rows. Note that the end-user can also choose between matching all of the supplied conditions or any of them with a simple radio button.

  
  Figure 68: Advanced Search with Custom Criteria Treatment
  
  

• User Can Sort on Any Column in Departments Table

  Click on the Departments tab. Notice that you can now click on any of the column headings in the table, like the DepartmentName column for example, and sort the table by that column value as shown in Figure 69. We actually didn't need to do anything above to enable this since the Column Sortable? property defaults to true on group items.

  
  Figure 69: User Can Sort on Any Column in Departments Table
  
  

• User Works with Employees in Department on Same Page, with Table Overflow Below and Add Row and Duplicate Row Buttons

  Still on the Departments tab, select a department, then click on the Details button. As shown in Figure 70, this now shows the department details, along with the relevant employees details on the same page with Add Row and Duplicate Row buttons to create new employees. Notice, too, that the EmployeeId, FirstName, and LastName display in the table, while the remainder of the details about the currently-selected table row appear in an "overflow area" below the table. As you select different rows in the Employees table, the items in the overflow area below automatically update (without refreshing the entire page) to display the correct values for the currently selected employee.

  
  Figure 70: User Works with Employees in Department on Same Page
  
  

• User Selects Job to Edit from Simple List

  Click on the Job tab and notice, as shown in Figure 71, that instead of the default table display to browse and select a Job to edit, the user now just selects the job name to edit from a simple list. Clicking on the (Edit) button brings you to the edit page for that job.

  
  Figure 71: User Selects Job to Edit from Simple List
  
  

• Countries Table Displays with Inline Locations Table

  As shown in Figure 72, visiting the Countries tab and searching for countries whose names start with "U", you can expand the inline table overflow area to see that the Locations table displays on the same page and as an inline, editable table.

  
  Figure 72: Locations for a Country Display on the Same Page in the Inline Table Overflow Area
  
  

• User Navigates Five-Level Hierarchy Using Tree Display

  Click the Regions tab, and you can drill down to find employees in departments in locations in countries in those regions. As shown in Figure 73, you can edit the data at any level.

  
  Figure 73: User Navigates Five-Level Hierarchy Using Tree Display
  
  

5 Create Department Manager List of Values (LOV)

In this step, we are going to change the dropdown list for selecting the manager of a department to be a popup list-of-values (LOV) window instead. When valid choices for a foreign key value are large in number, this kind of LOV window is more appropriate than a dropdown list. Specifically, we want to change the ManagerId dropdown list shown in Figure 74 to be a text field with a popup LOV instead.

Figure 74: EmployeeList Lookup as Dropdown List for Setting ManagerId

If we were to choose to show the ManagerId as a text field, the value that the user will see would be the numeric id of the manager which is not exactly what we want. It would be nicer for our end-users to show the manager's last name in the text field, and hide the numeric ManagerId value altogether. Then the user will see the last name, and popup the LOV to select last names from list. This will provide a lot better usability for our application. The following sections lead you through the few steps required with JHeadstart to accomplish this.

5.1 Add Manager Name to Departments Query

If we're going to show the name of a department's manager, we need to edit the definition of our DepartmentsView view object — back in our Model project — to include that bit of information.

1. Add Employees Entity Object to the DepartmentsView View Object

   Select the mydemo.model.DepartmentsView view object in the application navigator, and double-click it to launch the View Object Editor. On the Entity Objects panel of the editor, notice that the Departments entity object is already in use in this query. To add the Employees entity object as a second entity usage, as shown in Figure 75 select it in the Available list, and press (>) to shuttle it into the Selected list.

   Notice that by default the second entity object participating in this view object is marked as being Reference information and not updateable. While you can override this default setting, in this case the information we need to display from the Employees entity is read-only reference information — showing the department manager's last name — so we'll leave the default setting intact.

   
   Figure 75: Adding Employees Entity to DepartmentsView
   
   

2. Add LastName Attribute to the Attributes List

   On the Attributes panel of the editor, select the Employees entity's LastName attribute in the Available list, and press (>) to shuttle it into the Selected list as shown in Figure 76. Notice that the primary key attribute (EmployeeId) is also automatically added by the wizard.

   
   Figure 76: Adding the Employees.LastName Attribute to the List
   
   

3. Remove the Additional EmployeeId Key Attribute

   Since the manager-related information is contributing reference information to this view of department information, the DepartmentId attribute alone is enough to uniquely identify each row. Therefore, disable the Key Attribute setting of the additional EmployeedId attribute that JDeveloper enables by default.

   To do this, select the EmployeeId attribute in the Attributes section of the tree and uncheck its Key Attribute checkbox.

   
   

   NOTE:

   For more information on why this is a best practice, see section 7.3.1.4 Removing Unnecessary Key Attributes from Reference Entity Usages [11] in the ADF Developer's Guide for Forms/4GL Developers.

   
   
   
   

4. Rename the LastName Attribute to ManagerName

   To make it clearer that this employee last name is the name of the department's manager in this particular view object, we can rename the attribute from LastName to ManagerName. To do this, select the LastName attribute name indented under the Attributes node in the tree at the left, and type the new name attribute name into the Name field as shown in Figure 77.

   
   Figure 77: Renaming the LastName Attribute to ManagerName
   
   

5. Add the Employee Email Attribute and Rename to ManagerEmail

   Repeat steps 2 & 3 above to add the Email attribute from the Employee entity usage to the view object as well, and then rename this view attribute to ManagerEmail as shown in Figure 78 to make its name more meaningful.

   
   Figure 78: Renaming the Email Attribute to ManagerEmail
   
   

6. Change SQL Query to Outer Join to EMPLOYEES Table

   Since departments are allowed to have no manager, their ManagerId foreign key attribute value might be null. To insure that we query all departments, whether or not they have a corresponding employee as their manager, we need to change the SQL query for this DepartmentsView to be an outer join.

   To accomplish this, visit the Query panel of the editor, and type a "(+)" after the EMPLOYEE_ID column name the Where clause box as shown in Figure 79. Make sure there is a space between EMPLOYEE_ID and the "(+)" characters.

   
   Figure 79: Changing the DepartmentsView to an Outer Join

   Finally, click (OK) to accept all your changes to the DepartmentsView view object definition, then click the Save All toolbar button to save the changes.

   
   
   

5.2 Create a List of Values (LOV) Group

With our view object modified to include the ManagerName attribute, we're ready to define a new group to be used to layout the LOV window. Follow these steps...

• Add a New Instance of the EmployeesView View Object to the Data Model

  In order to ensure that any filtering performed by the employees list of values is independent from the list of employees in the Employees group's pages, we need to add a new instance of the EmployeesView view object to the data model for use by the LOV. To accomplish that, follow these steps:

  Visit the Data Model panel and expand the mydemo.model.queries package in the Available View Objects tree on the left.

  As shown in Figure 98:

  1. In your Model project, find the HRModule application module component in the mydemo.model package and double-click it to open the Application Module Editor.
  2. Select the EmployeesView view object in the Available View Objects list,
  3. Enter a view instance name of EmployeesLOV in the Name field below, and
  4. Click the (>) button to add the new view object instance with this name to the data model.

• Add a New Group

  Back in the JHeadstart Application Definition Editor, as shown in Figure 80, select the HRModule root node of the tree and click the Add a new component button () in the toolbar to add a new group.

  
  Figure 80: Adding a New Group

• Name the New Group and Configure as LOV for Employees

  As shown in Figure 81, set the Name property to EmployeesLOV, check the Use as List of Values? checkbox, set the Data Collection property to EmployeesLOV, set Advanced Search? to samePage, and set Quick Search? to dropDownList.

  
  Figure 81: Configuring a New LOV Group

• Synchronize the New Group's List of Items and Hide Most of Them in the Table Layout

  With the EmployeesLOV selected in the JHeadstart Application Definition Editor, set the Layout Style property to table as shown in Figure 82.

  
  Figure 82: Setting the LOV Group to Use a Layout Style of Table

  Then click the Synchronize button () in the toolbar, as shown in Figure 83 to refresh the list of items in the EmployeesLOV group from its related data collection.

  
  Figure 83: Refreshing the Item List for a Group

  Next, select all of the attributes that you do not want to appear in the LOV window layout and as shown in Figure 84, set their Display in Table Layout? property to false.

  
  Figure 84: Setting Items to Not Display in the LOV Group's Table Layout

• Set the Final Required Properties on the LOV Group

  To finish configuring the new EmployeesLOV group, as shown in Figure 85, set the Display Title (Plural) to Employees, the Descriptor Item to LastName, and uncheck all three of the Multi-Row Insert allowed, Multi-Row Update allowed, and Multi-Row Delete allowed checkboxes.

  
  Figure 85: Finalizing the Configuration of the New LOV Group

5.3 Use the LOV on ManagerName and Hide the ManagerId

• Refresh the Department Group's Item List

  Select the Departments group in the JHeadstart Application Definition Editor and as shown in Figure 86, click the Synchronize button in the toolbar to refresh its list of items. Notice that the ManagerName, EmployeeId, and ManagerEmail attributes we added to the view object in step 3a above now appear in the tree.

  
  Figure 86: Synchronizing Item List for the Departments Group After Adding View Object Attributes

• Hide the EmployeeId and ManagerId Items

  As shown in Figure 87, select the ManagerId and EmployeedId items and set their Display in Form Layout? and Display in Table Layout? properties to false.

  
  Figure 87: Hiding the Numeric ManagerId and EmployeeId Items

• Configure ManagerName to be an Editable LOV Field with Three Return Items

  Start by selecting the ManagerName and as shown in Figure 88, setting its Display Type to lov (list-of-values), its Update Allowed? property to true, and its Required? property to false.

  
  Figure 88: Setting ManagerName to Be an Editable LOV Item

  Add a nested list of values group to the ManagerName as shown in Figure 89 by selecting the Add List of Values item from the right-mouse menu on the ManagerName item.

  
  Figure 89: Adding a Nested List of Values Group

  Select the Choose an LOV Group node that is added as a child in the tree, and set its LOV Group Name property to EmployeesLOV as shown in Figure 90. Notice that the Use LOV for Validation property defaults to checked (or "on").

  
  Figure 90: Choosing an LOV Group for the Item's List of Values

  Configure the first list of values return item as shown in Figure 91 to have the LastName from the source LOV data collection be returned into the target Departments group's ManagerName item.

  
  Figure 91: Configuring the ManagerName Return Item

  It's also very important to remember to configure an LOV return item to return the primary key of the employee being selected into the (now hidden) ManagerId item so that the proper numerical foreign key value is set. So, as shown in Figure 92, use the Add Return Value item on the right-mouse menu of the EmployeesLOV to do this.

  
  Figure 92: Adding a Second LOV Return Item

Select the undefined <= undefined return item node that appears and as shown in Figure 93, set its Source Item property to EmployeeId and the Target Item property to ManagerId.

Figure 93: Configuring an LOV Return Item for the Primary Key of the Selected Employee

To also have the managers email returned when the value is selected, repeat the steps above to add a third LOV return item and set its Source Item property to Email and the Target Item property to ManagerEmail as shown in Figure 94.

Figure 94: Configuring a third LOV Return Item for the Managers Email

5.4 Regenerate and Run the Application

We're done setting up our list of values (LOV) field on ManagerName, so let's regenerate the application and run it. When generation finishes, run the application again by clicking on the ViewController project in the application navigator and press F11.

Figure 95 shows what the Departments tab looks like after we've used the Quick Search to find only departments whose DepartmentName contains "es".

Figure 95: ManagerName LOV Lookup in Departments Browse Page

The changes we made to the EmployeesLookup lookup definition above show up in the browse page with a ManagerName LOV field in every row. We can see that our outer join is working correctly, since the "Shareholder Services" department has no manager and it was included in the query results.

If you try typing a letter "p" in the ManagerName field for the "Shareholder Service" department — or alternatively, changing one of the existing manager names in a different department to the letter "p" — and then pressing Tab to leave the field, you'll see the LOV window pop-up automatically showing the filtered list of choices that start with the letter "p" as shown in Figure 96.

Figure 96: LOV Window Showing Filtered List of Matches

Back on the Departments browse page, if instead of typing just the letter "p" in one of the ManagerName fields, you type "ph" instead and Tab out of the field, you'll see another treat. Without bringing up the LOV window at all, the manager named "Philtanker" is automatically filled in, along with the manager's email id "HPHILTAN". This is the "Use LOV for Validation" behavior at work that JHeadstart enables by default for the list of values you generate. The selected data is returned from the LOV thanks to the "return items" we configured above.

Of course, you can also just click on the "searchlight" icon and pop-up the LOV window for you to filter and select the choice yourself.

If we drill-down to edit the details for a department, as shown in Figure 97 the same EmployeesLookup changes we made above result in showing a ManagerName LOV field in the Edit Departments form as well.

Figure 97: EmployeeLookup LOV Also Available in Edit Forms

6 Creating a Wizard Including a Shuttle Control

In this step we will generate a wizard consisting of four pages to enter a new employee. The fourth wizard page will contain a shuttle control to assign subordinates to the new employee if applicable.

6.1 Add View Object Instances to the Data Model to Support the Wizard and Shuttle

To ensure that the employee creation wizard and its shuttle control behaves in a way that is independent of other employee and subordinate data queried in the application, we can add an additional instances of the appropriate view object components to the data model of our HRModule, and then use these new view object instances as the data collections for the groups involved in the wizard. To accomplish this, follow these steps:

• Add a New Instance of the EmployeesView View Object to the Data Model

  In your Model project, find the HRModule application module component in the mydemo.model package and double-click it to open the Application Module Editor.

  Visit the Data Model panel and expand the mydemo.model.queries package in the Available View Objects tree on the left.

  As shown in Figure 98:

  1. Select the EmployeesView view object in the Available View Objects list,
  2. Enter a view instance name of CreateEmployeesView in the Name field below, and
  3. Click the (>) button to add the new view object instance with this name to the data model.
  
  Figure 98: Adding a New Instance of the EmployeesView Named 'CreateEmployeesView'

• Add a New Detail View Object for New Subordinates

  When creating a new employee, we want to optionally be able to add a related set of subordinates that have the new employee as their manager. To have this set of subordinates be independent of the other subordinate queries in the data model, we'll add a new detail instance of the EmployeesView based on the EmpManagerFKLink view link that was created by default when JDeveloper initially reverse-engineers ADF business components from the tables. To perform this task, as shown in Figure 99 do the following:

  1. Select the CreateEmployeesView view instance in the Data Model to be the existing parent view,
  2. Select the EmployeesView via EmpManagerFKLink in the Available View Objects list
  3. Enter a view instance name of NewSubordinates in the Name field below, and

  4. Click the (>) button to add the new view object instance with this name to the data model.

     
     Figure 99: Adding a NewSubordinates Detail View Instance with CreateEmployeesView as Master

     After performing these steps, your Data Model tree will look like what you see in Figure 100. Click (OK) to dismiss the Application Module Editor.

     
     Figure 100: Data Model with New Master/Detail View Instances

• Add an Instance of the EmployeesView for Use by the Subordinates Shuttle

  The shuttle control we'll use to assign subordinates to the newly created employee requires a list of available employees. In practice this list of available choices will be some appropriately filtered list of employees based on some application-specific criteria that make them "available" for assignment. However, to keep things simpler for the tutorial, we'll just add another instance of the existing EmployeesView to serve this purpose.

  To accomplish this task, do the following:

  1. Select the EmployeesView view object in the Available View Objects list,
  2. Enter a view instance name of EmployeesAvailableToAssign in the Name field below, and
  3. Click the (>) button to add the new view object instance with this name to the data model.

We're done making the required data model changes, so click (OK) to accept the changes, then click the Save All button in the JDeveloper main toolbar to save them.

6.2 Create and Configure a New EmpWizard Group

To create an configure a new group with a wizard layout, perform these steps:

• Create a New EmpWizard Group by Copying an Existing One

  In the JHeadstart Application Definition Editor, copy the Employees group using the Duplicate Group option in the right-mouse menu.

  Set its Name property (in the Identification group) to "EmpWizard" to rename the new group.

  Set the Data Collection property of the new EmpWizard group to CreateEmployeesView.

• Change the EmpWizard to Come After the Existing Employees Group

  In the HRModule tree on the left of the JHeadstart Application Definition Editor, drag the EmpWizard node and drop it after the existing Employees node to resequence it.

• Rename the Copied Employees2 Detail Group to Subordinates

  Select the EmpWizard group's detail group named Employees2 and set its Name property to Subordinates to rename it.

  Set the Data Collection property of the renamed Subordinates detail group to NewSubordinates.

• Remove the Copied Departments2 Detail Group

  The EmpWizard group's copied Departments2 detail group won't be needed for this task, so select it in the tree and click the Remove a component () toolbar icon to remove it. After performing these steps, your JHeadstart Application Definition Editor should look like Figure 101.

  
  Figure 101: New EmpWizard Group with Subordinates Detail Group

• Finish Configuring the New EmpWizard Group

  Set the following properties of the new EmpWizard group:

  Property Category	Property Name	Set to Value
  Labels	Tabname	"Employee Wizard"
  Labels	Display Title (Singular)	"Employee"
  Group Layout	Layout Style	form
  Group Layout	Wizard Style Layout?	(checked)
  Search Settings	Quick Search?	none
  Search Settings	Advanced Search?	none
  Search Settings	Auto Query?	(unchecked)
  Operations	Single-Row Update Allowed?	(unchecked)
  Operations	Single-Row Delete Allowed?	(unchecked)

6.3 Create and Configure Three Item Regions for the EmpWizard Group

To define three item regions and assign group items to them, follow these steps:

• Define Three Item Regions in the EmpWizard Group

  As shown in Figure 102, use the Add Child > Item Region option in the right-mouse menu on the Regions folder of the EmpWizard group.

  
  Figure 102: Defining a New Item Region for the EmpWizard Group

  Set the Name of the new item region to Identification, and set its Title property to the same value Identification.

  Repeat this step to define two additional item regions named and titled Functional and Financial. When done, your tree will look like Figure 103.

  
  Figure 103: EmpWizard Group with Three Item Regions

• Assign EmpWizard Group Items to Respective Item Regions

  Expand the EmpWizard group's Items folder and drag and drop to assign the following EmpWizard group items to belong to the indicated item region. Remember that you can use Ctrl or Shift while selecting the items to perform multiple section before dragging.

  Drag the EmpWizard Group Items...	...and Drop in This Item Region
  EmployeedId, FirstName, LastName, Email	Identification
  Salary, CommissionPct	Financial
  PhoneNumber, HireDate, JobId, ManagerId, DepartmentId	Functional

  When done, your application definition will look like what you see in Figure 104.

  
  Figure 104: EmpWizard Group Items Partitioned into Three Item Regions

• Set the Region Layout Style to Use Separate Pages

  Select the Regions folder as shown in Figure 105 and set its Layout Style property to separatePages.

  
  Figure 105: Setting EmpWizard Regions to Layout as Separate Pages

6.4 Configure Subordinates Detail Group to Use Shuttle

Select the EmpWizard group's detail group named Subordinates and set the following properties on it:

Property Category	Property Name	Set to Value
Group Layout	Layout Style	parent-shuttle
Group Layout	Same Page?	(unchecked)
Labels	Tabname	"Unassigned"
Labels	Display Title (Plural)	"Assign Subordinates"
Labels	Display Title (Singular)	"Assigned"

Like a dropdown list or radio group, a shuttle control presents the user with a list of available choices. This list contains a Meaning Attribute that reflects what the end-user will see in the list, and a Value Attribute that represents the underlying value in the database row. In your JHeadstart application definition, a named domain defines a list of available choices that can either be a static set (e.g. Open, Pending, Closed) or a dynamic set based on a view object's query results. When you ran the New JHeadstart Application Definition Wizard earlier in the tutorial, the JHeadstart application generator automatically generated a number of dynamic domains to support the selection of foreign key values from dropdown lists wherever it noticed those foreign keys existed.

Since we introduced a new EmployeesAvailableToAssign view object instance to provide the list of available choices for the "Subordinates" shuttle above, the last two steps in configuring the shuttle require:

• Defining a new dynamic domain for this data collection, and then
• referencing that new domain in the Subordinate group's Domain for Unselected List in Shuttle property.

To accomplish this task, perform these steps:

• Create a New Domain for the Shuttle's Available List

  As shown in Figure 106, select the Domains folder in the JHeadstart Application Definition Editor, click the Add a new component () toolbar button, and choose Dynamic Domain from the list.

  
  Figure 106: Creating a New Dynamic Domain

  Configure the new domain by setting the following properties:

  Property Category	Property Name	Set to Value
  General	Domain Name	"ShuttleEmployeesAvailableList"
  Query Settings	Data Collection	EmployeesAvailableToAssign
  Display Settings	Value Attribute	EmployeeId
  Display Settings	Meaning Attribute	LastName

  Once you've done this, your new domain should look like what you see in Figure 107.

  
  Figure 107: Configuring the Properties of the New Domain for the Shuttle Available List

• Set the Shuttle's Unselected List to Use the New Domain

  As shown in Figure 108, expand the EmpWizard group, select the Subordinates detail group, and set its Domain for Unselected List in Shuttle property to ShuttleEmployeesAvailableList.

  
  Figure 108: Referencing the New Domain as the Shuttle's Unselected List

6.5 Regenerate and Run the Application

We're done defining the new Employee wizard, so regenerate the application and run it. When generation finishes successfully, run the application again by clicking on the ViewController project in the application navigator and press F11.

Clicking on the Employee Wizard tab in the browser, you'll see the first page of the wizard as shown in Figure 109, ready to collect the information related to the Identification step of the process.

Figure 109: First Step in the Four-Step Wizard Layout

Clicking (Next) to proceed onto subsequent steps, you can enter the information for the Functional step in the process as shown in Figure 110.

Figure 110: First Step in the Four-Step Wizard Layout

Clicking (Next) to enter the Financial information in step 3, and clicking (Next) again, you can see that the last step of the wizard is the Subordinates step that we configured to generate as a shuttle. As shown in Figure 111, you can select a few subordinates, then click (Finish) to commit the transaction.

Figure 111: Shuttle Control to Assign Subordinates to a New Employee

7 Using Stacked Tabs for Table Overflow Items

Another use for the item regions we saw above is to organize items into stacked tabs. In this section will configure two item regions for the Employees3 detail group of the top-level Departments group and drag and drop some of its items into these item regions, which we'll configure to generate as stacked tabs on the same page as the parent group. To accomplish this task, follow these steps:

• Create Two Item Regions for the Employees3 Detail Group

  In the JHeadstart Application Definition Editor, expand the top-level Departments group, its Employees3 detail group, and select its Regions folder. Using the Add a new component toolbar button () or the right-mouse menu, create two new item regions named Functional and Financial. For each one, set their Title property to be the same as their Name property as we did above.

• Configure a Stacked Layout Style for the Regions

  Select the Regions folder as shown in Figure 112 and set its Layout Style property to stacked.

  
  Figure 112: Two New Item Regions for the Employees3 Group

• Drag and Drop to Associate Some Group Items with Item Regions

  Expand the Employees3 group's Items folder and drag and drop selected attributes into the two new item regions as follows:

  Drag the Employees3 Group Items...	...and Drop in This Item Region
  Email, PhoneNumber, HireDate, JobId, ManagerId, DepartmentId	Functional
  Salary, CommissionPct	Financial

• Change the Table Overflow Style to Layout on the Right

  The table overflow area can be inline, below, or to the right of the table layout. Select the Employees3 group and as shown in Figure 113, set the Table Overflow Style to right.

  
  Figure 113: Setting the Table Overflow Style for Employees3 Group to 'Right'

  After regenerating and running the application again, as shown in Figure 114 the Edit Departments detail page now features the selected overflow elements for the currently selected row in stacked tabs named "Functional" and "Financial" off to the right. Try changing the current row in the Employees table and notice that the current employees detail information in the overflow area at the right are automatically updated without refreshing the browser page. This is another example of ADF Faces partial page rendering at work.

  
  Figure 114: Table Overflow Items Show Current Employee in Stacked Tabs at Right

8 Adding a Conditionally Dependent Field

The ADF Faces components that JHeadstart application generator uses for your web tier pages cleverly combine Asynchronous JavaScript, XML, and Dynamic HTML to deliver a much more interactive web client interface for your business applications. In ADF Faces, the feature is known as partial page rendering because it allows selective parts of a page to be re-rendered to reflect server-side updates to data, without having to refresh and redraw the entire page. This combination of web technologies for delivering more interactive clients is known more popularly by the acronym AJAX ^[12]. ADF Faces supports this powerful feature for any JavaServer Faces (JSF) page with no coding. JHeadstart automatically configures the necessary properties on the controls to enable a maximal use of this great feature. We've seen a few examples of this AJAX-style partial-page rendering in previous sections of the tutorial. Here we'll study a final example that involves using it to enable dynamically-changing, conditionally-dependent fields.

Sometimes, one field value (or its enabled status) might depend on another field. JHeadstart makes it simple to generate pages that support this kind of conditionally-dependent field. For example, imagine that the commission percentage of an employee only is relevant if they are an Account Manager. In this section we'll configure a simple example to implement the disabling of the CommissionPct item in the Employees group unless the value of the JobId is equal to 'AC_MGR'. To accomplish this task, follow these steps:

• Conditionalize the Value of the Disabled Property Using an Expression

  In the JHeadstart Application Definition Editor, expand the top-level Employees group, its Items folder, and select the CommissionPct item. As shown in Figure 115, set its Disabled? property to the expression value:

  #{$DEPENDS_ON_ITEM_VALUE$ != 'AC_MGR'}

  The token $DEPENDS_ON_ITEM_VALUE$ gets substituted by the JHeadstart application generator so that the expression ends up referencing the correct value of the item on which the current item depends. We'll setup this item dependency next...

• Set the CommisionPct Item to Depend on the JobId Item

  Set the Depends on Item property of the CommissionPct item to JobId. After doing this, your application definition will look like Figure 115.

  
  Figure 115: Using a Conditional Disabled Expression Referencing a Dependent Item

After regeneration and running the application, in the Employees tab, if you use the Quick Search area to find all employees whose LastName starts with the letter H, and then drill down to the details, you can navigate between employees like Michael Hartstein and Shelly Higgins to notice that the CommissionPct field on the screen as disabled for Michael, as shown in Figure 116, but enabled for Shelly (whose JobId = 'AC_MGR').

Figure 116: CommissionPct is Disabled for Employees Who Are Not Account Managers

Perhaps even more interesting is the fact that the screen updates dynamically as you change the value of the dependent JobId field. For example, if you use the dropdown list to change the JobId of an employee who is currently not an account manager to have the new value of AC_MGR, you'll see that the CommissionPct field becomes enabled automatically, without refreshing the entire web page.

9 Generating a Graph and Summary Information

In this section we will add some Business Intelligence functionality to the top-level Jobs group and its Employees3 detail group. Assume an HR employee who needs to evaluate salary differences for employees with the same job. For this task it is convenient to see the average salary for a job, as well as a graph visualizing the differences in salary within a job. To add this functionality to our application, follow these steps:

• Configure the Employees4 Detail Group to Display on the Same Page with Overflow Right

  In the JHeadstart Application Definition Editor, expand the top-level Jobs group, and select its Employees4 detail group. Check the Same Page? checkbox, and set the Table Overflow Style property to right.

  
  Figure 117: Employees4 Group on Same Page with Overflow Right

• Do not Allow Insert nor Delete in Employees4 Detail Group

  Uncheck the Multi-Row Insert allowed? and Multi-Row Delete allowed? checkboxes, and clear the value of the New Rows property.

  
  Figure 118: Only Update Allowed in Employees4 Group

• Make Only Salary Updateable in Employees4 Detail Group

  Select all items in the Employees4 group using Shift-Click, and unselect the Salary item using Ctrl-Click. Set the Update Allowed? property for all selected items to false.

  
  Figure 119: Only Salary Updateable in Employees4 Group

• Only Display EmployeeId, FirstName, LastName and Salary in Table

  Using drag and drop, move the Salary Item up to display right below the LastName item. Then select all items starting with Email up to DepartmentId and set the Display in Table Layout? property for the selected items to false.

  
  Figure 120: Limit Items Displayed in Table Layout

• Display Salary Average at Bottom of Table

  Select the Salary Item and set the Display Summary Type in Table property to average.

  
  Figure 121: Display Salary Average

• Adding the Graph Item

  Right-mouse-click on the Salary Item and choose Duplicate Item from the popup window.

  
  Figure 122: Duplicating the Salary Item

  A new item named CopyOfSalary is added to the group. Move this new item using drag and drop to display right below the Salary item. Set the following properties for the CopyOfSalary item:

  Property Category	Property Name	Set to Value
  General	Name	"SalaryGraph"
  General	Display Type	graph
  Display Settings	Display in Table Layout	false
  Display Settings	Display in Table Overflow Area?	true
  Display Settings	Width	"300"
  Display Settings	Height	"200"
  Display Settings	Depends on Item(s)	Salary

  After you have aplied the above property settings the SalaryGraph should look like this:

  
  Figure 123: The New Salary Graph Item

• Generating and Configuring the Graph

  You are done with the required changes in the Application Definition Editor to generate the graph. You can now run the JHeadstart Application Generator again. When the generator is finished, you will notice a new file that has been added to your JDeveloper project. This file, named BIGraphDefEmployees4SalaryGraph.xml, is automatically opened in the JDeveloper Graph Editor. Using the Graph Editor, you can set the graph type, for example bar, line or pie chart as well as the visual appearance of the graph. The default bar graph suits our purpose, so we will only change the visual appearance of the graph by clicking the two right-most buttons in the Graph Editor toolbar. These settings result in a nice 3D-style rendering of the graph as shown in the picture below.

  
  Figure 124: The Graph Editor in JDeveloper

• Testing the Graph Page

  When you run the application, and select a job to edit in the Select Jobs page, a page that looks like this should appear:

  
  Figure 125: The Graph Editor in JDeveloperNotice the average salary displayed in the total row in the Employees table. Once again, this page uses ADF Faces Partial Page Rendering to update the salary average and the graph. If you change the salary of one of the employees, and tab out the salary field, you will see that the salary average and the graph are updated immediately.

10 Using "Deep Linking" to Support Targeted Hyperlinks

Sometimes you might want to allow a user to navigate to a page in your application to display or edit a particular row that they identify using an URL parameter. For example, for a page that edits jobs, you might want to allow a jobId URL parameter like this to indicate what job to display/edit:

http://yourserver.com/MyDemo/faces/pages/SelectJobs.jspx?jobId=AC_MGR

Since the page to which you allowing direct access like this might be "deep inside" your web application page hierarchy, this kind of direct link support is known commonly as "deep linking".

In this step, we will use JHeadstart's deep link support in combination with a custom generator template to generate the JobId in the Employees group table as a hyperlink that navigates to the "Job Edit" page querying the proper Job row in the process.

To accomplish this task, follow the steps in the sections below.

10.1 Configure the Job Group for Deep Linking

In the JHeadstart Application Definition Editor, start by enabling "Expert Mode" by clicking the "chess pawn" toolbar button (). It will toggle to a "chess king" icon () to indicate you are in "Expert Mode".

Select the Jobs group and in the Deep Linking category and set its:

• Type of Deep Linking property to Query By Key Value.
• Deep Linking Key Expression property to the expression: #{param.jobId}

10.2 Changing JobId to a Hyperlink Using the JDeveloper Visual Editor

In this step, after moving the JobId back to the main table for the Employees group, we'll customize the generated page manually to show how this is possible. The simple result we want to achieve is to change how the JobId item in the Employees group appears to the end user, making it a clickable hyperlink instead of a dropdown list.

So, start by moving the JobId back to the main Employees table and regenerating the application by following these two steps:

• Move the JobId Item Back to the Main Employees Table Layout

  In the JHeadstart Application Definition Editor, select the JobId item in the top-level Employees group and set its Display in Table Layout? to true and its Display in Table Overflow Area property to false. This will cause the JobId item to display again in the main table instead of in the overflow area.

• Regenerate the Application, Without Running It Yet

  Run the JHeadstart application generator to generate the latest version of the application's ViewController artifacts from the JHeadstart application definition, however don't run the application yet since we're not done with this step.

  Click the Save All button in the JDeveloper main toolbar to save all the generated changes.

Now, we'll proceed to make some manual modification to the generated EmployeesTable.jspx page. Since JHeadstart generates pages that are the same as ones you could have created by hand using JDeveloper itself, after you have gotten the generated pages as close to your final requirements as possible, you can use the JDeveloper visual editor and other rapid application development facilities to tailor the generated result. Once you've customized a generated page you can either:

• Change the corresponding group setting in the JHeadstart Application Definition Editor to avoid having the JHeadstart application generator ever regenerate the page, or as we'll see later in the tutorial,
• "Teach" the JHeadstart application generator how to generate your customized output by creating and using generator templates.

To change the generated dropdown list for JobId to be a hyperlink, do the following:

• Open the EmployeesTable.jspx Page in the Visual Editor

  As shown in Figure 126, find the EmployeesTable.jspx page in the pages subdirectory of the Web Content root directory in the ViewController project. Then double-click it to open the visual editor.

  
  Figure 126: The Generated EmployeesTable.jspx Page in the ViewController Project

• Convert the JobId Control in the Table to a Hyperlink

  As shown in Figure 127, select the JobId UI control inside the table column and choose Convert from the right-mouse menu.

  
  Figure 127: Converting the JobId Control to a Hyperlink

  In the Convert SelectOneChoice dialog that appears, select the CommandLink component as shown in Figure 128 and click (OK). When the subsequent Confirm Convert dialog appears, click (OK).

  
  Figure 128: Converting the JobId Control to a Hyperlink

  As shown in Figure 129, do the following:

  1. Select the JobId control you just converted in the visual editor,
  2. In the Structure Window, select the three child nodes "left over" from the previous dropdown control,
  3. Delete these extraneous selected elements using the Del key or the Delete option in the right-mouse menu
  
  Figure 129: Deleting Extraneous Child Nodes of the CommandLink After Conversion

• Configure Properties of the New Command Link

  Select the new commandLink component and in the Property Inspector set its:

  • Text property to the expression: #{row.JobId}
  • Action property to DeepLinkJobs using the convenient dropdown list.
  
  

  TIP:	The DeepLinkJobs JSF navigation case was added in the previous generation run, after we set up the deep linking for the Jobs group.

  
  

• Add a URL Parameter to the CommandLink to Pass the JobId

  To add a URL parameter to the commandLink component, we need to insert a child param component from the JSF Core tag library. To do this, as shown in Figure 130, select the commandLink in the visual editor and select Insert inside CommandLink > JSF Core > Param from the right-mouse menu.

  
  Figure 130: Inserting a JSF Core param Component as a Child of the Command Link

  When the Insert Param dialog appears, enter jobId for the parameter Name field, and enter the expression #{row.JobId} for the parameter Value field as shown in Figure 131, then click (OK).

  
  Figure 131: Setting the Name and Value of the CommandLink's Param Component
  

  TIP:	If you get an error telling you that you need to fill in the Value field, try typing an extra, trailing space character as the end of the Value expression and then try clicking the (OK) button again.

  
  

10.3 Run the Application to Test the JobId Hyperlink

Without regenerating, just run the application to test the change we've prototyped in the EmployeesTable.jspx page. As shown in Figure 132, the JobId attribute now displays as a hyperlink.

Figure 132: JobId Now Appears as a Hyperlink in the EmployeesTable Search Page

Clicking on a the hyperlink for the FI_ACCOUNT for employee Luis Popp jumps straight to the Edit Job page with that specific job selected for editing as shown in Figure 133, illustrating the runtime use of the "deep linking" feature.

Figure 133: Clicking JobId CommandLink "Deep Links" to the Edit Job Page for that JobId

11 Preserving Customizations Using Generator Templates

Once you've prototyped a customization to a generate page, instead of disabling future generation of the corresponding JHeadstart group in the application definition, you can also "teach" the JHeadstart application generator how to generate your preferred layout in the future by creating a custom generator template. This enables you to have the JHeadstart application generator generate the page in a customized way going forward, allowing you to continue making iterative application definition changes to the corresponding group.

In this step we'll illustrate an example of this second, more powerful approach. We will create a new generator template based on the customization we made in the previous section to the JobId item's generated control in the EmployeesTable.jspx page.

11.1 Moving the Customization into a Generator Template

We will now move the customization of the JobId column to a custom template. We'll do this by creating a copy of the default template used to generate the JobId item and then applying our customizations to it. To perform this task, follow these steps:

• Create a New JobIdColumn Table Based on an Existing Template

  In the ViewController project, expand the Resources folder and as shown in Figure 134 select the tableDropDownList.vm template in the ./default/item/table subdirectory. This is the default template used to generate JobId.

  
  Figure 134: Selecting an Existing Template to "Clone"

  Then choose File | Save As... from the main menu to save this existing template as a new name of JobIdColumn.vm.

  
  

  TIP:	In general, it's easy to know what template is being used to generate a given part of a page because the generated source contains helpful comments indicating what template was used to generate it.

  
  

• Open the New Template in the Code Editor

  Double-click the new JobIdColumn.vm template to open it in the code editor. You'll see that it currently looks like this:

  <af:column  #ITEM_ID_IN_COLUMN() #ITEM_SORTABLE()  #ITEM_WRAP()
           #ITEM_SORT_PROPERTY() #ITEM_ALIGNMENT()>
  <f:facet name="header">
    <af:outputLabel #COLUMN_HEADER_LABEL() #ITEM_SHOW_REQUIRED_IN_TABLE()
                    #COLUMN_HEADER_TEXT_STYLE_CLASS()/>
  </f:facet>
  <af:selectOneChoice  #ITEM_ID_IN_TABLE() #ITEM_VALUE_IN_TABLE()
                       #ITEM_RENDERED_IN_TABLE() #ITEM_PARTIAL_TRIGGERS()
                       #ITEM_REQUIRED_IN_TABLE() #ITEM_READ_ONLY_IN_TABLE() 
                       #ITEM_DISABLED_IN_TABLE() #ITEM_HINT()
                       #DEPENDS_ON_ITEM_PROPS_TABLE() #UNSELECTED_LABEL()>
    #JHS_PARSE($JHS.current.item.domain.optionsTemplateIdentifier ${JHS.current.model})
  </af:selectOneChoice>
</af:column>   

• Copy the Prototyped CommandLink Element into the New Template

  We want to copy the tags for the <af:commandLink> we prototyped in the EmployeesTable.jspx page and paste them into the new template. To do this:

  1. Activate the tab for the EmployeesTable.jspx visual editor,
  2. Drag the splitter shown in Figure 135 down to split the visual editor in two, showing the Design view in the upper half of the window, and the Source view in the lower half of the window.
  3. Select the Email element in the Design view, then select the JobId hyperlink again. This will cause the corresponding tags that represent that commandLink component to be highlighted in the Source editor
  4. Select the highlighted lines in Source view from the opening <af:commandLink> tag through the closing </af:commandLink> tag and choose Copy from the right-mouse menu to copy these tags to the clipboard.
  
  Figure 135: Selecting the Tags in the Split Source View for the JobId CommandLink Component

• Paste the CommandLink Tags to Replace the SelectOneChoice Tags

  Activate the JobIdColumn.vm template editor again, select the text from the <af:selectOneChoice> down through (and including) the closing </af:selectOneChoice> tag, then choose Paste from the right-mouse menu to paste the <af:commandLink> tags in the clipboard to replace the selection. The template should end up looking like this (possibly with extra whitespace):

  <af:column  #ITEM_ID_IN_COLUMN() #ITEM_SORTABLE()  #ITEM_WRAP()
           #ITEM_SORT_PROPERTY() #ITEM_ALIGNMENT()>
  <f:facet name="header">
    <af:outputLabel #COLUMN_HEADER_LABEL() #ITEM_SHOW_REQUIRED_IN_TABLE()
                    #COLUMN_HEADER_TEXT_STYLE_CLASS()/>
  </f:facet>
  <af:commandLink id="EmployeesJobId" immediate="true"
                  text="#{row.JobId}" action="DeepLinkJobs">
    <f:param name="jobId" value="#{row.JobId}"/>
  </af:commandLink>                       
</af:column>  

• Save the New Template

  Click the Save All toolbar button in the main menu to save your changes to the template.

11.2 Using the New Template for the JobId Column

Now that we've turned our prototyped change into a custom template, we just need to tell the JHeadstart application generator to use this custom template whenever it generates the JobId item in the Employees group.

Back in the JHeadstart Application Definition Editor, select the JobId item of the top-level Employees group.

As shown in Figure 136, click the Templates tab and set the TABLE_DROP_DOWN_LIST property in the Table Items category to the relative path to the custom template: default/item/table/JobIdColumn.vm

Figure 136: Setting a Custom Template for Employees.JobId When Used as a Dropdown List in a Table

11.3 Regenerate and Run the Application

Now you can rerun the JHeadstart application generator and run the application again. You'll see that manually-prototyped feature is now something you can regenerate automatically!

12 Applying Custom Skins to Change Look and Feel

You have undoubtedly noticed that the ADF web application we've built in this tutorial has a consistent look and feel on all the pages. This consistency is an important ingredient in delivering the attractive and easy-to-use experience that all application developers want for their end users. You might have also noticed that the pages we've built resemble those in the self-service web applications of the Oracle e-Business Suite. By default, ADF Faces pages are configured to have this Oracle Browser Look and Feel ^[14]...and with good reason. Over 4000 developers inside Oracle who implement and enhance the e-Business Suite use Oracle ADF to build these self-service web applications, the same key technologies we're using in this tutorial.

But if it's not your style to have your application look like the Oracle e-Business Suite, no worries. The ADF Faces technology supports changing the look and feel of all your pages in a consistent way by applying a skin ^[15]. As we'll see, applying a skin does not require any changes to the application pages that you've built. It's just a configuration setting.

ADF Faces comes with two built-in skins, oracle and minimal. The oracle skin is the default. The minimal skin provides an alternative look that is simpler and that tries to minimize the use of downloaded images.

To change the look and feel of our tutorial application...

• Find the adf-faces-config.xml file under the WEB-INF directory of your ViewController project's Web Content folder.
• Double-click the adf-faces-config.xml file in the application navigator to view it in the code editor.

• Find the <skin-family> tag in this XML configuration file and notice that it looks like this:

  <adf-faces-config xmlns="http://xmlns.oracle.com/adf/view/faces/config">

  <skin-family>oracle</skin-family>

</adf-faces-config>

• To change to use the minimal look and feel, type over the oracle skin family name and make it say minimal instead, so that your adf-faces-config.xml file looks like this:

  <adf-faces-config xmlns="http://xmlns.oracle.com/adf/view/faces/config">

  <skin-family>minimal</skin-family>

</adf-faces-config>

• Then save the file

The first thing we notice is that, as shown in Figure 137, the JDeveloper visual designer for the EmployeesTables.jspx page changes to show the page in the minimal look and feel. This underscores how the visual page designer really does offer a true "What You See Is What You Get" (WYSIWYG) environment.

Figure 137: Visual Designer Updates to Reflect Custom Skin

By rerunning the application, as shown in Figure 138 you can experience the effect of changing to the minimal skin at runtime as well. All of our application's functionality works the same as it did before, but the look and feel has been consistently modified with one edit to a configuration file.

Figure 138: Tutorial Application Running with "Minimal" Skin

Keep in mind that if neither of the two built-in skins suits your fancy, you can also create your own custom ADF Faces skins. To more radically change the look and feel of your application, for example to seamlessly match the look and feel of an existing site, you can use ADF Faces skinning in combination with a set of custom generator templates.

13 Adding a Validation Rule and Customizing Error Reporting

In this section of the tutorial, we'll add some declarative validation logic to one of our business domain objects. This will illustrate how business logic and user interface are cleanly separated in an Oracle ADF application, as well as show how the errors are displayed by default to the end-user.

13.1 Defining Some Declarative Validation Rules

Using Oracle ADF our business validation logic is nicely encapsulated inside the entity objects that represent our business domain objects. You can capture a number of aspects of business domain validation declaratively. Here we'll illustrate two simple examples of enforcing that an attribute is mandatory, and that its value lie within a certain numerical range.

• Make an Employee's Salary Mandatory

  In your Model project, find the Employees entity object in the mydemo.model.entities package and double-click it to edit it. In the Entity Object Editor, as shown in Figure 139 expand the Attributes node in the tree at the left and select the Salary attribute. Then, in the panel on the right, check the Mandatory checkbox.

  
  Figure 139: Making the Salary Attribute Mandatory

• Validate that Salary is Between 1 and 25000

  While still in the Entity Object Editor on the Employees entity, select the Validation panel. As shown in Figure 140, select the Salary attribute and click the (New...) button to add a new validation rule.

  
  Figure 140: Adding a New Attribute Validation Rule

  In the Add Validation Rule for: Salary dialog, as shown in Figure 141, select RangeValidator from the Rule dropdown list. Enter a Minimum Value of 1 and a Maximum Value of 25000. Finally, type in an error message like Salary must be between 1 and 25000, then click (OK) to add the rule.

  
  Figure 141: Configuring the Declarative Range Validation Rule

  As shown in Figure 142, any validation rules you've added to attributes or at the entity object level appear in the tree display on the validation panel.

  
  Figure 142: All Rules Appear in Validation Panel

Finally, click (OK) to dismiss the Entity Object Editor.

13.2 Rerunning the Application to See Validation Rules in Action

At this point, let's re-run the application to see the effect of having added two simple validation rules. As we've done before, select the ViewController project in the Application Navigator and press F11 to run.

When the initial Employees tab appears, enter a LastName of King in the quick-search Filter By field and click (Go) to find the employees with a last name of King. Select the employee "Steven King" and click the (Details) button to edit the data.

First try blanking out the existing value of Salary and pressing the (Save) button. You'll see an error as shown in Figure 143.

Figure 143: Mandatory Validation of Salary Now Automatically Enforced

Next, try to enter a Salary value of 25001 and click (Save) again. Since this value is outside of the valid range, as shown in Figure 144 we see that the end-user is shown the custom error message we provided when we added the range validation rule on the Employee entity object's Salary attribute.

Figure 144: Validation Errors Presented Automatically to User

Under the covers, what makes this work is the automatic coordination that's occurring between the front-end ADF Faces components and the view objects in the back-end ADF application module. Those view objects, in turn, coordinate with your underlying busing domain layer — realized as a set of ADF entity objects — which encapsulate the business validation. Any errors raised by the business layer automatically "bubble up" back to the user interface and are presented to the user. Again — as we've seen throughout this tutorial — all of this infrastructure is provided for you by the Oracle ADF framework so you don't have to write the "application plumbing" code.

13.3 Declaratively Customizing the Way Errors are Reported

If you take a closer look at the error message displayed in Figure 144, you may have noticed that it displayed an odd-looking error code prefix of "JBO-Salary_Rule_0" before the actual error message. This is not too user-friendly, so let's see what we can do about that.

When generating your web application artifacts, JHeadstart makes clever use of the JavaServer Faces managed bean facility. This built-in JSF feature allows developers to use simple XML files to declaratively configure any Java beans their application may need to reference, and also allows them to declaratively initialize any of the properties in those beans to a fixed or dynamic value.

The JSF configuration file that contains the bean definition related to how errors are reported is called the JhsCommon-beans.xml file. As shown in Figure 145, if you:

• Double-click on this XML file in the Application Navigator,
• Visit the Overview tab in the editor
• Select the Managed Beans section and specifically the errorReportingUtils managed bean in the list
• Expand its Managed Properties section to see its declaratively configured properties, and
• Select the showJBOErrorCode property,

you can change its value from true to false.

Figure 145: Changing Value of a Managed Bean Related to Error Reporting

Doing this will suppress the display of the JBO-XXXXXX error code prefix in errors messages that are displayed to the user.

After saving your changes, just rerun the application to immediately see the effect of changing this declarative error reporting setting. If you repeat the steps we tried above to set a salary of 25001 for Steven King, you'll now see the more friendly error message shown in Figure 146.

Figure 146: Validation Errors Presented Without the JBO-XXXX Prefix

14 Conclusion

In this end-to-end tutorial we've experienced first-hand how Oracle JHeadstart 10g turbo-charges developer productivity for Oracle ADF-based web applications. Using a JDeveloper wizard to generate the back-end ADF Business Components that handle database interaction, and using the declarative JHeadstart Application Generator to iteratively generate the entire web front end, we built an attractive, consistent, interactive, and skinnable web application with browse, search, insert, update, and delete functionality against six related database tables from the Oracle HR sample schema. The application featured single- and multi-row editing, page-by-page scrolling, master/detail handling, dropdown lists, a pop-up LOV, a wizard, a shuttle picker, a tree control, and more. We saw an example of how the JHeadstart Application Generator can be customized using a powerful templating mechanism to locally (or globally) change the basic structure of the pages it generates. We also saw that since JHeadstart is generating standard ADF artifacts and metadata, we can use the standard tools that JDeveloper provides to customize the generated pages where needed.

14.1 No Generated Java Code For Any Functionality in the Entire Tutorial!

We claimed at the outset that no Java code was required to build the demo, and in fact none of the steps we followed above required our writing any Java code. But you must be thinking, "Surely JHeadstart or JDeveloper itself must have generated some Java code to make all of that functionality work, right?" You might be surprised.

After first deleting any compiled output from our project by selecting the ViewController project and choosing Run | Clean ViewController..., we can simply go to a command shell and try to count the number of Java source code files that were generated during the course of this tutorial.

Figure 147 shows the result of opening a command shell, changing directories to the C:\MyDemo root directory where we've been working on the tutorial, and doing a recursive directory search for any *.java files. The executive summary: 1 File(s) Found. And we'll see in the next section why that single file does not really even count as Java code, since it is a file that just contains translatable error messages.

While a search for *.jspx files, *.properties, or *.xml files will produce a number of hits — other than the single message bundle file — no Java code was needed to build this demo. All of the base functionality to support the features we have employed lives in the base ADF framework library components and some standard framework extension libraries that JHeadstart provides to complement its declarative application generation.

Figure 147: No Written or Generated Java Code Required For Functionality of This Tutorial

This does not imply that building your own business applications with Oracle ADF and JHeadstart 10g Application Generator won't require any Java code. They undoubtedly will. However, what we're illustrating here in the tutorial is that Java code is not required for a huge amount of the basic functionality every business application needs. The code you'll end up writing will be code that is specific to your business application functionality, and not to making the basics of screen management, data management, or business rules enforcement work correctly.

14.2 Simplified Multi-Lingual Applications with Message Files

A Java message bundle file is the standard way a Java component — like the Employees entity object in your Model project — can save its translatable string resources. Oracle ADF and JHeadstart 10g use a combination of *.properties files and Java message bundles to save translatable string resources for your web tier in the ViewController project and business service tier in your Model project. If we look a little more closely at this lone Java file (EmployeesImplMsgBundle.java). you'll see that there's no real code in there, just the error message for the Employees entity object's range validation rule on the Salary attribute that we added above:

sMessageStrings = {
      {"Salary_Rule_0", "Salary must be between 1 and 25000"}
    };


Using a combination of *.properties files and Java message bundles like this, the applications you build with Oracle ADF and Oracle JHeadstart 10g for ADF are setup out of the box to use the best-practice techniques to make building even multi-lingual applications easy!

14.3 J2EE Applications Give Choice of Application Server

Another interesting point to note in closing is that while we've been testing the tutorial application on the embedded Oracle Containers for J2EE (OC4J) server inside JDeveloper, the same ADF-based web application can run inside any J2EE application server. As shown in Figure 148, in addition to support Oracle's J2EE server, JDeveloper offers automated installation of the ADF Runtime libraries on a number of other popular J2EE servers as well. For servers not included in this automated list, JDeveloper can prepare a standard J2EE EAR file to be deployed using the deployment tool provided by that application server.

Figure 148: ADF Runtime Installer Automated Installation Options

14.4 Useful Links for Additional Information on JHeadstart, JDeveloper, and Oracle ADF

So, in hoping that this tutorial has been both educational and eye-opening for you, we close with a few links to where you can find additional information, samples, and tutorials about JDeveloper 10g, Oracle ADF, and Oracle JHeadstart.

• Useful JHeadstart Links

  • JHeadstart Developer's Guide (PDF) ^[10]
  • JHeadstart Product Center on OTN ^[4]
  • OTN JHeadstart Discussion Forum ^[17]

  • JHeadstart Blog ^[18]

• Useful Oracle JDeveloper Links

  • JDeveloper Product Center on OTN ^[19]

• Useful Oracle ADF Links

  • ADF Learning Center on OTN ^[20]
  • ADF Developers Guide for Forms/4GL Developers ^[8]
  • ADF and J2EE for Forms and Designer Developers ^[21]

  • Dive into ADF Blog ^[22]

• Useful Oracle Technology Links

  • Oracle Technology Network ^[23]
  • Oracle Community Weblogs (Oracle Blogs) ^[24]

If you have any questions on JHeadstart that are not answered with the above links, you can post them on the OTN JHeadstart Discussion Forum ^[17]. In addition, if you have any questions on Oracle ADF in general, you can post them to the OTN JDeveloper Discussion Forum ^[25] on OTN.

14.5 Now You Can Try On Your Own Schema

At this point you are ready to try Oracle JHeadstart Evaluation Version on your own database schema. Keep in mind that the evaluation version of JHeadstart is fully-functional and has no time-limit, however it does limit you to working with a maximum of only ten (10) different view objects in your workspace. If you try to run the JHeadstart application generator in a workspace with more than ten view objects, you'll see the JAG error:

JAG-00130 [ JHeadstart ] You can have only 10 ViewObjects in your workspace when using the JHeadstart Evaluation Version.

This lets you experiment with every feature of the powerful JHeadstart product on a selected group of your real-world application tables to demonstrate to yourself, your colleagues, and your management the boost in development productivity it can provide you. If you like what you see, you can find information on getting the full JHeadstart product on the JHeadstart Product Center on OTN ^[4] .

Related Documents

1. Building Enterprise JSF Applications with Oracle JHeadstart for ADF (10.1.3) [PDF] [http://otn.oracle.com/products/jdev/tips/muench/jhstutorial/jhs-step-by-step.pdf]

2. Completed Version of the Tutorial [http://otn.oracle.com/products/jdev/tips/muench/jhstutorial/MyDemo.zip]

3. ADF Business Components Design Pattern Catalog [http://www.oracle.com/technology/products/jdev/tips/muench/designpatterns/index.html]

4. JHeadstart Product Center [http://www.oracle.com/technology/consulting/9iServices/JHeadstart.html]

5. Tutorial Files for Offline Viewing and Database Setup [http://otn.oracle.com/products/jdev/tips/muench/jhstutorial/jhs-step-by-step.zip]

6. JDeveloper Downloads [http://www.oracle.com/technology/software/products/jdev/index.html]

7. Installing the Sample Schemas and Establishing a Database Connection [http://www.oracle.com/technology/obe/obe_as_1012/j2ee/common/obeconnection.htm]

8. ADF Developer's Guide for Forms/4GL Developers [http://www.oracle.com/technology/documentation/jdev/b25947_01/index.html]

9. Oracle Magazine DEVELOPER: Frameworks [http://www.oracle.com/technology/products/jdev/tips/muench/oramag/index.html]

10. JHeadstart Developer's Guide [http://download.oracle.com/consulting/jhsdevguide1013.pdf]

11. 7.3.1.4 Removing Unnecessary Key Attributes from Reference Entity Usages [http://download.oracle.com/docs/html/B25947_01/bcvoeo003.htm#sthref527]

12. Asynchronous JavaScript and XML (AJAX) [http://en.wikipedia.org/wiki/AJAX]

13. Velocity [http://jakarta.apache.org/velocity/]

14. Oracle Browser Look and Feel [http://www.oracle.com/technology/tech/blaf/index.html]

15. Wikipedia Definition of 'Skin' [http://en.wikipedia.org/wiki/Skin_(computing)]

16. Oracle Designer Product Center on OTN [http://www.oracle.com/technology/products/designer/index.html]

17. OTN JHeadstart Discussion Forum [http://forums.oracle.com/forums/forum.jsp?forum=38]

18. JHeadstart Blog [http://blogs.oracle.com/jheadstart/]

19. JDeveloper Product Center on OTN [http://www.oracle.com/technology/products/jdev/index.html]

20. ADF Learning Center on OTN [http://www.oracle.com/technology/products/adf/learnadf.html]

21. ADF and J2EE for Forms and Designer Developers [http://otn.oracle.com/formsdesignerj2ee]

22. Dive into ADF Blog [http://radio.weblogs.com/0118231/]

23. Oracle Technology Network [http://otn.oracle.com]

24. Oracle Community Weblogs (Oracle Blogs) [http://blogs.oracle.com]

25. OTN JDeveloper Discussion Forum [http://forums.oracle.com/forums/forum.jsp?forum=83]