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
Styles: Alerts (continued) 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:= END; SHOW_ALERT('alert_name'); 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