11i Extend Oracle Applications:

Building OA Framework Applications

Basics of the View

Copyright © 2005, Oracle. All rights reserved.

 Objectives

After completing this lesson, you should be able to do

the following:
• Understand the terminology used when talking
about OA Framework UI (View) objects
• Understand how to build a basic OA Framework
page using regions, items, attribute sets, CSS
styles, LOVs, and Search regions

5-2 Copyright © 2005, Oracle. All rights reserved.

 Terminology

• Property
– Anything shown in the Property Inspector
• Attribute
– Means "property" in UIX (XML attribute in the XML
file)
– Roughly equivalent to "column" in BC4J (view
object attribute)
– Various other meanings
• Instance and Usage
– Mean the same thing

5-3 Copyright © 2005, Oracle. All rights reserved.

 OA Workspaces and OA Projects

Be careful to create OA workspaces and OA projects,

rather than plain workspaces or projects.
• Only OA projects allow you to create pages,
regions, and attribute sets.
• Only OA projects capture Oracle Applications-
related information.
– Run options such as Developer Mode
– OA Framework connection information

5-4 Copyright © 2005, Oracle. All rights reserved.

 Region Styles

The region style in the Property Inspector determines

the UI Bean for the region. Different Beans have very
different behaviors.
• header
• Table or advancedTable
• switcher
• hGrid (horizontal grid)
• hideShow
• advancedSearch and so on…
See the OA Framework Developer's Guide and the
online help in JDeveloper.

5-5 Copyright © 2005, Oracle. All rights reserved.

 Region Styles

Some styles need to be combined to build a particular

layout on your page, such as an arrangement of fields
and buttons that use a tableLayout region to define
their locations.
• Table Layout
• Row Layout
• Cell Format
• Spacer

5-6 Copyright © 2005, Oracle. All rights reserved.

 Named Children and Indexed Children

• Named children of a Bean have a specific name

and purpose
– Like properties of the Bean that can be Beans
themselves
• Indexed children
of a Bean depend
on their order
under the Bean

5-7 Copyright © 2005, Oracle. All rights reserved.

 Page Layout Region

The PageLayoutRN region (pageLayout style) must be

the first region. It has several properties and named
children that define the overall appearance and
behavior of your page.
• (Root) Application Module Definition
• AutoFooter
• Title
• Window Title
• Product Branding
• Return Navigation

5-8 Copyright © 2005, Oracle. All rights reserved.

 Item Styles

• Item styles that start with "message" (such as

messageTextInput, messageStyledText,
messageLovInput, and so on) create displayed
data fields.
– Use messageTextInput for an input field.
– Use messageLovInput for an input field with an
LOV.
– Use messageStyledText for a display-only field.
• Region style messageComponentLayout can be
used to quickly and correctly position message*
beans and related items into an N-column grid

5-9 Copyright © 2005, Oracle. All rights reserved.

 More Item Styles

• Use staticStyledText for plain boilerplate text on a

page such as an instruction.
• Use submitButton for a button that does a POST
(the button item style does not submit).

5-10 Copyright © 2005, Oracle. All rights reserved.

 Attribute Sets

Use attribute sets to set certain properties by

inheritance using the Attribute Set property.
• Prompts and text
• Maximum length, display width
• Inherited values are marked in the Property
Inspector

5-11 Copyright © 2005, Oracle. All rights reserved.

 Extending Other Objects

Some parts of your page can be inherited by extending

other regions or items using the Extends property.
• For example, extend
/oracle/apps/fnd/framework/webui/
OAReqFieldDescRG region to get a Required Key
region
• Extend entire regions (and their logic) that are
common to several pages.
• Extend single objects.

5-12 Copyright © 2005, Oracle. All rights reserved.

 CSS Styles

Apply CSS (cascading style sheet) styles to regions

and items to provide a consistent look and feel
• Customers can change styles easily
• Master list of styles at BLAF UI website:
[Link]
tech/blaf/specs/[Link]
• Many of these are already built into UIX and do not
need to be applied manually.

5-13 Copyright © 2005, Oracle. All rights reserved.

 Common CSS Styles

You must set style sheet tags for many of the UI

Beans, particularly fields and "field-like" Beans
(poplists, checkboxes, static page text, and so on).
• OraDataText:
– bold, left-aligned display-only field data
• OraFieldText:
– plain text in updatable fields, checkboxes, etc.
– The text displayed for a checkbox is not considered
to be a prompt, so do not use OraPromptText

5-14 Copyright © 2005, Oracle. All rights reserved.

 Common CSS Styles

• OraPromptText:
– right-aligned prompts
– Note that any of the "message" Beans, such as
messageTextInput, automatically set the correct
CSS class for the prompt.
• OraLinkText:
– left-aligned plain text data that should render as a
link in the link color.
• OraInstructionText:
– any of the left-aligned plain text instructions that
you add to your page

5-15 Copyright © 2005, Oracle. All rights reserved.

 Binding Items to Data

In your declarative data, binding a specific item to data

from an existing VO is simple.
• Add the VO instance to the root AM.
• Specify the root AM for the pageLayout.
• Specify the View Instance in the Property
Inspector for each item.
– Also called view object instance or view usage
• Specify the View Attribute in the Property
Inspector for that item.
– Also called view object attribute

5-16 Copyright © 2005, Oracle. All rights reserved.

 Creating a Region with the Region Wizard

Use the Region Wizard when you need to create

multiple items based on one VO instance.
• Choose your AM and VO instance (usage).
– Typically AM is set at pageLayout level, so do not
check the "Use as AM for the Region" box.
• Choose your region style (such as table).
• Specify attribute sets before changing prompts.
– Attribute sets often change prompts.
• Set IDs and item styles as needed.
• Make other property changes to individual items
when you are done with the wizard.

5-17 Copyright © 2005, Oracle. All rights reserved.

 Destinations and Links

The Destination URI property lets you link from a field.

• For a link to another page:
[Link]?[page=<URL path> or
OAFunc=<FunctionName>]
&<paramName1>={@ViewAttributeName1}
…
&retainAM=<Y or N>
&addBreadCrumb=<Y or N>
• The same syntax can also be used with
[Link]

5-18 Copyright © 2005, Oracle. All rights reserved.

 Mailto Links

The Destination URI property lets you link from a field.

• For an email link, set Destination URI property to
[Link]
– For example: [Link]

5-19 Copyright © 2005, Oracle. All rights reserved.

 Standards Help Meet Many Requirements

Standards for object and file naming, CSS style sheets

and attribute sets help developers meet requirements
for:
• Customization/personalization
• Translation
• Accessibility
• Maintenance

5-20 Copyright © 2005, Oracle. All rights reserved.

 General Naming Rules

• File Name length

– File names are limited to 30.3 characters for OA
Extension XML files ([Link] for Java files).
• Object Name length (regions, items, and so on)
– For performance reasons, object names (internal
ID’s) are limited to 30 characters.
– Use the shortest possible names that are readable.
– Consider abbreviating repeating object names.

5-21 Copyright © 2005, Oracle. All rights reserved.

 General Naming Rules

Object name abbreviations:

• Common abbreviations are acceptable to keep
names as short as possible.
• Acceptable abbreviations can be instantly
understood by a third party consultant.
• Examples of acceptable abbreviations are:
– Emp for employee
– Num for number
– Desc for description
– Industry terms such as PO
• If in doubt don’t abbreviate.

5-22 Copyright © 2005, Oracle. All rights reserved.

 General Naming Rules

Object names in pages must be unique in the entire

page.
• Convention is to name the object to match its label
(shortened as appropriate).
• For duplicate names, prefix the second and higher
instances with a short version of the parent
object’s name. For example:
– EmpName
– SearchEmpName
– ResultsEmpName
• Most names follow Java naming convention
(mixed case)

5-23 Copyright © 2005, Oracle. All rights reserved.

 Page and Object Naming Rules

• Page name ends in PG: EmpSearchPG,

EmployeePG, SupplierPG
• Content regions have names ending with RN:
MainRN, EmpSearchRN, PoHeaderRN
• Layout-only container region names reflect the
layout: ContactsTableLayout, ButtonsRow
• BLAF Navigation-only regions use standard
names: PageTopNavLinksRN, TrainRN

5-24 Copyright © 2005, Oracle. All rights reserved.

 Styles and Bean Names

• Region or item style names in the JDeveloper

Property Inspector appear in the Java naming
convention starting with lower case letter.
• The corresponding programmatic versions (web
Bean names) usually prepend "OA", append
"Bean" and capitalize the first letter.
– messageComponentLayout becomes
OAMessageComponentLayoutBean
– table becomes OATableBean
• See the OA Framework Developer's Guide and OA
Framework Javadoc

5-25 Copyright © 2005, Oracle. All rights reserved.

 Attribute Set Standards

• Use an attribute set for every displayed field on

the page.
– Includes prompt or label, field descriptions for
accessibility, any other text for the field
• Each displayable table column must have at a
least one associated attribute set.
• Foreign key column references use base columns’
attribute sets.
• For lookup code columns, create an attribute set
with a prompt suitable as a label for the lookup
values.

5-26 Copyright © 2005, Oracle. All rights reserved.

 Attribute Set Standards

• Attribute sets associated with a single table are

saved in a single package.
– Attribute sets associated with translation table
columns are saved in the base table package.
• In addition to attribute sets for columns, a table-
related package includes:
– Region header attribute sets
– Table-specific action button attribute sets
• Standard button attribute sets are provided by OA
Framework under [Link]

5-27 Copyright © 2005, Oracle. All rights reserved.

 Attribute Sets

For UI elements that don’t map directly to a table

column (transients):
• If the element maps indirectly to a table column,
reuse that column’s attribute set (example: search
criteria or other non-database fields)
• If the element is reusable, create an attribute set
under
<your-prod>.[Link]
• Attribute sets for product-specific buttons can be
added under
<your-prod>.[Link]

5-28 Copyright © 2005, Oracle. All rights reserved.

 Attribute Set Naming Conventions

• For column-related attribute sets, change column

name to use Java class naming style.
– For example, PARTY_NAME column name becomes
PartyName.
• When a column is used in different contexts, use
multiple attribute sets.
– 1st attribute set name is derived from column name
and considered the default (such as PartyName,
which contains the most common prompt,
Organization)
– 2nd and higher attribute sets add an _OtherPrompt
suffix (such as PartyName_Partner)

5-29 Copyright © 2005, Oracle. All rights reserved.

 More Attribute Set Standards

The attribute set standards include lists of properties

(templates) for defining various categories of attribute
sets.
• Templates define which properties are mandatory
or optional for defining an attribute sets.
• Properties not on the templates are NOT allowed.

5-30 Copyright © 2005, Oracle. All rights reserved.

 More Standards Information

You must also follow all the related standards in:

• Oracle Applications Framework Developer's Guide
– Standards and Guidelines
– Testing and Debugging
• Standards for:
– Naming
– Coding
– Accessibility
– Customization …and more
• See also
[Link]/atg/accessibility
(internal).

5-31 Copyright © 2005, Oracle. All rights reserved.

 Overview of Building Search Regions

• The user can have three main types of search

interface.
• The developer has three main ways (construction
modes) of building search regions on pages.
• Any search user interface can be done with either
Results-based search or Auto Customization
Criteria.
User Interfaces Construction Mode
Simple Results-based Search
Advanced Auto Customization Criteria
Views Manual

5-32 Copyright © 2005, Oracle. All rights reserved.

 Simple Search

The simple search interface provides:

• one or more fields for a user to type a criteria
value
• a Go button
• a Clear button.

5-33 Copyright © 2005, Oracle. All rights reserved.

 Advanced Search

The advanced search interface provides:

• one or more fields for a user to type a criteria
value
• a Go button
• a Clear button
• AND, OR, and datatype-specific search capabilities

5-34 Copyright © 2005, Oracle. All rights reserved.

 Personalized Views

• The views search interface allows a user to name,

save, and rerun queries with particular query
criteria.
• The results table and items in the table must have
"User Personalization" set to True to make this
work.
– The developer must specifically set these.

5-35 Copyright © 2005, Oracle. All rights reserved.

 Construction Mode

There are three construction modes for your query

region:
• resultsBasedSearch
• autoCustomizationCriteria
• none

5-36 Copyright © 2005, Oracle. All rights reserved.

 Results-based Search

A results-based search is the simplest to build, but

offers little control of the search panels.
• All you need to build is the results table.
– Set the Search Allowed property to True for
columns that should have fields in the search
panel.
– You do not need to handle any buttons.
– You do not need to build an initQuery() method on
your VO.
• You cannot have an LOV or other special
validation on a search field.

5-37 Copyright © 2005, Oracle. All rights reserved.

 Auto Customization Criteria Search

An autoCustomizationCriteria search requires you to

build the search panels but allows greater control.
• Build the results table.
• Build the search fields for each search panel.
• Create mappings between the search fields and
the table columns.
• Build any LOV or other special validation you want
on a search field.
• You do not need to handle any buttons.
• You do not need to build an initQuery() method on
your VO.

5-38 Copyright © 2005, Oracle. All rights reserved.

 Construction Mode of "None"

For the "none" construction mode, you must create

your own simple and/or advanced search panels, and
you must implement your own Go button.

5-39 Copyright © 2005, Oracle. All rights reserved.

 Manually-Built Search Regions

Many Search regions have been built manually without

using the query bean.
• Build region with search criteria fields and a Go
button.
• Build results table region.
• Handle Go button in processFormRequest.
• Call AM and have the AM call initQuery method in
your VO.
• Initialize and execute query in your initQuery
method in your [Link] class.
– You must write code to prevent blind queries.

5-40 Copyright © 2005, Oracle. All rights reserved.

 Disabling Blind Queries

Blind queries can cause huge performance impacts

and must be prevented.
• With query bean, use Selective Search Criteria
property set to True on items to force the user to
enter criteria in at least item where it is set to
True.
• For a manually-built search, you must write code
to prevent blind queries.

5-41 Copyright © 2005, Oracle. All rights reserved.

 Lists of Values (LOVs)

• Two types of declarative LOV

– In-line LOV region
– External LOV region
• Dynamic query construction
– Add to either in-line or external LOV
– Define "Programmatic Criteria" in LOV mappings
– Requires an extra controller

5-42 Copyright © 2005, Oracle. All rights reserved.

 Lists of Values (LOVs)
LOV Window
Base Page
Search
Criteria
A 1 Search by E 1 Go
Return F
B 2

Results
C E F G H
4
D 4 1 2 4
Hidden Criteria
4
4

Cancel Select

5-43 Copyright © 2005, Oracle. All rights reserved.

 Defining an External LOV

• Build the LOV region in a region file:

– Create an LOV region of style ListofValues.
– Create a table region inside the LOV region.
– Items that users can choose for entering query
criteria in LOV window must have Search Allowed
property set to True.
• Attach the LOV region to the base page using
External List of Values property on LOV field
– Set to qualified name of region file.
– Base page LOV field must have Item Style property
set to messageLovInput.

5-44 Copyright © 2005, Oracle. All rights reserved.

 Defining an External LOV

Create the LOV mappings:

– LOV field on base page must be specified for both
Criteria From and Return To properties.
– Other fields can only be used for one direction only
(criteria item or return item).
– Other criteria fields provide hidden criteria that is
always applied to the search in the LOV window.

5-45 Copyright © 2005, Oracle. All rights reserved.

 Summary

In this lesson, you should have learned how to:

• Understand the terminology used when talking
about OA Framework UI (View) objects.
• Understand how to build a basic OA Framework
page using regions, items, attribute sets, CSS
styles, LOVs, and Search regions.

5-46 Copyright © 2005, Oracle. All rights reserved.