Chapter 7: Creating Custom Forms

Data Block and Custom Forms Data block form Based on data blocks that are associated with specific database tables Reflect the structure of the database Custom form Based on control blocks that process data from multiple tables Reflect business processes rather than the database structure

Creating a Custom Form 1. Create the form 2. Create the form window and canvas manually 3. Create a control block Data block that is not associated with a specific table Contains form items that you manually draw on the canvas 4. Create form triggers to process data

Form Triggers Code that is associated with a form object and an event Can contain SQL INSERT, UPDATE, DELETE, and SELECT commands Referencing form text item values in triggers: :block_name.item_name

Program Units Self-contained programs Can be called from PL/SQL triggers Used to make triggers more modular, and reuse code within triggers

Referencing System Date and Time Values in Forms System VariableReturn Value $$DATE$$ Current operating system date $$TIME$$ Current operating system time $$DATETIME$$ Current operating system date & time $$DBDATE$$ Current DB server date $$DBTIME$$ Current DB server time $$DBDATETIME$$ Current DB server date & time

Using the Forms Debugger to Find Runtime Errors 1. Run the form using the Run Form Debug button 2. Set a breakpoint on the program line where you want to start examining variable values during execution Breakpoint

Using the Forms Debugger to Find Runtime Errors 3.Run the program and execute the trigger containing the breakpoint 4.Single-step through the code and monitor the variable values Execution arrow Variable values

Forms Debugger Variable Types  Module (block)  Current values of form items  Stack  Values of local variables declared in PL/SQL triggers or program units  Global  Values of global variables used in form triggers or program units

Strategy for Using the Forms Debugger  Single-step through the trigger and identify the program line causing the error  Run the form again and single-step through the trigger, and note the values of variables just before the line containing the error executes  Determine the cause of the error

Form Triggers Categories Block processing Interface event Master-detail processing Message handling Navigational Query time Transactional Validation

Trigger Timing PRE- Fires just before associated event occurs POST- Fires just after associated event occurs ON-, WHEN-, KEY- Fires immediately, in response to specific user actions, such as key presses

Trigger Scope Defines where an event must occur to make the trigger fire Trigger scope includes the object to which the trigger is attached, as well as all objects within that object Form-level: fires when event occurs within any block or item in the form Block-level: fires when event occurs within any item in the form Item-level: fires only when event occurs within that item

Trigger Execution Hierarchy If 2 related objects have the same trigger, the higher-level object’s trigger fires first Form & block, form’s trigger fires first Block & item, block’s trigger fires first You can specify a custom execution order on the trigger Property Palette

Navigational Triggers External navigation: occurs when user causes form focus to change Internal navigation: occurs as a result of internal form triggers that fire in response to external navigation events

User Action Triggers Fired Result on User Screen Display User starts form PRE-FORM PRE-BLOCK Form appears, but with no data visible WHEN-NEW-FORM-INSTANCE WHEN-NEW-BLOCK-INSTANCE WHEN-NEW-RECORD-INSTANCE WHEN-NEW-ITEM-INSTANCE Form is available for use Triggers That Fire at Form Startup

User Action Triggers Fired Result on User Screen Display User places the insertion point in a text item WHEN-NEW-ITEM-INSTANCE Insertion point appears in item WHEN-NEW-RECORD-INSTANCE WHEN-NEW-ITEM-INSTANCE Next record appears User clicks the Next Record button Triggers That Fire as a Result Of External Navigation

User ActionTriggers Fired Result on User Screen Display User closes the Forms Runtime window Forms Runtime window closes POST-BLOCK POST-FORM Triggers That Fire When a Form Closes

Directing External Navigation Form tab order is based on item order in Object Navigator block list Form tab order

Moving to a Specific Form Item GO_ITEM(‘:block_name_item_name’);

Oracle Error Message Severity Levels 5: informative message 10: informative message advising user of procedural error 20: condition that keeps trigger from working correctly 25 condition that keeps form from working correctly >25: extreme severity

Suppressing Lower Level System Messages Set :SYSTEM.MESSAGE_LEVEL variable to a higher level in PRE-FORM trigger :SYSTEM.MESSAGE_LEVEL := 25;

Providing User Feedback in Forms  Message  Text in message line at bottom of form  Informational only; user doesn't have to respond  Alert  Dialog box  Allows user to choose different ways to proceed

Messages Message Syntax: MESSAGE(‘message text’);

Alerts Form-level object Object properties define alert appearance Title Style icon Message Buttons

Code for Displaying an Alert DECLARE alert_button NUMBER; BEGIN alert_button := SHOW_ALERT('alert_name'); IF alert_button = ALERT_BUTTON1 THEN program statements for first button; ELSE program statements for second button; END IF; END;

Avoiding User Errors Make primary and foreign key text items non-navigable When user moves form focus to primary or foreign key text item, trigger moves focus to alternate form item

Trapping Runtime Errors  Create an ON-ERROR event trigger  Form-level trigger  Executes whenever an FRM- or ORA- error occurs  -FRM errors: generated by Forms Runtime  -ORA errors: generated by database

Form Procedures That Return System Error Information DBMS_ERROR_CODE: -ORA error code DBMS_ERROR_TEXT: -ORA error message ERROR_CODE: -FRM error code ERROR_TEXT: -FRM error message MESSAGE_CODE: most recent error code (either –ORA or –FRM) MESSAGE_TEXT: most recent error message (either –ORA or –FRM)

Structure of ON-ERROR Trigger BEGIN --trap FRM errors IF ERROR_CODE = FRM_error_code1 THEN error handler; ELSIF ERROR_CODE = FRM_error_code2 THEN error handler; … ELSE --trap ORA errors IF DBMS_ERROR_CODE = -ORA_error_code1 THEN error handler ELSIF DBMS_ERROR_CODE = -ORA_error_code2 THEN error handler … END IF END IF; END; Code to trap –FRM errors Code to trap –ORA errors

Form Validation Ensures that form data meets preset requirements so erroneous data is not sent to database Validation unit: specifies the largest data chunk that the user can enter enter before validation occurs Can be performed at the form, block, record, or item level Specified in the Validation Unit property on the form Property Palette

Types of Form Validation Data Specifies data types, lengths, and maximum and minimum values Database Specifies which operations a user can perform on a text item List of Values Specifies whether a data value must be validated against the text item’s LOV

Data Blocks vs. Control Blocks Data block Easy to create and use Is associated with a single table, and reflects the table’s structure Control block Requires a lot of custom programming Can contain items from many different tables You can link data and control blocks to take advantages of the strengths of each

Linking Data Blocks and Control Blocks 1. Create the control block as the master block 2. Create the data block as the detail block, but do not create a master-detail relationship 3. Create a master-detail relationship manually in the WHERE Clause property of the detail block: data_block_field := control_block.text_item

Displaying and Refreshing the Data Block Values Create a trigger to: Place the insertion point in the data block GO_BLOCK(‘block_name’); Flush the data block to make its data consistent with the master block and the database: EXECUTE_QUERY;

Converting a Data Block to a Control Block Create a data block and layout that contains most of the required text items Convert the data block to a control block by changing the following block properties: Database Data Block = No Required = No

Creating a Form with Multiple Canvases Users should be able to see all canvas text items without scrolling For complex applications with many text items, divide application into multiple canvases

Block Navigation Order First block in Object Navigator Data Blocks list determines block items that first appear when form opens Users can use the Tab key to navigate among different block items Canvas that contains block items automatically appears

Block Navigation Order Block order Canvas order doesn’t matter

Controlling Block Navigation Block Navigation Style property Same Record: navigation cycles through items on same block Change Data Block: navigation moves to next data block in list

Tab Canvases Multiple-page canvases that allow users to move among different canvas surfaces by clicking tabs

Tab Canvas Components Tab canvas Collection of related tab pages Tab pages Surfaces that display form items Tab labels Identifier at top of tab page A tab canvas lies on top of a content canvas

Creating a Tab Canvas Use the Tab Canvas tool on the Layout Editor tool palette to draw a tab canvas on an existing content canvas By default, a new tab canvas has 2 tab pages Create new tab pages as needed Adjust tab page properties

Important Tab Page Properties Name: how the page Is referenced in the form Label: Caption that appears on the associated tab

Adjusting the Tab Page Order Tab page that appears first is tab page whose block items appear first in the Object Navigator Block order Tab page order doesn’t matter

Stacked Canvases Canvas that appears on an existing content canvas, and can be displayed or hidden as needed Allows user to configure canvas items

Stacked Canvas Example Stacked canvas Content canvas

Creating a Stacked Canvas Use the Stacked Canvas tool on the Layout Editor tool palette to draw a stacked canvas on an existing content canvas Create block items on the stacked canvas Create buttons and triggers to display and hide the stacked canvas

Displaying and Hiding a Stacked Canvas Displaying a stacked canvas: GO_BLOCK(‘stacked_canvas_block’); SHOW_VIEW(‘stacked_canvas’); Hiding a stacked canvas: GO_BLOCK(‘stacked_canvas_block’); HIDE_VIEW(‘stacked_canvas’);