|Oracle® Application Express Application Migration Guide
Part Number E13368-01
This appendix lists how objects are generated during the conversion process, or alternatively how the same functionality can be implemented post-generation if necessary.
This section contains the following topics:
This section describes various Oracle Forms components and offers a brief overview of how they are mapped to similar objects within an Oracle Application Express application or explains how they can be implemented manually post generation.
Topics in this section include:
This section provides an overview of Oracle Forms components and the corresponding Oracle Application Express generation capabilities or workarounds.
Alert messages are not generated. However, you can store an alert message as a text message in Shared Components in Oracle Application Express application. Text messages can be used to build translatable text strings with substitution variables that can be called from PL/SQL packages, procedures, and functions. See "Working with Shared Components" in Oracle Application Express Application Builder User's Guide.
A single block can be mapped to a region in Oracle Application Express. Based upon the block type and data source type (that is, table or view) identified in the Forms
XML file, some default mappings are defined. For example, a report block based upon an Oracle view, is mapped to an Interactive report in Oracle Application Express. A form block based upon a table, is mapped to an Interactive report and form in Oracle Application Express. For more information see "Block to Page Region Mappings".
In Oracle Forms, the canvas is the object on which the graphical user interface (GUI) is drawn, or the background of the form. In Oracle Application Express, the Application Express engine constructs the appearance of each page in an application using templates. Templates define how pages, page controls, and page components display. Canvases are ignored when generating pages for an Oracle Application Express application.
Depending on the coordinate system used in an Oracle Forms application, coordinates can be expressed in real units such as inches, centimeters, and pixels. The coordinate values cannot be automatically applied to the generated application. One unit in an Oracle Application Express item width might not be equal to one physical pixel in an Oracle Forms application. While Oracle Forms enables specific placement of individual fields by specifying coordinates, Oracle Application Express uses standard HTML tables and all items are positioned relative to other elements and columns within the HTML table.
In Oracle Forms, editors provide standard editing features, including search and replace and cut, copy, and paste for text items. For a selected text item, an editor is mapped to a HTML editor in Oracle Application Express.
A list of values (LOV) can be mapped to an equivalent list of values in Oracle Application Express. When LOVs are selected for inclusion in the conversion to Oracle Application Express their associated record group is included in the conversion. For more information, see the "List of Values Implementation".
In the post-generation phase of the Forms Conversion process, program units can be incorporated into your Oracle Application Express application as a PL/SQL package, page process, computation or validation. For more information, see "Implementing Business Logic".
In Oracle Forms, a property class is a named object that contains a list of properties and their settings. An object based on a property class can inherit the settings of any property in that class. Similarly, in Oracle Application Express, a theme is a named collection of templates used to define the user interface of an application. Oracle Application Express has a repository of 20 themes, and you can also create your own custom themes. Property classes are not used within the generation of Oracle Application Express applications.
In Oracle Forms, LOV values are derived from a record group. When a record group is defined, it is associated with a SQL query. When a LOV is generated in Oracle Application Express, the associated record group is used to determine the SQL Query for that LOV. For more information, see "List of Values Implementation".
An Oracle Forms trigger is an event-handler written in PL/SQL to augment the default processing behavior. The trigger logic can be incorporated into an Oracle Application Express application as a computation, validation, or PL/SQL process in the post-generation phase. Where feasible,
POST-QUERY block trigger logic is automatically incorporated in the generated Oracle Application Express application, as part of the Enhanced Query generation. For more information refer to "Implementing Business Logic".
Visual attributes are the font, color, and pattern properties that you can set for form and menu objects that appear in an Oracle Forms application's interface. Using the default cascading style sheets (CSS) installed with Oracle Application Express, or by uploading your own CSS files, style can be applied to your Oracle Application Express application. See "Using Custom Cascading Style Sheets" in Oracle Application Express Application Builder User's Guide.
A window is the container for all visual objects that comprise an Oracle Forms application, including canvases. In Oracle Application Express, a page holds all of the visual objects for an application. Due to the block mapping resulting in multiple pages, the windows are not used in the conversion process.
Generated forms for inserting, updating, or deleting records include automatic row fetch processes to load existing records and automatic row processes to commit changes to the Oracle Database table. Forms also include generated validations for mandatory columns, and column types of number or date.
The generation process assumes that the primary key for an Oracle table is non-updatable, maintained using a database trigger, and has a maximum of two parts.
If the primary key is updatable then the generated application must be modified post-generation. You must modify the item attributes for the primary key. By default, these attributes are generated but displayed as hidden and protected. If there is no database trigger defined to automatically fetch the primary key when inserting a record, then the application will fail when attempting to insert a record. To avoid this error either define a database trigger or modify the generated application post-generation to populate the primary key value before processing the record. To populate the primary key value within the application you can use the item default, create a computation, or create a process. If creating a computation or process it is important to include a condition so that execution only occurs when inserting a record (for example, when the primary key item is
Oracle Application Express does not support cascading multiple part keys where the key for a child is defined as the primary key of the parent with a counter for each child within that parent key. In such cases, you must define a distinct primary key for the child table with an appropriate means of populating the primary key.
When an Oracle Form is loaded into an Oracle Application Express project, the various blocks are analyzed to determine how they will be generated. The conversion process uses information such as block relations, the number of records displayed, and whether insert or update are allowed. There are inherent differences between Oracle Forms and Oracle Application Express that have a direct bearing on the resulting pages that are generated.
Except for specific master-detail relationships, each block is generated onto a separate Oracle Application Express page. Furthermore, the canvases specified in Oracle Forms are ignored as multiple blocks are not generated as separate regions on the same page within Oracle Application Express. The sections that follow explains different Oracle Forms block types and how they are mapped into an Oracle Application Express application.
In Oracle Forms a single record block can be used for both querying data and updating the records returned. Within Oracle Application Express, standard updatable regions cannot also be used as query regions. When an Oracle Forms block is defined as being insertable, updatable, and has a primary key, then the generation mapping defines an interactive report with a form. The interactive report enables you to query the records and the generated Edit link provides navigation to an individual record for update or deletion. A Create Record button enables you to insert records.
If not all the conditions are satisfied then only an interactive report is generated for a single record block. Therefore, only an interactive report is generated and not the corresponding form if one of the following conditions exist:
the number of records displayed is greater than one
INSERT allowed is set to false
UPDATE allowed is set to false
there is no primary key defined for the underlying table
the block is based on a view
The interactive report uses the original query, enhanced query, or custom query defined within the project for the block. However, the form is based only on the underlying table. Items characteristics such as radio groups, check boxes, date pickers, editors and list of values will be generated where possible.
A tabular form defined in Oracle Forms is generated as a tabular form in Oracle Application Expresss providing the number of records displayed is greater than one. Implementing item characteristics, such as select lists, needs to be performed manually post-generation. Non-database items specified in Oracle Forms are not be generated into the tabular form generated by Oracle Application Express, even if they have been included. Implementing non-database items in a tabular form needs to be performed manually post-generation. For more information, see "How to Create a Tabular Form" in Oracle Application Express Advanced Tutorials.
Currently adding validations and non-database items on a tabular form is non-declarative and is covered in the Oracle Application Express Advanced Workshop course. An alternative is to manually create a report and form to replace the tabular form post-generation where it is much easier to add validations and add items without a source of database.
Within Oracle Forms, master detail forms are defined using block relations. There are several additional criteria that must be examined in order to determine what will be generated for an Oracle Forms master detail relationship. The master block is generated as one of the following:
An interactive report and a master-detail form
An interactive report and a form only
Only an interactive report
The detail blocks are generated independently as either a single record block or a tabular form based on the mappings provided.
An interactive report and master-detail form is only be generated if all the following criteria are satisfied:
The master and detail blocks are both based on tables, but not the same table, and both have primary keys.
There is only one detail block.
There is a valid foreign key relationship between the master and detail blocks.
The block relations are correctly defined with the Oracle Forms file.
When a master detail form is generated, the detail page is also created within Oracle Application Express. You can manually remove the detail page when reviewing the pages to be generated prior to creating the Oracle Application Express application, or you can delete it manually post-generation.
Alternatively, if both the master and the single detail block are based on the same table and that table has a primary key, then two interactive reports and forms are generated for each block. It is recommended that you manually modify one of the resulting forms post-generation to combine the functionality into a single form and delete the second interactive report and form. However, if the table does not have a primary key or is based on a view then only reports are generated.
Oracle Application Express cannot include more than one tabular form on a page. Therefore, when a file with a master and multiple detail blocks is loaded, the relations are ignored and the master block and each detail block are treated independently as either a single record block or a tabular form based on each blocks properties.
If there is no valid foreign key relationship and the table has a primary key, then the master block is generated as an interactive report and form. Otherwise, it is generated as an interactive report.
If a block is not associated with a database table or view then the block is not included for generation. These blocks typically hold menus, navigation bars, and buttons. Given that such components are handled and defined very differently within Oracle Application Express it is not appropriate to generate separate pages for these. However, such blocks can be included if required and will be generated as blank pages.
Oracle Application Express dynamic list of values (LOVs) enable one display value and one return value to be defined within an SQL. You can specify LOVs individually for an item or define as a named shared component which can be used with any item throughout the application.
Oracle Forms record groups define the query for each list of values. These record groups are analyzed to determine whether the corresponding LOV can be generated. A named shared component LOV is created utilizing the query from the record group and then specified on the corresponding Oracle Application Express item. The implementation style used in Oracle Forms determines whether the item is implemented as a select list or pop-up list of values.
Where there are multiple display columns in the record group only one is used in the resulting Oracle Application Express LOV query. If the record group uses bind variables as parameters, Oracle Application Express application items are defined and referenced within the resulting LOV query.
Within Oracle Forms applications, business logic is often interspersed with Oracle Forms user interface functionality. The Oracle Forms user interface functionality used to manipulate the screen (for example,
set_item_property and so on) are often not appropriate within Oracle Application Express due to the inherent differences in the user interface.
Business logic can be found in Oracle Forms triggers and program units, or in PL/SQL libraries. The business logic can be written directly into the objects as SQL or PL/SQL. This code may in turn call database packages, procedures, or functions. The underlying tables may also have database triggers defined which implement business logic.
Because database triggers operate on the underlying tables regardless of the user interface, they do not need to be altered when converting an application to Oracle Application Express. You can call database packages, procedures, or functions from Oracle Application Express because it also uses SQL and PL/SQL. Note that these database objects do not need to be altered when used within the Oracle Application Express development environment.
In order to re-implement the business logic defined within Oracle Forms you must analyze the triggers, program units, and PL/SQL libraries and manually write corresponding logic within Oracle Application Express. Note that Oracle Forms triggers, program units, and PL/SQL library code are not automatically generated except for
POST-QUERY triggers can be incorporated into Enhanced Queries as part of the block definition and subsequently included in the Oracle Application Express application.
Oracle Application Express uses processes, computations, and validations to implement such business logic. Before undertaking the post-generation task of re-implementing business logic, it is important to understand how and when to invoke the various types of processes, computations, and validations. It is also important to understand how conditional processing can be applied to these types of components to customize the circumstances under which they execute. For more information, see Oracle Application Express Application Builder User's Guide.
Processes are logic controls used to execute data manipulation language (DML) or PL/SQL. A process performs an action at a specified point during the rendering or submission of the page. For example, you can create a process to execute logic or to make a call to the Application Express engine. A process is a unit of logic that runs when a specific event occurs, such as loading or submitting a page. For more information, see "Understanding Page Processes" in Oracle Application Express Application Builder User's Guide.
Processes can be defined as either an application-level process or a page-level process. From a functional perspective, there is no difference between page-level and application-level processes. Application-level processes can be called form any page within the application and may be called On Demand which is especially useful when you have PL/SQL logic that you would like to run from different execution points across multiple pages. Page-level processes can only be called from the page on which they are defined.
Computations are units of logic used to assign a value to an identified item when a page is submitted or displayed.
Computations can be defined as either an application-level computation or a page-level computation. Most application-level computations are performed for every page in an application. In contrast, computations created at the page-level only execute when that page is rendered or processed. For more information, see "Understanding Page Computations" and "Understanding Application Computation in Oracle Application Express Application Builder User's Guide.
Validations enable you to create logic controls to verify whether user input is valid. For example, a validation can check whether a value has been entered into a mandatory field. When a validation fails then an error message is displayed and subsequent page processes and computations will not occur. For more information, see "Understanding Validations" in Oracle Application Express Application Builder User's Guide.
There are two distinct types of validations:
Item-level validations which are specific to a single item.
Page-level validations which do not apply to any single item, but apply to an entire page.
There are several validation methods:
SQL - Compares item values to data in the database.
PL/SQL - Enables you to enter complex logic to validate entered data.
Item Level Null - Checks if an item's value in session state is
Item String Comparison - Compares the value of an item to a specific string.
Regular Expression - Provides a method to describe text patterns.
The underlying SQL query used to define an Oracle Report is used within Oracle Application Express when generating an interactive report. When one or more Oracle Report files are loaded, an additional Reports page is generated with links to each of the generated interactive report pages. You will need to manually implement additional logic defined within the Oracle Report post-generation. Oracle Application Express supports the creation of printable reports utilizing Oracle Bi Publisher, Apache FOP, or another standard XSL-FO report processing engine. To learn more, see:
PL/SQL libraries contain logic which can be called from any of the Forms Modules to which it is linked. Such libraries are primarily used to define commonly used business logic that must be manually re-implemented post-generation. See "Implementing Business Logic". Generally such logic should be implemented as application-level processes so that they can be called from any generated page.
Oracle Forms menus are not automatically generated within Oracle Application Express. Oracle Application Express uses lists displayed in a region to replicate a menu structure. The default generation process creates a Home page with a list of horizontal images as the basis for a menu within your Oracle Application Express application. This list can be manually updated post-generation to incorporate conditional logic to implement the business logic defined within the Forms Menu. For information, see "Creating Lists" in Oracle Application Express Application Builder User's Guide.
Object Libraries contain common visual elements used to define Oracle Form layouts for specified components. These visual elements are not used within the Oracle Application Express generation process. You must manually create these visual attributes contained within these libraries post-generation. Depending on the visual attribute there are different ways of implementing such features including customizing templates, shared list of values, item types, item attributes and so on.