chapter 6: creating custom forms - yolaaalarfaj.yolasite.com/resources/chapter06b.pdf · ·...

$: Chapter 6: Creating Custom Forms - Yolaaalarfaj.yolasite.com/resources/chapter06b.pdf · · 2012-03-03Guide to Oracle 10g 2 ... Open the 6BProjects.fmb form in the Chapter6\Tutorials$
Chapter 6:

Creating Custom Forms

Guide to Oracle 10g

Guide to Oracle 10g 2

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

3

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;


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.


Custom Messages

• A custom message is a short text string that

displayed on form message line

– Up to 200 characters

• Syntax:

– MESSAGE('message_string');

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

8

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.

9

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.

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:

5. Close the Property Palette, and then save the form.

13


Alerts (continued)

• To declare/display alert:

DECLARE

alert_button NUMBER;

BEGIN

alert_button:=

SHOW_ALERT('alert_name');

END;


Example Alert

16

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

• 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.


• 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.


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


Validating Form Input Values

• Validate input values

– Ensure that values meet specific preset

requirements

– Use

• Text item validation properties

• Form validation triggers

23

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

validation properties.

24

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

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

26

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.

• 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);


Disabling Form Command Buttons to

Avoid User Errors

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

29

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

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.


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.


33

Generating Runtime Errors

• Deliberately generate errors while updating and

deleting records

– View error messages


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


Forms Builder Built-in Procedures for

Handling Errors

• 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

• 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


Lesson B Summary

• Create custom messages and alerts

– Provide feedback to users

• Validate user inputs using

– Text item validation properties

– Form validation trigger

chapter 6: creating custom forms - yolaaalarfaj.yolasite.com/resources/chapter06b.pdf · ·...

Documents