Chapter 6:

Creating Custom Forms

Guide to Oracle 10g

 Lesson B Objectives

After completing this lesson, you should be able to:

• Suppress default system messages
• Create alerts and messages to provide system
feedback to users
• Create applications that avoid user errors
• Trap common runtime errors

Guide to Oracle 10g 2

 Controlling System Messages
• Forms Services message line
– Displays FRM- and ORA- messages
– Classified according to
• Severity
• Whether or not they require user intervention
• Suppress default system messages
– Replace with custom messages
– Set :SYSTEM.MESSAGE_LEVEL variable
• In PRE-FORM trigger
• :SYSTEM.MESSAGE_LEVEL := message_level;
• :SYSTEM.MESSAGE_LEVEL := 25;
3
 Providing System Feedback
• Important application design principle
– Provide users with feedback about what is
happening in application.
• caution users when they are about to make a change
that could potentially cause harm
• Make applications forgiving
– Allow users to undo unintended operations
• To provide feedback in forms, you create custom
messages and alerts.

Guide to Oracle 10g 4

 Custom Messages

• A custom message is a short text string that

displayed on form message line
– Up to 200 characters
• Syntax:
– MESSAGE('message_string');

Guide to Oracle 10g 5

6
To add custom messages to the Projects form:
1. Open the Layout Editor, right-click the Save New button, and
then click PL/SQL Editor to open the button trigger.
2. To display a custom message when the user saves a new
record, add the following command as the last command in
the trigger:
MESSAGE('Record inserted.');
3. Compile the trigger, correct any syntax errors, and then close
the PL/SQL Editor.
4. To display a custom message when the user updates an
existing record, right-click the Update button, click PL/SQL
Editor, and then add the following command as the last
command in the trigger:
MESSAGE('Record updated.');
5. Compile the trigger, correct any syntax errors, close the
PL/SQL Editor, and then save the form. 7
 Alerts
• Alert is a dialog box
– Display text message longer than 200 characters
– Displays one or more buttons
• Allow user to select between alternatives that execute
associated program statements
• It is needed when:
– The feedback requires a longer message than will fit
on the message line.
– The user needs to select between alternate ways to
proceed.
– For important messages that the user needs to
acknowledge.
8
 Alerts (continued)
• An alert is a top-level form object.
– To create a new alert, select the Alerts node in the Object
Navigator, and then click the Create button. Then,
specify the alert properties.
• The Title property determines the title that appears in
the alert window title bar.
• The Message property defines the text that appears in
the alert.
• The Style property value specifies the icon that
appears on the alert.

9
Guide to Oracle 10g 10
 Alerts (continued)
• Styles:
– Note displays an “i” for information, conveys
information to the user
• Such as confirming that the form has inserted a record.
– Caution displays an exclamation point (!), inform the user
that he or she is about to make a choice that cannot be
undone and could lead to a potentially damaging situation,
• such as deleting a record
– Stop display a red "X" or a red stoplight
– inform the user that he or she has instructed the system to
perform an action that is not possible
• such as trying to delete a record that is referenced as a foreign
key in another table. 11
 Alerts (continued)

• Button Label property determines:

– How many buttons appear on alert
– Labels on buttons
– Maximum 3 buttons
• Button 1 Label, Button 2 Label, and Button 3
Label. If you delete the label for a given button,
then that button no longer appears on the alert.

12
To create the alert:
1. Open the 6BProjects.fmb form in the Chapter6\Tutorials folder on your
Solution Disk, and save the form as 6BProjects_ALERT.fmb in the
Chapter6\Tutorials folder on your Solution Disk. (If you did not create
the 6BProjects.fmb form earlier in the lesson, a copy of this file is in the
Chapter6 folder on your Data Disk.)
2. Make sure that the Object Navigator window is open in Ownership
View, then select the Alerts node under the PROJECT_FORM node.
3. Click the Create button on the Object Navigator toolbar to create a new
alert object.
4. Double-click the Alert icon beside the new alert to open its Property
Palette, and then change its properties as follows:

13
5. Close the Property Palette, and then save the form.
 Alerts (continued)

• To declare/display alert:
DECLARE
alert_button NUMBER;
BEGIN
alert_button:=
SHOW_ALERT('alert_name');
END;

Guide to Oracle 10g 14

 Example Alert

Guide to Oracle 10g 15

 Syntax to Display an Alert and Execute
Alternate Commands Depending on the
Button the User Clicked
• To execute alternate program commands depending on the alert
button that the user clicks, you create an IF/ELSIF decision
control structure

16
• To create the program unit to display the alert:
1. In the Object Navigator window, select the Program
Units node, and then click the Create button to
create a new program unit.
2. Type DISPLAY_ALERT for the new program unit
name, make sure that the Procedure option button is
selected, and then click OK.
3. Modify the procedure so it appears as shown
in Figure 6-24 . Then compile the code, correct any
syntax errors if necessary, close the PL/SQL Editor,
and save the form.

Guide to Oracle 10g 17

• Next, you need to modify the trigger for the
Update button so that it calls the
DISPLAY_ALERT program unit instead of
committing the transaction to the database.
• Then you run the form, select and update a
record, and display the alert.

Guide to Oracle 10g 18

To modify the Update button trigger, then run the form:
1. Open the Layout Editor, right-click the Update button, and then
click PL/SQL Editor.
2. Delete the COMMIT; command, and replace it with the following
command that calls the DISPLAY_ALERT program unit:
DISPLAY_ALERT;
3. Compile the trigger, correct any syntax errors, close the PL/SQL
Editor, and save the form.
4. Run the form, make sure that the insertion point is in the Project
ID field, open the LOV display, select the record for Project ID 1,
and then click OK. The data values for the project appear in the
form text items.
5. Place the insertion point in the Manager ID field, open the LOV
display, select the record for consultant ID 102 (Brian Zhang),
click OK, and then click Update. UPDATE_ALERT appears, as
shown in Figure 6-22 . 19
6. Click OK. The confirmation message "Record updated."
appears on the message line.
7. Make sure that the insertion point is in the Project ID field,
open the LOV display, select the record for Project ID 1
again, and then click OK. The data values for the project
appear in the form text items, showing the updated project
manager value.
8. Place the insertion point in the Manager ID field, open the
LOV display, select the record for consultant ID 103 (Sarah
Carlson), click OK, and then click Update. The alert
appears again. This time, you cancel your changes.
9. Click Cancel. The "Record not updated." message appears,
and the form fields are cleared.
10. Close the browser window, and then close the form in
Forms Builder.
20
 Avoiding User Errors

• Forms help users avoid errors(such as entering an

incorrect data value, or clicking a button at the wrong
time) by:
– Configure forms that validate input values
– Programmatically disable form command buttons
– Disable navigation for form text items containing
values that users should not change

Guide to Oracle 10g 21

 Validating Form Input Values

• Validate input values

– Ensure that values meet specific preset
requirements
– Use
• Text item validation properties
• Form validation triggers

Guide to Oracle 10g 22

 Text Item Validation Properties
• A form can validate a text item's value using specific text item
validation properties.

23
Validating Form Input Values (continued)
• You can perform complex validation operations by
using validation triggers.
• Item validation trigger
– Item-level trigger
– Associate with item’s WHEN-VALIDATE-ITEM event
– Fires when item is validated
• As determined by form validation unit
• The trigger code tests the current item value to determine
if it satisfies the validation condition or conditions.
– If not valid
• Raises built-in exception named
FORM_TRIGGER_FAILURE
24
To create and test an item validation trigger:
1. In the Layout Editor, select the Class text item, right-click, point to
SmartTriggers, and then click WHEN-VALIDATE-ITEM. The
PL/SQL Editor opens.
2. Type the following command in the PL/SQL Editor to create the
validation trigger:
IF NOT :student.s_class IN ("FR", 'SO', 'JR', 'SR') THEN
MESSAGE('Legal values are FR, SO, JR, SR');
RAISE FORM_TRIGGER_FAILURE;
END IF;
3. Compile the trigger, correct any syntax errors, close the PL/SQL
Editor, and save the form.
4. Run the form, and click Create. A new Student ID value appears.
5. Place the insertion point in the Class field, type AA, and then press
Tab. The message "Legal values are FR, SO,JR, SR" appears on the
message line, indicating that the item validation trigger fired correctly.
6. Close the browser window. 25
 Disabling Form Command Buttons to
Avoid User Errors
• when a user clicks the Create button on the Students form, a new
Student ID value appears on the form. The user must enter values into
the other form text items, and then click the Save New button, to save
the new record. If the user clicks the Save New button without
clicking the Create button, then the form does not retrieve the Student
ID value from the sequence, and risks having a duplicate primary
key. Therefore, when the form first opens, the Save New button
should be disabled (grayed-out). The Save New button should not be
enabled until after the user has clicked the Create button.

26
 Disabling Form Command Buttons to
Avoid User Errors

• To disable a command button when a form first opens, you

open the command button's Property Palette and set the
Enabled property to No.
• Enable or disable button while form running:
– SET_ITEM_PROPERTY('item_name',
property_name, property_value);
– SET_ITEM_PROPERTY('UPDATE_BUTTON',
ENABLED, PROPERTY FALSE);

Guide to Oracle 10g 27

To change and test the button properties:
1. In the Layout Editor, right-click the Save New button, and then click
Property Palette. To disable the button when the form first opens,
change the Enabled property value to No, and then close the
Property Palette.
2. Right-click the Create button, and then click PL/SQL Editor. The
button trigger code appears. To enable the Save New button, add the
following command as the last command in the trigger:
SET_ITEM_PROPERTY('SAVE_BUTTON', ENABLED,
PROPERTY_TRUE);
3. Compile the trigger, and debug it if necessary, then close the
PL/SQL Editor.
4. Save the form, and then run the form. The Save New button appears
disabled when the form first opens.
5. Click Create. A new value appears in the Student ID text item, and
the Save New button is now enabled.
6. Close the browser window. 28
 Disabling Text Item Navigation
• Nonnavigable:
– not allowing users to directly update text items that
contain primary key values is to make these text items
nonnavigable.
– User cannot press Tab key to place insertion point in
text item
– Set item’s Keyboard Navigable property to No
– User can still click mouse pointer in text item to enter
value
• Create trigger that moves insertion point to another form
item
• WHEN-MOUSE-UP event
29
To make the text item nonnavigable and switch the form
focus when the user clicks the mouse in the text item, then
run the form:
1. In the Layout Editor, double-click the S_ID text item to
open its Property Palette. Scroll down to the Navigation
node, select the Keyboard Navigable property, open the
list, select No, and then close the Property Palette.
2. To create the trigger to change the form focus to the
Create button when the user clicks the mouse pointer in
the S_ID text item, right-click the S_ID text item, and
then click PL/SQL Editor. Select WHEN-MOUSE-UP
from the list, and then click OK.

Guide to Oracle 10g 30

3. Type the following command in the Source code pane,
compile the trigger, correct any syntax errors, and then
close the PL/SQL Editor and save the form.
GO_ITEM('STUDENT.CREATE_BUTTON');
4. Run the form. Note that because the Student ID text item is
now nonnavigable, the insertion point initially appears in
the Last Name text item instead of in the Student ID text
item.
5. Click the insertion point in the Student ID text item. Note
that the form focus switches to the Create button.
6. Press Tab 3 times. Note that the insertion point does not
appear in the Student ID text item, but moves directly to
the Last Name text item.
7. Close the browser window, and then close the form in
Forms Builder.
31
 TRAPPING COMMON RUNTIME
ERRORS

• It is a good practice to trap these errors, which

means to intercept the default system error
message and replace it with a custom error
message.
• The custom error message gives more detailed
information to the user about how to correct the
error.

Guide to Oracle 10g 32

 Generating Runtime Errors

• Deliberately generate errors while updating and

deleting records
– View error messages

33
 Trapping Form Runtime Errors

• ON-ERROR event occurs

– Whenever ORA- or FRM- error occurs while form
running
• Create form-level trigger that corresponds to ON-
ERROR event
– Use decision control structure to handle different
errors

Guide to Oracle 10g 34

Forms Builder Built-in Procedures for
Handling Errors

Guide to Oracle 10g 35

• If an FRM- error occurs, the ERROR_CODE
procedure returns the corresponding FRM- error
code.
• If an ORA- error occurs, the
DBMS_ERROR_CODE procedure returns the
corresponding ORA- error code.
• You can create an IF/ELSIF decision structure in
the ON-ERROR trigger that traps errors based on
the values of ERROR_CODE and
DBMS_ERROR_CODE, and then displays
custom messages or alerts to provide users with
informative messages and alternatives.
36
 General Syntax for an ON-ERROR
Trigger

Guide to Oracle 10g 37

• To create and test the ON-ERROR trigger:
1. In Forms Builder, make sure that the Object Navigator
window is open. To create a form-level trigger, select the
Triggers node directly below the form module, then click the
Create button.
2. In the INVENTORY_FORM: Triggers dialog box, select
ON-ERROR in the list, and then click OK. The PL/SQL
Editor opens.
3. Type the commands in Figure 6-28 , compile the code,
correct any syntax errors, and then close the PL/SQL Editor.
4. Save the form and then run the form. Make sure that the
insertion point is in the Item ID field, open the LOV display,
select Item ID 2 (3-Season Tent), click OK, and then click
Delete in the Items frame. The event handler message for
the ORA-02292 error ("This record is referenced by other
database tables.") appears. 38
.
5. Place the insertion point in the Inventory ID field, open
the LOV display, select ID 2, and then click OK. Change
the QOH value to the letter a, and then click Update in
the Inventory Items frame. The event handler message
for the FRM-50016 error ("Please enter a value that is a
number.") appears.
6. Change the QOH value to 200, and then click Clear in the
Inventory Items frame to clear the frame items.
7. To test the general error handler, change the Category ID
field value in the Items frame to 10, then click
Update. Because 10 is not a valid category ID value in
the CATEGORY table, the ORA-02291 error code and
message appears in the message line.
8. Close the browser window, close the form in Forms
Builder, and then close Forms Builder, the OC4J Instance,
and SQL* Plus 39
Guide to Oracle 10g 40
Guide to Oracle 10g 41
 Lesson B Summary

• Create custom messages and alerts

– Provide feedback to users
• Validate user inputs using
– Text item validation properties
– Form validation trigger

Guide to Oracle 10g 42