This section describes the standard properties for the various form widgets that a user interacts with. It also describes the coding techniques for implementing these widgets.
The following topics are covered:
For more information about the general look and feel of widgets, see the Oracle E-Business Suite User Interface Standards for Forms-Based Products.
The following information applies to all text items.
In general, most text items use the TEXT_ITEM property class.
Use the TEXT_ITEM_DISPLAY_ONLY property class on fields that do not allow a user to type, but must support scrolling and or querying. Some date fields use this property class. In cases where the user must tab to display-only fields located on a part of the canvas that is not immediately visible, you may override the Keyboard Navigable property inherited from the property class.
Use the TEXT_ITEM_MULTILINE property class on all multiline text items.
Use TEXT_ITEM_DATE for date fields unless the item is display only.
Apply the CREATION_OR_LAST_UPDATE property class to the items containing the WHO date information, CREATION_DATE and LAST_UPDATE_DATE.
Set the maximum query length to 255 to allow for complex query criteria.
This trigger fires when the field value changes. Also, a Required field is not enforced until record-level validation. Therefore you may need to write logic that specifically accounts for a NULL value.
To support bidirectional languages such as Arabic, do not use Left or Right justification (numeric text items can use Right justification). Use Start and End instead. You may use Center where appropriate.
Generally the property class sets the correct justification, unless you need to specify Right or Center.
Date fields that the user enters should use the Calendar.
See: The Calendar
For date fields, use the DATE data type unless the user needs to enter time. Use the DATETIME data type to require the user to enter time.
To default a form field to the current date without the time, use $$DBDATE$$. To default a form field to the current date and time, use $DBDATETIME$$.
Create date fields as 11 characters without time, or 20 characters with time.
You do not need to specify a format mask in the item. Oracle Forms defaults the format correctly for each language from the environment variable NLS_DATE_FORMAT.
Oracle E-Business Suite currently requires an NLS_DATE_FORMAT setting of DD-MON-RR. Forms date fields that are 11 or 20 characters long will display a four-character year (DD-MON-YYYY) automatically.
In general, validate your date fields at the record level rather than at the item level.
Record level validation allows the user to correct errors more easily, especially in a From Date/To Date situation. After entering an incorrect date (last year instead of next year), the user should not need to change first the To Date before correcting the From Date.
Display items do not allow any user interaction - they merely display data and never accept cursor focus.
Use a display item for the following situations:
Null-canvas fields
Context fields
Fields that act as titles or prompts
If a field must accept cursor focus, either to allow scrolling or querying, it must be a text item, not a display item.
See: Text Items and Oracle E-Business Suite User Interface Standards for Forms-Based Products.
If an item is used to hold a dynamic title, use DYNAMIC_TITLE; if an item holds a prompt, use DYNAMIC_PROMPT. Both of these property classes provide a "canvas" colored background (gray). Otherwise, you should apply the DISPLAY_ITEM property class to your display items (provides a white background with no bevel).
To support bidirectional languages such as Arabic, do not use Left or Right justification. Use Start instead of Left, and generally use End in place of Right. Use Right only with numeric fields. You may use Center where appropriate.
Generally, applying the correct property class sets justification correctly.
Always make sure that the width (length) of the display item is large enough to accommodate translated values without truncating them. Items using either DYNAMIC_TITLE or DYNAMIC_PROMPT inherit a maximum length of 80 (which you should not change). Typically, the largest value you could accommodate in English would be about 60 characters (which, if expanded about 30 percent, fills an 80-character-wide field).
Poplists are used for two distinct purposes in Oracle E-Business Suite: to hold data in a small list of possible values, and to set the displayed region for a set of alternative regions (for backwards compatibility only).
For information about the look and feel of poplists, see the Oracle E-Business Suite User Interface Standards for Forms-Based Products.
Poplists holding data use the LIST property class. Poplists that serve as control elements for alternative regions use the LIST_REGION_CONTROL property class (for backwards compatibility only).
Coding Alternative Region Behavior
The maximum width of a list element is 30 characters. Your longest value in English for a 30-character-wide poplist should be no longer than 23 characters to account for expansion of values for some languages.
You may need to populate a list at runtime. If so, be aware of the following issues:
Never use a list item if you expect more than fifteen elements
Do not change a list on a per-record basis
Make sure each populated list has a value that matches the default value. You can dynamically change the default by specifying it as a reference to another field, as opposed to a hardcoded value.
Always set a poplist based on its value, not its label. The value never gets translated, but the label may. When you set the Default Value property, Oracle Forms will actually accept the label value (for example, Good), but you should always use the hidden value (for example, G) instead.
For information about the look and feel of option groups, see the Oracle E-Business Suite User Interface Standards for Forms-Based Products.
Apply the RADIO_GROUP property class to the option group.
Apply the RADIO_BUTTON property class to each button of an option group.
An option group that serves to place the form in a mode (as opposed to holding data) should have Access Keys specified for each of the buttons.
For information about the look and feel of check boxes, see the Oracle E-Business Suite User Interface Standards for Forms-Based Products.
See: Master-Detail Relations (Blocks)
Apply the CHECKBOX property class to each normal check box (used for data entry). Apply the CHECKBOX_COORDINATION property class to each coordination check box.
Buttons can either be textual or iconic; that is, they display either words or a picture.
Buttons should be items in the block they act upon or appear to be part of (not in a control block). For example, create an "Accept" button as a non-database object in the block on which it performs the accept. If you navigate to a LINES block from a HEADER block using a "Lines" button, make the button part of the HEADER block.
For information about the look and feel of buttons, see the Oracle E-Business Suite User Interface Standards for Forms-Based Products.
Textual buttons use the BUTTON property class. Iconic buttons use the BUTTON_ICONIC property class and typically appear only in the toolbar or in folder forms.
Warning: Never override the height specified by the BUTTON property class.
Single record block buttons are Keyboard Navigable Yes. Multi-record block buttons are Keyboard Navigable No. The exception is Clear buttons, which should always use Keyboard Navigable No. This is to prevent users from accidentally clearing records when they expect to fire the default button.
All buttons are Mouse Navigate No.
Iconic buttons cannot be operated from the keyboard. If your form is intended to used for heads-down data entry (keyboard only), this implies the functionality they add must either be non-essential or have a secondary invocation method, such as the menu.
Most buttons do not apply in Enter-Query mode. Users cannot leave the current record while in this mode. You do not need to explicitly disable a button while in Enter-Query mode; instead set the trigger property "Fire in Enter-Query mode" for the WHEN-BUTTON- PRESSED trigger to No.
Buttons should call APP_STANDARD.APP_VALIDATE and pass a scope before performing their action. This ensures that your records are valid before performing an action, and that the button acts on the expected block.
Use Lists of Values to provide validation on a text item when you expect to have more than fifteen values.
For more information, see the Oracle E-Business Suite User Interface Standards for Forms-Based Products.
Apply the LOV property class to all LOVs.
Tip: You may override the List Type and Automatic Refresh properties as needed.
You should base your LOVs on views. This denormalizes any foreign key references and provides the same performance advantages as basing your blocks on views.
An LOV view is usually simpler than a form view, since it does not include all denormalized columns. The LOV view does need to join to foreign key tables to get meanings associated with list and radio group values, whereas in a form view the meanings are hardcoded into the boilerplate text or the widget.
If the view is very simple or, conversely, overly-complicated because the bind variables are not in the SELECT list, then you may code the entire SQL needed by the LOV directly into the form.
The title of an LOV is the name of the object in the LOV, and is plural.
The prompt of the first column is related to, or matches identically, the prompt of the item that invoked it.
The width of each column should be wide enough to show most values (just like the width of fields on a canvas). Make the LOV wide enough to show all included columns, up to a maximum of 7.8".
Always specify the default value by the value, not the label. This ensures that the default is translated correctly.
Use your judgement when deciding which columns to bring over for the LOV. Sometimes you only need to bring over a primary key and its display name, if the rest of the data would take too long to fetch. After the row is selected, use the WHEN-VALIDATE-ITEM trigger to bring over any other necessary columns. VARCHAR(2000) columns should not be part of an LOV.
A LOV should show only those rows that currently can be selected, unless the LOV is in a Find Window (Find Window LOV's show all rows that have ever been valid).
EXCEPTION: Validation can be performed after-the-fact if any of the following apply:
The validation clause cannot be written in SQL.
The validation clause is too costly to evaluate in SQL.
The reason for exclusion from the list is obscure to the user.
In such cases, after the value is selected, show an error message indicating exactly why the value could not be selected.
For more information on how to code Row-LOVs in response to "View->Find," see:
See: Query Find Windows
If your item has a List of Values, the Validate from List property is set to Yes, and you assign a value to the field in the POST-QUERY trigger, the item is marked as changed because the LOV fires. To avoid this complication, set the RECORD_STATUS back to QUERY at the end of the POST-QUERY trigger.
You may alter the properties on your LOV to create the following behavior:
If the values displayed by the LOV are static during a session and the number of rows is not excessive, turn Automatic Refresh off (No) to cache the LOV values for the session. Caching the values avoids database hits and network round trips for subsequent invocations of the LOV, and eliminating unnecessary round trips is a key factor in producing a product that can run on a wide area network. However, the caching consumes memory that is not recovered until the form is closed.
If an LOV may show more than one hundred rows, then the user must be prompted to reduce the list of valid values first (Filter Before Display:Yes).
Never have Filter Before Display set to Yes, and Automatic Refresh set to No, on an LOV. This combination would cause only the reduced set of rows to be cached if the user enters something in the reduction criteria window. With Automatic Refresh off, there is no way of returning to the full set of rows. Typically it is not wise to cache an LOV that returns more than 100 rows.
The EMP table contains the following columns: EMPNO, ENAME, JOB, MGR, HIREDATE, SAL, COMM AND DEPTNO. DEPTNO is a foreign key to the table DEPT, which contains the columns DEPTNO, DNAME, and LOC.
A form view of the EMP table would contain all columns in EMP, denormalize EMP.DEPTNO, and include the column DEPT.DNAME, as well. It might also include DEPT.LOCATION and other DEPT columns, and contain records for all past and present employees:
CREATE VIEW EMP_V AS SELECT EMP.EMPNO, EMP.ENAME, EMP.JOB, EMP.MGR, EMP.HIREDATE, EMP.SAL, EMP.COMM, EMP.DEPTNO, DEPT.DNAME, DEPT.LOCATION FROM EMP, DEPT WHERE DEPT.DEPTNO = EMP.DEPTNO;
By contrast, an LOV view of EMP would only include columns EMP.EMPNO and EMP.ENAME. DEPT information would be included only if necessary to help select an employee.
For Y/N values, decode "Y" to "*" and "N" to null to avoid a join to FND_LOOKUPS.
Example
A table T has columns ID, NAME, and ENABLED_FLAG. ENABLED_FLAG contains Y/N values. Create your view as follows:
CREATE VIEW T_V AS
SELECT ID, NAME,
DECODE(ENABLED_FLAG, 'Y', '*', NULL)
FROM T;
An LOV on a dependent field should use the value in the master field to reduce the list.
For example, if NAME is dependent on TYPE, the entry LOV for NAME's WHERE clause would include the condition:
WHERE TYPE = :MY_BLOCK.TYPE
LOVs in ENTER-QUERY mode should be used sparingly, as Query Find is the preferred method for a user to locate records.
You should only code them where they dramatically improve the usability of ENTER-QUERY mode, and you expect this mode to be used regularly despite Query Find.
An LOV in ENTER-QUERY mode should display all values that the user can query, not just currently valid values.
EXAMPLE: An LOV for vendors in a purchase order form in enter-query mode shows all vendors that could ever be placed on a PO, not just the set of vendors that currently are allowed to be placed on a PO.
Do not reuse the entry LOV in ENTER_QUERY mode unless it provides the correct set of data for both modes.
Important: WHEN-VALIDATE-ITEM does not fire in ENTER-QUERY mode. Therefore, you cannot depend on the WHEN-VALIDATE-ITEM trigger to clear hidden fields when selecting from an ENTER-QUERY LOV.
See: Query Find Windows
To enable LOVs in ENTER-QUERY mode on an item, create an item-level KEY-LISTVAL trigger as follows:
Trigger: KEY-LISTVAL
IF (:SYSTEM.MODE != 'ENTER-QUERY') THEN LIST_VALUES;
ELSE SHOW_LOV('query lov');
END IF;
When implementing LOVs in ENTER-QUERY mode, do not return values into any field other than the field from which the LOV is invoked. If the LOV selects into a hidden field, there is no way to clear the hidden field. Clearing or typing over the displayed field will not clear the hidden field. Users must select another value from the LOV or cancel their query and start over.
Oracle E-Business Suite does not use the native Oracle Forms alert object. The Oracle Application Object Library Message Dictionary feature is used instead, as it provides full translation capabilities and handles text larger than 80 characters.
See: Message Dictionary APIs for PL/SQL Procedures.
Do not write special code for the editor. Rely on native Oracle Forms behavior.
For more information on visual standards for descriptive flexfields, see the Oracle E-Business Suite User Interface Standards for Forms-Based Products.
For information on building flexfields into your forms, see: Overview of Flexfields.
All entities should provide a descriptive flexfield to allow customization.
Avoid using the same descriptive flexfield definition in more than one form. Because a customer can reference any field in their flexfield definition, they may reference a field that exists in one form but not the others.
Key flexfields should use the "ENABLE_LIST_LAMP" LOV, with the Use Validate from List property set to No. Descriptive flexfields do not use an LOV.
This section describes item properties Oracle E-Business Suite uses to control how the user interacts with items when they are in specific states. Oracle E-Business Suite provides a cover routine to the Oracle Forms built-in routine SET_ITEM_PROPERTY. This cover routine, APP_ITEM_PROPERTY.SET_PROPERTY, modifies or augments the native Oracle Forms behaviors for specific properties.
Using APP_ITEM_PROPERTY.SET_PROPERTY helps your forms adhere to the Oracle E-Business Suite user interface standards and helps simplify coding. Using this routine also helps to protect your form from future changes in the native Oracle Forms SET_ITEM_PROPERTY built-in routine.
The APP_ITEM_PROPERTY.SET_PROPERTY cover routine modifies the following properties:
ALTERABLE
ALTERABLE_PLUS
ENTERABLE
DISPLAYED
ENABLED
REQUIRED
All other properties are processed with the native Oracle Forms functionality. Oracle recommends that you call this cover routine even for properties that do not currently have special behaviors in case they change in the future.
Note that calling APP_ITEM_PROPERTY.SET_PROPERTY and specifying a property that is not valid for the indicated item will give the same error as the native Forms built-in routine SET_ITEM_PROPERTY, except where certain conditions are masked as noted below.
The ALTERABLE property is intended to allow or disallow changes to a specific instance (one row) of an item regardless of whether the record is a new or queried record. The item remains keyboard navigable even if changes are not allowed.
The following code:
app_item_property.set_property(itemid, ALTERABLE,
PROPERTY_ON);
is equivalent to:
set_item_instance_property(itemid, CURRENT_RECORD,
INSERT_ALLOWED, PROPERTY_ON);
set_item_instance_property(itemid, CURRENT_RECORD,
UPDATEABLE, PROPERTY_ON);
set_item_property(itemid, INSERT_ALLOWED, PROPERTY_ON);
set_item_property(itemid, UPDATEABLE, PROPERTY_ON);
If the item is currently hidden, no action is taken.
Item and item-instance values are both set to make sure the effect of both of them produces the desired result.
The following code:
app_item_property.set_property(itemid, ALTERABLE,
PROPERTY_OFF);
is equivalent to:
set_item_instance_property(itemid, CURRENT_RECORD,
INSERT_ALLOWED, PROPERTY_OFF);
set_item_instance_property(itemid, CURRENT_RECORD,
UPDATEABLE, PROPERTY_OFF);
If the item is currently hidden, no action is taken.
The ALTERABLE_PLUS property is intended to allow or disallow changes to all instances of an item (all rows of the block). Setting the property to PROPERTY_OFF prevents the user from making a change to that item on any row, regardless of whether each record is a new or queried record. The item remains keyboard navigable even if changes are not allowed.
The following code:
app_item_property.set_property(itemid, ALTERABLE_PLUS,
PROPERTY_ON);
is equivalent to:
set_item_property(itemid, INSERT_ALLOWED, PROPERTY_ON); set_item_property(itemid, UPDATEABLE, PROPERTY_ON);
If the item is currently hidden, no action is taken.
The following code:
app_item_property.set_property(itemid, ALTERABLE_PLUS,
PROPERTY_OFF);
is equivalent to:
set_item_property(itemid, INSERT_ALLOWED, PROPERTY_OFF); set_item_property(itemid, UPDATEABLE, PROPERTY_OFF);
If the item is currently hidden, no action is taken.
The ENTERABLE property is designed to simulate disabling a particular instance of an item (one row). It extends the ALTERABLE property by also controlling the NAVIGABLE property; however, there is no way to prevent the user from clicking into the item.
The following code:
app_item_property.set_property(itemid, ENTERABLE,
PROPERTY_ON);
is equivalent to:
set_item_instance_property(itemid, CURRENT_RECORD,
INSERT_ALLOWED, PROPERTY_ON);
set_item_instance_property(itemid, CURRENT_RECORD,
UPDATEABLE, PROPERTY_ON);
set_item_instance_property(itemid, CURRENT_RECORD,
NAVIGABLE, PROPERTY_ON);
set_item_property(itemid, INSERT_ALLOWED, PROPERTY_ON);
set_item_property(itemid, UPDATEABLE, PROPERTY_ON);
set_item_property(itemid, NAVIGABLE, PROPERTY_ON);
If the item is currently hidden, no action is taken.
Item and item-instance values are both set to make sure the effect of both of them produces the desired result.
The following code:
app_item_property.set_property(itemid, ENTERABLE,
PROPERTY_OFF);
is equivalent to:
set_item_instance_property(itemid, CURRENT_RECORD,
INSERT_ALLOWED, PROPERTY_OFF);
set_item_instance_property(itemid, CURRENT_RECORD,
UPDATEABLE, PROPERTY_OFF);
set_item_instance_property(itemid, CURRENT_RECORD,
NAVIGABLE, PROPERTY_Off);
If the item is currently hidden, no action is taken.
The DISPLAYED property handles displaying and hiding items as well as resetting certain properties that Oracle Forms automatically sets when an item is hidden.
The following code:
app_item_property.set_property(itemid, DISPLAYED,
PROPERTY_ON);
is equivalent to:
set_item_property(itemid, DISPLAYED, PROPERTY_ON);
If the item is not a display item then also set:
set_item_property(itemid, ENABLED, PROPERTY_ON); set_item_property(itemid, NAVIGABLE, PROPERTY_ON);
If the item is neither a display item nor a button then also set:
set_item_property(itemid, QUERYABLE, PROPERTY_ON); set_item_property(itemid, INSERT_ALLOWED, PROPERTY_ON); set_item_property(itemid, UPDATEABLE, PROPERTY_ON);
The following code:
app_item_property.set_property(itemid, DISPLAYED,
PROPERTY_OFF);
is equivalent to:
set_item_property(itemid, DISPLAYED, PROPERTY_OFF);
The ENABLED property is primarily intended to disable an item that will never apply during the entire session of the form. It differs from the native Oracle Forms behavior in that when items are re-enabled certain properties that Oracle Forms set automatically are reset.
The following code:
app_item_property.set_property(itemid, ENABLED,
PROPERTY_ON);
is equivalent to (for a text item or a list item):
set_item_property(itemid, INSERT_ALLOWED, PROPERTY_ON); set_item_property(itemid, UPDATEABLE, PROPERTY_ON); set_item_property(itemid, NAVIGABLE, PROPERTY_ON);
If the item is a button, then the APP_ITEM_PROPERTY.SET_PROPERTY call is equivalent to:
set_item_property(itemid, ENABLED, PROPERTY_ON);
If the item is not a text item, list, or button, then the APP_ITEM_PROPERTY.SET_PROPERTY call is equivalent to:
set_item_property(itemid, ENABLED, PROPERTY_ON); set_item_property(itemid, INSERT_ALLOWED, PROPERTY_ON); set_item_property(itemid, UPDATEABLE, PROPERTY_ON);
If the item is a display item or is currently hidden, then no action is taken.
The following code:
app_item_property.set_property(itemid, ENABLED,
PROPERTY_OFF);
is equivalent to (for a text item or list item):
set_item_property(itemid, INSERT_ALLOWED, PROPERTY_OFF); set_item_property(itemid, UPDATEABLE, PROPERTY_OFF); set_item_property(itemid, NAVIGABLE, PROPERTY_OFF);
If the item is neither a text item nor a list then:
set_item_property(itemid, ENABLED, PROPERTY_OFF);
If the item is a display item or is currently hidden, then no action is taken.
The REQUIRED property sets whether an item is required or not, while adjusting for whether the field is currently hidden. The REQUIRED property is an item-level property (affects all rows of the block). If the REQUIRED property must change on a per-record basis, you must reset the property as the cursor moves between the rows (typically in the WHEN-NEW-RECORD-INSTANCE trigger). Alternatively, you may prefer to call the native Oracle Forms built-in routine SET_ITEM_INSTANCE_PROPERTY to set the REQUIRED property on a row-by-row basis. Oracle E-Business Suite does not currently provide a cover routine for SET_ITEM_INSTANCE_PROPERTY.
The following code:
app_item_property.set_property(itemid, REQUIRED,
PROPERTY_ON);
is equivalent to:
set_item_property(itemid, REQUIRED, PROPERTY_ON);
If the item is currently hidden, no action is taken.
The following code:
app_item_property.set_property(itemid, REQUIRED,
PROPERTY_OFF);
is equivalent to:
set_item_property(itemid, REQUIRED, PROPERTY_OFF);
Oracle Forms supports setting properties such as INSERT_ALLOWED, UPDATEABLE and NAVIGABLE at both the item level (all records) and item-instance level (just a particular row). A precedence is applied between these two levels to determine the net effect to the user. Thus, if a setting is OFF at the item-level, but ON at the item-instance level, the net effect is that it is OFF. For this reason, exercise caution when setting properties that involve multiple levels. For example, mixing ALTERABLE and ENABLED calls on the same widget may not produce the desired effect.
While working in the Form Builder be aware that setting the Enabled property to No on a text item or list item does not automatically exhibit the same behaviors as the runtime equivalent set through APP_ITEM_PROPERTY.SET_PROPERTY. Instead, you must set the Insert Allowed, Update Allowed, and Keyboard Navigable properties of the item to No, and keep the Enabled property set to Yes.
Behaviors such as ALTERABLE and ENTERABLE can only be achieved at runtime because they rely on item-instance properties that can only be set programmatically.
Unlike most Oracle E-Business Suite visual attributes that are applied as part of a property class or are applied automatically by APPCORE routines, the following visual attributes must be applied programmatically by the developer.
The DATA_DRILLDOWN visual attribute makes the contents of a text item appear in green with an underline. Applied programmatically, this visual attribute can be used to simulate a hypertext link for "drilldown" purposes. It only changes the appearance of the text; it does not perform any linking logic.
DATA_SPECIAL applies the color red on white to a field that needs special emphasis because it contains a value that violates a business rule or requires the user's close attention. For example, negative values in financial forms should be red on white. This visual attribute is ordinarily only applied at runtime.
Warning: Any use of color coding should augment an indicator that functions in a monochrome environment.
Oracle E-Business Suite does not use the DATA_REQUIRED visual attribute.