Written by Chris Schalk, Oracle Corporation
January 2005
Introduction
This HowTo provides an introduction to working with Oracle's ADF Faces JSF
Components in JDeveloper 10.1.3 Preview's environment. It will show how to build
both static HTML select components as well as dynamic select Components which
are bound to data provided from an Oracle TopLink middle-tier.
Prerequisites:
This HowTo uses the same TopLink middle-tier explained in the related HowTo:
Working with JSF Select Components. Later
in the steps below, you'll need to consult this related HowTo in order to
build your TopLink middle-tier.
Getting Started - Building an Oracle TopLink middle-tier
Before building a View for this example, you'll need to first build a middle-tier
Model which uses Oracle TopLink to persist data from an Oracle database. There
is a related HowTo document which details how to build an Oracle TopLink middle-tier
project as well as how to build a non Oracle ADF Faces View.
For this ADF Faces example, you should follow the instructions on building
your TopLink middle-tier and then proceed on to building an ADF Faces View detailed
in this HowTo.
Build a TopLink middle-tier using steps 1-12 in the "Getting Started
- Building an Oracle TopLink middle-tier" section from the related HowTo:
Working with JSF Select Components.
Building the View with Oracle ADF Faces JSF Components
Once you've successfully built and tested your Oracle TopLink middle-tier detailed
in the other HowTo document, you can then build a View using Oracle's ADF Faces
JSF Components.
Important Notice: Please note that this application will be built with
JSF Auto-Binding turned off. This is an option which autobinds both the
page and any JSF Components that you drag and drop onto your JSF page, however
this How-To shows how to manually bind JSF pages. Before continuing,
please make sure that the JSF Auto-Binding option is turned off by unchecking
the "Autobind JSF.." setting in the JSP and HTML visual editor preferences.
For further info, see my Blog entry on this: http://radio.weblogs.com/0130966/2005/01/05.html#a28
In the same project as your TopLink code, build a JSF enabled JSP page by
selecting File->New->Web-Tier->JSF->JSF JSP.
As you invoke the JSF JSP Wizard you can name the page "selectfun_adf_faces".
Change the page type to document (jspx). Accept the default error page
settings and click "Next".
The next page in the wizard allows you to select JSP tag libraries. Select
both the ADF Faces libraries.
Note: The ADF Faces libraries will only appear as available only after you've
installed the ADF Faces extension.
Once the page is generated, drag and drop an ADF Faces PanelPage
component, located on the "ADF Faces Layout" palette page, onto
your new page. Set the Title property to: "JSF Select Fun with ADF Faces".
The ADF Faces PanelPage is a composite component which although not required,
serves as helpful parent container component and provides nice visual formatting
for our page contents.
Before continuing we'll need to make sure the ModelBean class which was
built in the related TopLink HowTo is added to your Faces-Config.xml. If you
haven't already done this, add the ModelBean class as a managed bean in the
Faces-Config.xml file. To do this locate the faces-config.xml file in the
navigator (Web Content->WEB-INF->faces-config.xml) and double-click
it to edit its contents.
The default editor for the faces-config.xml file is the Page Flow modeler,
but for this simple application we will not introduce any navigation rules
so click on the "Overview" tab at the bottom of the page to invoke
the faces-config editing console.
Add a new Managed Bean by first clicking on the Managed Beans node on the
left in the console and clicking "New".
Specify the following and click OK:
Name: Model
Class: selectfun.ModelBean
Scope: request
Continuing building our ADF Faces view, we'll now build a simple static
Select list which will display a list of countries and display the country
code selected. Above our new Select, we'll first add a small banner "Static
Example". This can be done by adding an HTML banner formatted with <h3>
encapsulated in JSF Verbatim tags. To do this, drag and drop a (JSF Core)
Verbatim tag into the center of the PanelPage. Then add "<h3>Static
Example</h3>" into the body of the tag.
Notice that you'll be able to type directly into the Verbatim body in the
visual editor.
Now drag and drop an ADF Faces SelectOneChoice tag below the banner.
After dropping it, set the Label to "Select a country:". (Notice
that ADF Faces provides a useful built-in label for the select.)
In order to capture the selection of the user, we must bind the SelectOneChoice
Component to the ModelBean's "selectedcountry" field. Click
in the Value property in Property Inspector and then click on the bind button
in the Property
Inspector. Click back in the Value property and you'll see an empty
JSF Value expression along with a new button
which invokes the JSF value binder dialog. Click this button to invoke the
dialog and then bind to #{Model.selectedcountry}.
To display the actual items in the selection, you can use the generic JSF
SelectItem tag and embed it inside of the ADF Faces select component.
To insert a SelectItem tag, simply drag it from the Component Palette and
drop it onto the ADF Faces select component. You can also use the Structure
Pane to see the exact location while dropping the component. Once dropped,
set the itemLabel to "United States" and itemValue
to "us".
The easiest way to continue adding static selection items is to simply copy
the selectItem item tag in the code editor and paste it several times. Set
the copied itemLabels and itemValues respectively as: United Kingdom - uk,
France - fr, Spain - sp.
Our static Select control is now finished, however to test that our Select
Component is working correctly we'll need to show the updated value of the
"Model.selectedcountry" field. For this we'll add the ADF Faces
outputLabel and outputText components encapsulated in an ADF
Faces panelGroup component. (The panelGroup allows us to define a horizontal
layout for the label text fields as opposed to a vertical layout.)
Drag and drop an (ADF Faces Layout) PanelGroup Component and set the
type property to "horizontal". Then drag and drop
an (ADF Faces Output) outputLabel into the new Panel group and set
it's value to "You selected: ".
Finally, drag and drop an outputText and bind it's value to
#{Model.selectedcountry} using the same JSF value binder dialog as
before.
Before running the static example, we need to add a button to the page in
order to submit the form. Drag and drop an (ADF Faces Navigation) CommandButton
to the bottom of the Panel Page. Set the Text property to "Update
Model".
Optional: You may want to use an (ADF Faces Output) ObjectSeparator
in between the Commandbutton and the select components. The Object Separator
provides a horizontal divider line between components.
Save all and Compile all.
Right-click and Run the jspx page to test the static example. Verify that
the Select component works: select a country and click "Update Model".
Now we'll add a dynamic Select example based on a returned List object from
our TopLink middle-tier.
Add another banner using the JSF Verbatim tag with <h3>.Dynamic
Example using Oracle TopLink</h3> inside of it.
Optional: Before adding the new banner, you can also add another ObjectSeparator
to visually separate the static list and the new dynamic list.
Similar to before, drag and drop a new SelectOneChoice component
and set it's label to "Select an employee:"
Set the SelectOneCoice component's value to #{Model.selectedempno}.
(Use the JSF value binder as before.)
Insert a single (JSF Core) SelectItems component into the SelectOneChoice
component and bind it's value property to #{Model.employees}. This
will associate the returned List object returned from TopLink to the SelectItems
component.
Add another PanelGroup, set it's type to "horizontal", and then
insert another pair of outputText and outputLabel components.
For the Outputlabel set the value to "You selected employee #: ".
Set the OutputText's value to #{Model.selectedempno}.
That's it. You can now save and run the page again to see both the static
and dynamic selection example!
Summary
This HowTo hopefully serves as a user-friendly example of how to get started
working with the new ADF Faces Component library using the widely used example
of assembling static and dynamic Select controls.
Similar to the core JSF Reference Implementation (RI) Components, ADF Faces
also offer various alternative select Components including some really cool
components such as SelectManyShuttle and others. Readers are definitely encouraged
to take this example and expand on it with the other ADF Faces Components.
JSF RI View
As you may have noticed, the related HowTo which explains how to build the
Oracle TopLink middle-tier, also has steps on how to build a View with just
the JSF RI Components. Feel free to try this out to compare and contrast the
development experience. See the "Building the View.." portion of :
Working with JSF Select Components
Bookmark
in the Property
Inspector. Click back in the Value property and you'll see an empty
JSF Value expression along with a new button 
which invokes the JSF value binder dialog. Click this button to invoke the
dialog and then bind to #{Model.selectedcountry}.
