IMB - Oracle Developer 6 Standards & Guidelines

Oracle Developer 6 Standards & Guidelines

4 Forms

4.1 Linkage with Oracle Designer

The Ministry standard for application development is to generate all Forms modules from the Designer Repository. The only exceptions are menu modules, and application startup forms. These two forms objects may be created manually in Forms Builder without initial generation using Forms Generator. However, it is still the Ministry standard that these modules be documented in the Repository.

Once generated from Designer, a Form may require post-generation changes. These post-generation changes are done using Developer, and documented in the Repository. This ensures that modules are documented correctly in the repository, and has the added benefit of a common look and feel for resulting Forms. This is due to the standard Forms template, and the standard Forms object library.

The role of template forms in form generation has changed from previous releases (V1.2). In previous versions of Designer, a template form could contain generator objects (e.g. items, canvases, and visual attributes) and user objects. Form Generator then used these generator objects to set properties of generated objects, and copied user objects into the generated form without any change.

This functionality of using generator objects to set properties, has now been superseded by Form Generator’s support for copying and sub-classing objects from object libraries. Object libraries are containers for reusable objects and standards, and take the place of referenced forms objects.

The standard source objects all begin with a CGSO$ prefix. Designer 6 Forms Generator can still use preference settings or Repository information, but the standard location to hold standard settings is the CGSO$ objects, with repository information overriding these settings if needed.

CGSO$ object properties can be further refined by their context (e.g. multi-record block, control block, display only item, or mandatory item). These hierarchies of inheritance are set up in the Ministry Standard Template package.

Note: Designer Standards and Guidelines are available on the Internet All Standards page.

4.2 Ministry Standard Template Package

The Ministry supplies a set of standard developer objects, for use in both Designer Forms Generation and the subsequent Developer post-generation changes.

Forms 4.5 to Forms 6.0 Migration Package

*No Longer Supported or Updated*

See document Ministry Oracle Forms 6i/

4.2.1 Incorporating application-specific code

Always have the env60_std.olb object library open in your Forms Builder, so that all your forms can access the super-class objects. This only needs to be done once, as Forms Builder remembers which object libraries are in use.

Globals available for your use are:

ENV$SYSTEM_NAME	Name of your application (e.g. EMS), as set by you in the LOCAL_INIT program unit
ENV$SYSTEM_TITLE	Title of your application, as set by you in the LOCAL_INIT program unit
ENV$CONNECT_STRING	Connect string, if entered, when the user logged on (note that this will be different from the instance name, as in 'ssb_prod' versus 'prd7')

In addition, the ENV$CTRL control block has the following items which your application may access:

DB_APP_VERSION	Version of the application, as stored in the database table APP_STATE
DB_NAME	Instance name, as stored in the global_names database view
DB_USER_ID	Database User ID that is currently logged on
DB_SYSDATE	Database datestamp
MODULE_NAME	Name of the module, as returned by get_application_property(current_form_name)
MODULE_VERSION_NUMBER	Version of this module, as set by you in the LOCAL_INIT program unit

Procedures and Functions for use in your application include:

ENV$CALL_FORM	Ministry standard front-end call to default forms CALL_FORM
ENV$OPEN_FORM	Ministry standard front-end call to default forms OPEN_FORM
ENV$CALL_HTML_HELP	Ministry standard front-end call to HTML help
ENV$INFO_ALERT	Procedure to call a NOTE alert with one 'OK' button, showing the text you pass in.
ENV$OK_ALERT	Function to call a CAUTION alert with 'OK' and 'Cancel', showing the text you pass in.
ENV$VALIDATE_ALERT	Function to call a STOP alert with 'Yes', 'No' and 'Cancel', showing the text you pass in.
ENV$ERROR_ALERT	Procedure to call a STOP alert with one 'OK' button, showing the text you pass in

4.2.2 Miscellaneous Notes

Detailed information on the Template can be found in the Designer Standards. Detailed information on the Standard Forms Generator preferences also can be found in the Data Architecture Standards . Oracle Forms has now been preceded by Java though.

In addition:

Your main entry form (e.g. with Navigation buttons to other parts of your application), may or may not include the Ministry Standard Horizontal Toolbar. If it does have it, then you must disable the 'Close' button, as the new standard is that this button means 'return to previous screen'. To exit from the main entry screen (a.k.a. the entire application), the user must press the standard 'close window' icon at the top-right, or you may provide an 'Exit' button on the main entry screen.
Remember that, when working with packages, you should enter all new procedures after the current ones. Forms run-time accesses the procedure by its sequence number (order in the package), rather than by name, and so you may need to re-compile all forms which reference a package that has been 're-sequenced'.
If you are going to be manually modifying the form during post-generation, please remember to use the Ministry standard object library to create sub-classed items, data blocks, etc. See 'Designer' on-line help (indexed under 'object libraries (Form), alphabetical list of ...') for detailed listings of all available template objects.

4.2.3 Migration from Forms

For applications originally developed using the Forms 4.5 version of the Ministry Template,

Forms 4.5 to Forms 6.0 Migration Package

*No Longer Supported or Updated*

See document Ministry Oracle Forms 6i/

4.3 Overview

4.3.1 General

A general forms design preference is to develop a single form containing the blocks, windows and canvasses required to complete one logical unit of work (e.g. add a new Referral, maintain Referral Correspondence, maintain client information, etc.).

Creating separate forms for each small application component may result in excessive loading of executable code across a network link between the server and client machines. Therefore, developing a separate form for each small component in an application is not recommended. However, forms modules should not be too large (e.g. .fmx should not exceed 512 kilobytes in size) as large forms modules are slow to load.

It is a Ministry standard that all Forms modules be documented in the Designer repository

It is the Ministry standard that all Forms objects be sub-classed from the appropriate CGSO$ object in the inheritance hierarchy (e.g. multi-record block, control block, display only item, or mandatory item). These hierarchies of inheritance are set up in the Ministry Standard Template package, therefore all Forms generated from Designer will automatically be sub-classed correctly.

4.3.2 Sub-Classing Hierarchy of standard source objects

The order of inheritance follows a definite order. If the block is a multi-record data block, then the block is subclassed from the CGSO$BLOCK_MR object. If the block is a control block, then it is sub-classed from the CGSO$BLOCK_CT object.

The complete hierarchy is in the Designer On-Line Help, under Generating Oracle Developer Forms Builder applications >Generating Form Builder applications > Forms Generation >Using object libraries > Hierarchy of standard source objects. A shortened example of the hierarchy is:

CGSO$WINDOW
CGSO$BLOCK

CGSO$BLOCK_MR
CGSO$BLOCK_CT

CGSO$CANVAS
CGSO$CANVAS_TAB
CGSO$CANVAS_SPREAD
CGSO$CANVAS_POPUP
CGSO$CANVAS_POPLIST
CGSO$CANVAS_HTOOL
CGSO$CANVAS_VTOOL
CGSO$LOV
CGSO$DEFAULT_ITEM

CGSO$DEFAULT_ITEM_MR
CGSO$DEFAULT_ITEM_CT
CGSO$DEFAULT_ITEM_DO
CGSO$DEFAULT_ITEM_MD

CGSO$BUTTON

CGSO$AIBUTTON

CGSO$AIBUTTON_CT

CGSO$BUTTON_MR
CGSO$BUTTON_CT
.   .   .   .    .    .   .   .   .
.   .   .   .    .    .   .   .   .
.   .   .   .    .    .   .   .   .
.   .   .   .    .    .   .   .   .
.   .   .   .    .    .   .   .   .

CGSO$LOV_BUT

CGSO$LOV_BUT_MR
CGSO$LOV_BUT_CT

Post-generation addition of Forms objects must still be sub-classed from the MSRM Standard Object Library (env60_std.olb), with over-riding of the properties where necessary.

4.3.3 Alphabetical List of standard source objects

The complete list shown below. This is also in the Designer On-Line Help, under Generating Oracle Developer Forms Builder applications > Generating Form Builder applications > Forms Generation > Using object libraries > Alphabetical list of standard source objects and object types

Standard Source Object Name	Possible Suffixes	Object Library Object Type	Type of Generated Item	Parent Standard Source Object Name
CGSO$AIBUTTON	CT	Item	Button	CGSO$BUTTON
CGSO$ALPHA	MR, CT, DO, MD	Item	Alpha	CGSO$CHAR
CGSO$BLOCK	MR, CT	Block	-	-
CGSO$BUTTON	MR, CT	Item	Button	CGSO$DEFAULT_ITEM
CGSO$CANVAS	-	Canvas	-	-
CGSO$CANVAS_HTOOL	-	Canvas	-	-
CGSO$CANVAS_POPLIST	-	Canvas	-	-
CGSO$CANVAS_POPUP	-	Canvas	-	-
CGSO$CANVAS_SPREAD	-	Canvas	-	-
CGSO$CANVAS_TAB	-	Canvas	-	-
CGSO$CANVAS_VTOOL	-	Canvas	-	-
CGSO$CHAR	MR, CT, DO, MD	Item	Char	CGSO$DEFAULT_ITEM
CGSO$CHAR_MLINE	MR, CT, DO, MD	Item	Char	CGSO$CHAR
CGSO$CHART	MR, CT, DO, MD	Item	Chart	CGSO$DEFAULT_ITEM
CGSO$CHECK_BOX	MR, CT, DO, MD	Item	Check Box	CGSO$DEFAULT_ITEM
CGSO$COMBO	MR, CT, DO, MD	Item	Combo Box	CGSO$DEFAULT_ITEM
CGSO$CONTEXT	MR, CT, DO, MD	Item	Char	CGSO$DEFAULT_ITEM
CGSO$CUR_REC_IND	MR, CT, DO, MD	Item	Char	CGSO$DEFAULT_ITEM
CGSO$DATE	MR, CT, DO, MD	Item	Date	CGSO$CHAR
CGSO$DATETIME	MR, CT, DO, MD	Item	Datetime	CGSO$CHAR
CGSO$DEFAULT_ITEM	MR, CT, DO, MD	Item	-	-
CGSO$DESC_FLEX	MR, CT, DO, MD	Item	Char	CGSO$DEFAULT_ITEM
CGSO$DRILL_IND	MR, CT, DO, MD	Item	Char	CGSO$DEFAULT_ITEM
CGSO$IMAGE	MR, CT, DO, MD	Item	Image	CGSO$DEFAULT_ITEM
CGSO$INTEGER	MR, CT, DO, MD	Item	Integer	CGSO$NUMBER
CGSO$LONG	MR, CT, DO, MD	Item	Long	CGSO$DEFAULT_ITEM
CGSO$LOV	-	LOV	-	-
CGSO$LOV_BUT	MR, CT	Item	Button	-
CGSO$MONEY	MR, CT, DO, MD	Item	Money	CGSO$NUMBER
CGSO$NUMBER	MR, CT, DO, MD	Item	Number	CGSO$CHAR
CGSO$OCX	MR, CT, DO, MD	Item	OCX Control	CGSO$DEFAULT_ITEM
CGSO$OLE	MR, CT, DO, MD	Item	Ole Container	CGSO$DEFAULT_ITEM
CGSO$POP	MR, CT, DO, MD	Item	Pop List	CGSO$DEFAULT_ITEM
CGSO$RADIO	MR, CT, DO, MD	Item	Radio Group	CGSO$DEFAULT_ITEM
CGSO$RADIO_BUTTON	MR, CT, DO, MD	Item	Radio Button	CGSO$DEFAULT_ITEM
CGSO$SOUND	MR, CT, DO, MD	Item	Sound	CGSO$DEFAULT_ITEM
CGSO$TAB_PAGE	-	Tab Page	-	-
CGSO$TEXT_LIST	MR, CT, DO, MD	Item	Text List	CGSO$DEFAULT_ITEM
CGSO$TIME	MR, CT, DO, MD	Item	Time	CGSO$CHAR
CGSO$WINDOW	-	Window	-	-

4.3.4 Forms Objects

The following sections define the various Forms 6.0 objects; describe the properties of each object; and provide usage guidelines and naming conventions for each.

4.3.4.1 Windows

A window is the base frame which holds the canvases which actually contain the user interface items. The window frame provides a way of interacting with the window as a whole (scrolling, resizing and moving the window).

Windows must be sub-classed from the CGSO$WINDOW source object, and should contain one logical unit of work. The logical unit of work may consist of one or many canvasses.

For example the root window should contain static information. Subsequent windows may contain one canvas based on one base table or record group or more than one canvas, block etc.
The window should be optimized for viewing on an SVGA monitor (800x600), but keep in mind that the available horizontal area is less due to the Windows Start Bar
The default size of the window should be large enough to avoid horizontal scroll bars. Horizontal scroll bars are permissible if the window is resized

Window names should be as generated from Designer (CG_WINDOX_n). Windows added during post-generation should be named reflect their purpose. Each of these windows should contain one logical unit of work.

If the logical unit of work consists of one base table or record group, then the window should be named after the table or record group, if more than one canvas, block etc exist an appropriate name to define the purpose should be selected.

The MDI window title will contain (from left to right) the module name, the version of the module, environment name (E.G. test/prod), the name of the system (E.G. "EMS"), the userid and the system date.

As generated from Oracle Designer Forms Generator, the CG$WINDOW_1 window title will contain the title of the module. This title is automatically set when using the Ministry standard template and library. Only the name of the system needs to be set by the developer.

4.3.4.2 Canvases

A canvas is the background object displayed within a window which forms the foundation on which user interface items are displayed.

Canvases must be sub-classed from one of the 7 (seven) canvas source objects, depending on its use (e.g. vertical toolbar canvas, spread-table)
A canvas should be used for one business function.

If there are no horizontal scroll bars on the window, then all objects on the canvas must be visible on an 800 pixels W by 540 pixels H screen (SVGA minus the start bar)

Canvas names should be as generated from Designer (CG$PAGE_n). Canvases added during post-generation will most likely require a post-generation Window as well. If it is the sole canvas for the window, then it should be named to match the name of its window.

Canvases which share a window must be named "Window_name"_"canvas_purpose". This will be true whether the canvases are stacked or not.

The size of the canvas should not be larger than the user can view at one time.
All static information should be visible at all times. Record scrolling should be done at the block level.
Other attributes of the canvas should be consistent throughout the application.

4.3.4.3 Visual Attributes

Visual attributes determine how a user interface object appears at run time. These attributes include font characteristics, colour and pattern characteristics and character mode characteristics.

In the rare cases that an object's 'look and feel' cannot be inherited via a sub-classed standard source object, then a named visual attribute can be added to the application-specific forms template (e.g. ems_pc1t.fmb). Note that the Ministry template already supplies the following pre-defined visual attributes (use these before creating your application-specific ones):

CG$CURRENT_RECORD	CG$BLOCK_SCROLL_BAR	CG$ITEM
CG$CURRENT_ITEM	CG$PROMPT	CG$DISPLAY_ITEM
CG$TITLE	CG$RADIO_TITLE	CG$GROUP_TITLE
CG$PUSH_BUTTON	CG$CANVAS	CG$RADIO_BUTTON
CG$CHECK_BOX	CG$MANDATORY_RADIO_BUTTON	CG$OPTIONAL_RADIO_BUTTON
CG$DISPLAY_RADIO_BUTTON	CG$MANDATORY_CHECK_BOX	CG$OPTIONAL_CHECK_BOX
CG$DISPLAY_CHECK_BOX	CG$OTHER_RECORD	CG$DRILLDOWN
CG$TEMPLATE_TEXT	CG$STUB_TITLE	CG$STUB_DECORATION
CG$RADIO_DECORATION	CG$GROUP_DECORATION	CG$DECORATION
CG$CONTEXT_TITLE	CG$CONTEXT_DECORATION	CG$BLOCK_TITLE
CG$BLOCK_DECORATION	ENV$TOOLTIP_TITLE	ENV$QUERYABLE_ITEM_VA
ENV$NONQUERYABLE_ITEM_VA	ENV$MANDATORY_PROMPT_VA

See also "Use of Colours/Fonts" under the SCREEN LAYOUT section.

Named visual attributes may be used instead of default values. These named visual attributes should be used consistently throughout the application.

Forms 6.0 visual attribute names must be prefixed by the application short name, and follow the form of "type"_va for example:

ems_alert_va
ems_button_va
ems_check_box_va
ems_radio_group_va
ems_text_item_va

If it is necessary to have more than one visual attribute for a type, some meaning should be appended to each name. (e.g. text_item_highlight_va, text_item_italics_va, etceteras)

4.3.4.4 List of Values

The following diagram displays a Forms 6.0 List of Values window:

A list of values is a modal pick-list from which you can select a single value.

Should be based on a record group
Availability should be represented by using an LOV button on the toolbar which will be enabled/disabled when the cursor is on a field which has/does not have a LOV associated

It is a Ministry Standard to always sort a List-of-Values.

List of value names should be as generated from Designer (e.g. CGFK$G_MBR_DSP_AV_TITLE), which denote the data usage that is being linked.

Do not choose auto display
Do not choose auto refresh

4.3.4.5 Blocks

A block provides a simple way of grouping related items into a single unit for storing, displaying and manipulating records. Every Oracle Forms 6.0 item must belong to a block.

It is the Ministry standard to highlight the current record in multi-record data blocks.

Note that all objects sub-classed correctly using the MSRM Standard Forms Template will have the current record visual attribute set to CG$CURRENT_RECORD. This is automatic when using the Designer Forms Generator.

Block names should be as generated from Designer (table short name, or specific usage). Blocks added during post-generation should follow the same convention.

4.3.4.6 Alerts

An alert is a modal window that displays a message that notifies the user of some application condition. The following diagram displays a Form 6.0 `Stop' style of alert (the other styles of alerts available in Forms 6.0 are `Note' and `Caution'):

Use one of the four available program units which show the different alert types:

ENV$INFO_ALERT
ENV$OK_ALERT
ENV$VALIDATE_ALERT
ENV$ERROR_ALERT

If you require a new alert, then:

Use one alert per alert style and dynamically change the message text at runtime (e.g. Each alert style will always have the same buttons but will be displayed with different text).

If you require a new alert, then prefix the application short name to the alert (e.g. swis$special_error_alert).

4.3.4.7 Text Items

A text item is an interface control that displays and allows editing of text. The text is displayed in a field in either single or multi-line format.

text items must be sub-classed from one of the available source objects, depending on its use (e.g. multi-record item, mandatory, optional, etc.)

Text item names should be as generated from Designer (based on column usage). Post-generation items should follow the same convention.

Prompts for an item must be set using the new 'Prompt' property, and not via un-related boilerplate text. It is the Ministry standard that all prompts be declared as text labels in the 'Prompt' property.

4.3.4.8 Record Groups

A record group is an Oracle Forms 6.0 internal data structure that is similar in structure to a database table. There are two types of record groups that can be declared in Forms Designer. On type is based on a query and the other contains a static set of columns and rows. Records groups can also be created and populated at runtime.

Use one table, or view only. Use views to hide complex SQL in the database.

Record group names should be as generated from Designer (e.g. CGFK$G_MBR_DSP_AV_TITLE), which denote the data usage that is being linked. Post-generation record groups should be named in a similar fashion.

If the record group is used to populate a list of values, name the record group the same as the list of values object.

4.3.4.9 Editors

Oracle Forms provides a built in text editor for use with text items. The editor can be invoked by pressing the "Edit" key (ctrl-E on Windows) or automatically at runtime by executing the EDIT_TEXTITEM built in procedure. The following diagram displays the Oracle Forms built in text editor:

Use one common editor throughout the application
Use the default editor unless it does not meet the needs of the application
Position the editor so as not to obscure the field (in most cases, letting Forms determine the placement of the editor works well)

It is the Ministry standard to choose Word Wrap.

4.3.4.10 Relations

A relation is a logical object that specifies the relationship between a master block and a corresponding detail block.

Relation names should be as generated from Designer (table short name, or specific usage). Relations added during post-generation should follow the same convention, using the "Master Block Name"_"Detail Block Name" convention.

Choose Non-Isolated Delete
Choose Deferred Coordination
Choose Auto-Query
Choose Prevent Masterless Operation

4.3.4.11 Buttons

Buttons are interface items that operators select to execute commands or initiate actions.

Buttons should be labeled and not iconified (if an icon is used, the button should also be identified by a label or balloon help).

Button names should be as generated from Designer. Buttons added during post-generation should be named to reflect its usage.

4.3.5 Screen Layout

4.3.5.1 Toolbars

A toolbar is an area where textual descriptions of commands available to a window are displayed. The following figure is an example of a screen that has incorporated the Ministry standard horizontal toolbar (referenced from the Library form) and an application specific vertical toolbar:

Every window must have a horizontal toolbar canvas positioned in the top left hand corner of the window.

The main window must contain the Ministry standard toolbar, available in the Library form and shown in the above diagram.

See Appendix F of the Designer Standards.

Positioning of an item within a toolbar should be consistent with its position on other toolbars in the system.
Toolbars in non-root windows used to show window/form specific functionality should be displayed as vertical toolbars. For example, if the user can navigate to a List Screen from a Display or Modify screen this should be a clearly marked button on the vertical toolbar
N/A

4.3.5.2 Scroll Bars

Scroll bars allow operators to scroll through records within a block or to scroll across a wide screen which has items obscured due to the window size. The following figure contains examples of vertical and horizontal scroll bars<:

Every multi-line block should have a Vertical scroll bar on the right hand side of the block (as in the example above).
Single record blocks may or may not have scroll bars.
Scroll bars should be the same height as the modifiable information in the block.
Use of Horizontal scroll bars is not recommended except in the case of a spread table style of display. Windows should be large enough to avoid the need for Horizontal scroll bars
N/A

4.3.5.3 Messages

Messages should not inhibit data entry. Only use messages in alert boxes if the system cannot continue without an answer from the user or if the user must provide confirmation of the action about to be taken. Warnings and information should be displayed on the bottom message line as usual. Using the Ministry standard resource file will enhance the messages with the use of colour. See next item and Appendix F of the Designer Standards.

If an alert is displayed as the result of field validation, the alert message should explain the edit rule to the user. (e.g. use `The Start Date must Monday to Saturday' instead of `Invalid Start Date').

4.3.5.4 Use of Colours/Fonts

The form module will use real coordinates and centimetres.

Font standard is Arial 10 point because it translates well to the use in Web Browsers.

In general colours and fonts should be used in named visual attributes. Users should be able to change colours at the operating system level to whatever they like. Fonts should be consistent throughout the system.

If a font or colour is changed from the default for a particular message type or highlighting purpose, this font/colour MUST be used consistently for the same types of messages or highlighting purposes throughout the system.

If the application is to be deployed on the Citrix Servers, then the screens should be designed to work on a '256 Colours' setting; this is the default Citrix Metraframe standard;

4.3.5.5 Menu Construction

The following diagram displays the Ministry standard menu (This diagram was taken from the Oracle Forms Builder in order to show all menu options fully expanded. The `&' translates to an `_' at runtime.).

Exit - Exits the system (on the Ministry standard menu);

Close - Returns to the last logical unit of work e.g. calling forms, previous window etc...

Sub-menu Hierarchies are to be avoided wherever possible.

Application specific functions only under the 'Options' heading. See Appendix F of the Designer Standards for information on the Ministry standard integrated menu "env60_mnu.mmb"

4.3.5.6 Screen Navigation

Use consistent commit behavior within an application e.g.: alert box, post and commit, commit only, or auto-commit.
Do not limit mouse navigation. IF YOU CAN SEE IT YOU CAN GO THERE.
Use push-buttons on the tool bar to navigate to unseen but available functionality.
Use consistent tabbing behavior. In general tabbing past the last field should take the user to the next logical unit of work. Suggested:

- Multiple record blocks should to go to next record.

- Single record blocks should wrap back to the first field if no further blocks exist.

- Single record blocks which are "maintain" screens and have another block should go to the next block.
Allow for keyboard navigation between objects (in addition to the mouse navigation) to minimize the amount switching back and forth between the keyboard and mouse for a user.

4.4 HTML Help

HTML documents are the new standard for on-line application documentation. The Ministry standards on HTML Help are available on the Internet / World Wide Web at:

http://srmwww.gov.bc.ca/imb/3star/oracle_support/help/online_guides.html

Return to Table of Contents