Skip Headers

Oracle E-Business Suite Developer's Guide
Release 12.1
Part Number E12897-04
Go to Table of Contents
Contents
Go to previous page
Previous
Go to next page
Next

Overview of Coding Standards

Overview of Coding Standards

Importance of these Standards

The coding standards described in this manual, together with the user interface standards described in the Oracle E-Business Suite User Interface Standards for Forms-Based Products, are used by Oracle developers to build Oracle E-Business Suite applications. If you want to build custom application code that integrates with and has the same look and feel as Oracle E-Business Suite, you must follow these standards. If you do not follow these standards exactly as they are presented, you may not achieve an acceptable result.

This manual makes no attempt to analyze the consequences of deviating from the standards in particular cases. The libraries and procedures that are packaged with Oracle E-Business Suite all assume adherence to these standards. In fact, since the behavior of Oracle Forms, the Oracle E-Business Suite standard libraries, and the standards are so tightly linked, a deviation from standards that appears to be minor may in fact have far-reaching and unpredictable results. Therefore, we recommend that when you develop custom application code, you follow the standards exactly as they are described in this manual and in the Oracle E-Business Suite User Interface Standards for Forms-Based Products.

Coding Principles

Oracle E-Business Suite coding standards are guided by the following principles:

Coding with Handlers

Oracle E-Business Suite uses groups of packaged procedures, called handlers, to organize PL/SQL code in forms so that it is easier to develop, maintain, and debug.

In Oracle Forms, code is placed in triggers, which execute the code when that trigger event occurs. Implementing complex logic may require scattering its code across multiple triggers. Because code in triggers is not located in one place, it cannot be written or reviewed comprehensively, making development, maintenance, and debugging more difficult. To determine what code and events affect a particular item, a developer must scan many triggers throughout the form. Code that affects multiple items can be extremely difficult to trace.

To centralize the code so it is easier to develop, maintain, and debug, place the code in packaged procedures and call those procedures from the triggers. Pass the name of the trigger as an argument for the procedure to process. This scheme allows the code for a single business rule to be associated with multiple trigger points, but to reside in a single location.

There are different kinds of procedures for the different kinds of code you write: item handlers, event handlers, table handlers, and business rules. Code resides in these procedures; do not put any code in the triggers other than calls to the procedures.

Handlers may reside in program units in the form itself, in form libraries, or in stored packages in the database as appropriate.

Item Handlers

An item handler is a PL/SQL procedure that encapsulates all of the code that acts upon an item. Most of the validation, defaulting, and behavior logic for an item is typically in an item handler.

See: Coding Item Handlers

Event Handlers

An event handler is a PL/SQL procedure that encapsulates all of the code that acts upon an event. Usually event handlers exist to satisfy requirements of either Oracle Forms or the Oracle E-Business Suite User Interface Standards for Forms-Based Products, as opposed to particular business requirements for a product.

See: Coding Event Handlers.

Table Handlers

A table handler encapsulates all of the code that manages interactions between a block and its base table. When an updatable block is based on a view, you must supply procedures to manage the insert, update, lock and delete. Referential integrity checks often require additional procedures. Table handlers may reside on either the forms server or the database, depending on their size and the amount of interaction with the database, but they typically reside in the database.

See: Coding Table Handlers and Server side versus Client side.

Business Rules

A business rule describes complex data behavior. For example, one business rule is: "A discount cannot be greater than 10% if the current credit rating of the buyer is less than 'Good'." Another business rule is: "A Need-By Date is required if a requisition is made for an inventory item."

A business rule procedure encapsulates all of the code to implement one business rule when the business rule is complex or affects more than one item or event. The business rule procedure is then called by the item or event handlers that are involved in the business rule. If the business rule is simple and affects only one item or event, implement the business rule directly in the item or event handler.

Libraries

Libraries contain reusable client-side code. They support these form coding standards by allowing the same code to be used by all forms to enforce specific validation, navigation and cosmetic behaviors and appearances.

Libraries allow code to be written once and used by multiple forms. Additionally, because the executables attach at runtime, they facilitate development and maintenance without being invasive to a form.

Every form requires several standard triggers and procedures to link the form with a library. Many of these triggers and procedures have a default behavior that a developer overrides for specific items or blocks.

See: Special Triggers in the TEMPLATE form .

Application-Specific Libraries

Each application is strongly encouraged to create its own libraries. Typically, each application creates a central library that governs behaviors of objects found throughout many of its forms. Additional libraries should be created for each major transaction form to facilitate the following:

All libraries should reside in the $AU_TOP/resource directory (or its equivalent).

Attaching Libraries

Sometimes library attachments can be lost on platforms that have case-sensitive filenames. By Oracle E-Business Suite standards, library names must be in all uppercase letters (except for the file extension). However, for forms developed using Microsoft Windows, the library filename may be attached using mixed case letters, making the attachment invalid on case-sensitive platforms such as UNIX. If you attach a library to a form in the Oracle Forms Developer on Microsoft Windows, you should avoid using the Browse mechanism to locate the file. Instead, type in just the filename, in uppercase only, with no file extension (for example, CUSTOM). Oracle Forms will then preserve the attachment exactly as you typed it. Note that your attachment should never include a directory path; your Forms path should include the directory that holds all your libraries.

Performance

Performance is a critical issue in any application. Applications must avoid overloading the network that connects desktop client, server, and database server computers, since often it is network performance that most influences users' perceptions of application performance.

Oracle E-Business Suite products are designed to minimize network traffic on all tiers. For example, they try to limit network round trips to one per user-distinguishable event by employing the following coding standards:

.See: Views and Server Side versus Client Side.

Coding for Web Compatibility

Following Oracle E-Business Suite standards carefully will help ensure that your forms can be deployed on the Web.

You should avoid using the following features in your forms, as they are not applicable in this architecture:

The Standard Development Environment

These coding standards assume that you are developing code in the appropriate Oracle E-Business Suite development environment, which includes compatible versions of several products. You can ensure that you have all the correct versions of the Oracle E-Business Suite and other Oracle products by installing all products from one set of Oracle E-Business Suite Release 12 CDs.

While you can develop forms using the standard Oracle Forms Developer, you cannot run your Oracle E-Business Suite-based forms from the Oracle Forms Developer. Running such forms requires additional Oracle Application Object Library user exits referred to by the libraries, as well as settings and runtime code that can only be seen when running forms through a browser with JInitiator. Both the libraries and the user exits also assume a full installation of the Oracle Application Object Library database schema, as they reference tables, views, and packages contained therein.

Mandatory Settings for Running Oracle E-Business Suite

The html file used to launch Oracle E-Business Suite must include several specific settings for Oracle E-Business Suite to function properly. The following table contains the required parameters and their required values:

Name Value
colorScheme blue
lookAndFeel oracle
separateFrame true
darkLook true
readOnlyBackground automatic
dontTruncateTabs true
background no

Additionally, the file OracleApplications.dat must contain the following lines:

app.ui.requiredFieldVABGColor=255,242,203
app.ui.lovButtons=true
app.ui.requiredFieldVA=true

There are several variables that must be set correctly, either as UNIX environment variables or NT Registry settings, before starting up your Forms Server for running Oracle E-Business Suite. These variables include NLS_DATE_FORMAT. NLS_DATE_FORMAT must be set to DD-MON-RR.

For additional information, see Oracle E-Business Suite Installation Guide: Using Rapid Install

Mandatory Settings for Form Generation

At form generation time, make sure you designate the character set designed for your language in the NLS_LANG variable in your Windows NT registry or environment file (for Unix). You must ensure that the character set you specify is the character set being used for your Oracle E-Business Suite installation.

You must also set the value of your Forms path environment variable in your environment file (or platform equivalent such as Windows NT registry) to include any directory that contains forms, files, or libraries you use to develop and generate your forms. Specifically, you must include a path to the <$AU_TOP>/forms/US directory to be able to find all referenced forms, and a path to the <$AU_TOP>/resource directory to be able to find the Oracle E-Business Suite library files you need (where <$AU_TOP> is the appropriate directory path, not the variable).

Recommended Setting for Form Development

Oracle Forms Developer allows referenced objects to be overridden in the local form. Oracle Forms Developer also does not normally provide any indication that an object is referenced unless you set a special environment variable (Registry setting for NT). Set the environment variable (Registry setting) ORACLE_APPLICATIONS to TRUE before starting Oracle Forms Developer. This setting allows you to see the reference markers (little flags with an "R" in them) on referenced objects so you can avoid changing referenced objects unintentionally. Any object referenced from the APPSTAND form must never be changed.

Warning: Oracle Forms Developer allows referenced objects to be overridden in the local form. Any object referenced from the APPSTAND form must never be changed.

Oracle Application Object Library for Release 12

Oracle Application Object Library includes (partial list):

Setting Object Characteristics

The characteristics of most form objects, including modules, windows, canvases, blocks, regions, and items may be set in the following ways:

Shared Objects

These standards rely extensively on the object referencing capabilities of Oracle Forms. These capabilities allow objects to be reused across multiple forms, with changes to the master instance automatically inherited by forms that share the object. Additionally, these shared objects provide flexibility for cross-platform support, allowing Oracle E-Business Suite to adhere to the look and feel conventions of the platform they run on.

APPSTAND Form

The APPSTAND form contains the master copy of the shared objects. It contains the following:

TEMPLATE Form

The TEMPLATE form is the required starting point for all development of new forms. It includes references to many APPSTAND objects, several attached libraries, required triggers, and other objects.

Start developing each new form by copying this file, located in $AU_TOP/forms/US (or your language and platform equivalent), to a local directory and renaming it as appropriate. Be sure to rename the filename, the internal module name, and the name listed in the call to FND_STANDARD.FORM_INFO found in the form-level PRE-FORM trigger.

Overview of the TEMPLATE Form.

FNDMENU

The Oracle E-Business Suite default menu (with menu entries common to all forms, such as File, Edit, View, Help, and so on) is contained in the $AU_TOP/resource/US directory (or its equivalent) as the file FNDMENU. You should never modify this file, nor should you create your own menu for your forms.

Standard Libraries

Application Object Library contains several libraries that support the Oracle E-Business Suite User Interface Standards for Forms-Based Products:

The TEMPLATE form includes attachments to the FNDSQF, APPCORE and APPDAYPK libraries. Other standard Oracle E-Business Suite libraries are attached to those libraries and may appear to be attached to the TEMPLATE form.

See: Libraries in the TEMPLATE Form Any code you write within a form that is based on the TEMPLATE form may call any (public) procedure that exists in these libraries. If you code your own library, you will need to attach the necessary libraries to it.

Property classes

Property classes are sets of attributes that can be applied to almost any Oracle Forms object. The TEMPLATE form automatically contains property classes, via references to APPSTAND, that enforce standard cosmetic appearances and behaviors for all widgets and containers as described in the Oracle E-Business Suite User Interface Standards for Forms-Based Products.

Do not override any attribute set by a property class unless this manual explicitly states that it is acceptable, or there is a compelling reason to do so. Overriding an inherited attribute is very rarely required.

Application-specific Property Classes, Object Groups and Objects

Each application should take advantage of the referencing capabilities of Oracle Forms to help implement standards for their particular application in the same manner as APPSTAND.

For example, the General Ledger application might have specified standard widths and behaviors for "Total" fields throughout the application. A GL_TOTAL Property Class, referenced into each form, could set properties such as width, format mask, etc. A General Ledger developer, after referencing in this set of property classes, can then simply apply the GL_TOTAL property class to each item in the form that is a Total field and it inherits its standard appearance and behavior automatically. Entire items or blocks can also be reused.

Further, property classes can be based on other property classes, so the GL_TOTAL class could be based on the standard TEXT_ITEM_ DISPLAY_ONLY class in APPSTAND. Such subclassing allows the application-specific object to inherit changes made within APPSTAND automatically.

Most Oracle E-Business Suite products also have a "standard" form (typically called [Application short name]STAND, such as GLSTAND or BOMSTAND) in the same directory if you install the development versions of those products. These files are used for storing application-specific object groups, property classes, and other objects that are referenced into Oracle E-Business Suite forms.

Visual Attributes

All of the visual attributes described in the Oracle E-Business Suite User Interface Standards for Forms-Based Products are automatically included in the TEMPLATE form via references to APPSTAND. Each visual attribute is associated with a property class or is applied at runtime by APPCORE routines.

For detailed information about the specific color palettes and effects of the visual attributes, see the Oracle E-Business Suite User Interface Standards for Forms-Based Products.

Overview of Building an Oracle E-Business Suite Application

An application that integrates with Oracle E-Business Suite consists of many pieces, including but not limited to forms, concurrent programs and reports, database tables and objects, messages, menus, responsibilities, flexfield definitions, online help, and so on.

Building an application also requires that you consider many overall design issues, such as what platforms and languages your application will run on, what other applications you will integrate with, maintenance issues, and so on.

Overall Design Issues to Consider

When designing your application, you should keep in mind that many Oracle E-Business Suite features affect various facets of your application including database objects, forms, concurrent programs, and so on, and including these features should be considered from the beginning of your application design process. These features include but are not limited to:

Overview of Application Development Steps

This is the general process of creating an application that integrates with Oracle E-Business Suite.

  1. Register your application. See the Oracle E-Business Suite System Administrator's Guide - Configuration.

  2. Set up your application directory structures. See: Overview of Setting Up Your Application Framework.

  3. Modify the appropriate environment files. See: Oracle E-Business Suite Concepts.

  4. Register your custom Oracle schema. See: Oracle E-Business Suite System Administrator's Guide - Configuration.

  5. Include your custom application and Oracle schema in data groups. See: Oracle E-Business Suite System Administrator's Guide - Configuration.

  6. Create your application tables and views. See: Tables. See: Views.

  7. Integrate your tables and views with the Oracle E-Business Suite APPS schema. See: Integrating Custom Objects and Schemas.

  8. Register your flexfields tables. See: Table Registration API.

  9. Build your application libraries and forms. See: Overview of Form Development Steps.

  10. Build your application functions and menus. See: Overview of Menus and Function Security.

  11. Build your application responsibilities. See the Oracle E-Business Suite System Administrator's Guide - Security.

  12. Build concurrent programs and reports. See: Overview of Concurrent Processing.

  13. Customize Oracle E-Business Suite forms if necessary using the CUSTOM library. See: Customizing Oracle E-Business Suite with the CUSTOM Library.

Overview of Form Development Steps

This is the general process of building a form that integrates with Oracle E-Business Suite.

  1. Copy the form TEMPLATE and rename it. See: Overview of the TEMPLATE Form.

  2. Attach any necessary libraries to your copy of TEMPLATE. TEMPLATE comes with several libraries already attached. See: Overview of the TEMPLATE Form.

  3. Create your form blocks, items, LOVs, and other objects and apply appropriate property classes. See: Setting the Properties of Container Objects. See: Setting the Properties of Widget Objects.

  4. Create your window layout in adherence with the Oracle E-Business Suite User Interface Standards for Forms-Based Products.

  5. Add table handler logic. See: Coding Table Handlers.

  6. Code logic for window and alternative region control. See: Controlling Window Behavior.

  7. Add Find windows and/or Row-LOVs and enable Query Find. See: Overview of Query Find.

  8. Code logic for item relations such as dependent fields. See: Item Relations.

  9. Code any messages to use Message Dictionary. See: Overview of Message Dictionary.

  10. Add flexfields logic if necessary. See: Overview of Flexfields.

  11. Add choices to the Special menu and add logic to modify the default menu and toolbar behavior if necessary.

  12. Code any other appropriate logic.

  13. Test your form by itself.

  14. Register your form with Oracle Application Object Library. See: Forms Window.

  15. Create a form function for your form and register any subfunctions. See: Overview of Menus and Function Security.

  16. Add your form function to a menu, or create a custom menu. See: Overview of Menus and Function Security.

  17. Assign your menu to a responsibility and assign your responsibility to a user. See: Oracle E-Business Suite System Administrator's Guide - Security.

  18. Test your form from within Oracle E-Business Suite (especially if it uses features such as user profiles or function security).