Professional Documents
Culture Documents
Page 1 of 47
Purpose
In this tutorial, you learn how to control Forms menus programmatically. You also learn to manage the interaction
between the menu and the form, and you implement application security through the menu.
Time to Complete
Approximately 1 hour .
Overview
This tutorial is aimed at Oracle Forms developers who wish to broaden their skills with the tool, enabling them to create
more user-friendly applications. You learn how you can manage custom menus.
Scenario
In this tutorial, you learn how to modify menus dynamically and how to control application security through menu
access.
You are maintaining the Orders and Customers forms. The Orders form uses a custom menu, Summit_menu. You want
to duplicate in the menu some of the functionality that is programmed into the form's buttons and triggers. You want to
be able to switch and replace menus dynamically. You also want to add security to the Customers form through its
menu.
Software Requirements
The following is a list of software requirements:
Oracle Forms Builder
Oracle database
Application server compatible with Forms Builder
This tutorial is not specific to a particular version of Forms. However, it was developed using Oracle Forms 11g
11.1.1.4, Oracle WebLogic Server 10.3.4, and Oracle database 11g 11.2.0.1.
Prerequisites
This tutorial is a follow-up to the tutorial Creating Oracle Forms Menu Modules. Before starting this tutorial, you should
perform the following setup steps::
Download the file Menu2OBE.zip and unzip it to the directory of your choice.
Ensure that the directory where you unzipped the file is included in your FORMS_PATH environment variable (set in
default.env or other environment file that you use for your application). To see how to set environment variables
for Forms Runtime, see the deployment guide for the version of Forms that you are using, such as Oracle Fusion
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 2 of 47
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 3 of 47
2 . In the Object Navigator, expand the ORDERS and TRIGGERS nodes, and then double-click the icon to the left of the
WHEN-NEW-FORM-INSTANCE node to invoke the PL/SQL editor for the trigger.
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 4 of 47
4 . Invoke the Menu Editor by double-clicking the icon to the left of the SUMMIT_MENU node, and then select the Save
node in the Menu Editor and click Create Down.
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 5 of 47
5 . Relabel the new menu item as Query by overtyping the label in the Menu Editor. This changes the display label of
the menu item and also changes the name in the Object Navigator after you enter the text.
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 6 of 47
6 . Invoke the Property Palette for the Query item by double-clicking its node in the Menu Editor, or by right-clicking its
node in the Object Navigator and selecting Property Palette .
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 7 of 47
Yes
Yes
exeqry
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 8 of 47
8 . Open the PL/SQL editor for the Query menu item; one way to do this is to double-click the icon to the left of its node
in the Object Navigator.
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 9 of 47
9 . With your cursor in the PL/SQL editor, select Edit > Paste from the Forms Builder menu to paste in the trigger code
that you copied earlier.
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 10 of 47
10 . Because you cannot refer directly to form values in menu code, change :s_ord.customer_id to the following
indirect reference: NAME_IN('s_ord.customer_id')
Note: You could also change the references to the global variable to use the NAME_IN built-in; however, this is not
strictly necessary, because global variables are available directly throughout the application.
11 . Save and compile the menu by selecting the SUMMIT_MENU node or any of its subnodes in the Object Navigator,
and then clicking Save and then Compile Module.
12 . Select ORDERS in the Object Navigator and click Run Form to run the Orders form by itself .
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 11 of 47
13 . When the form appears in the browser, use the down arrow key a few times to scroll through the records. You can
see that orders from various customers are shown. Then select File > Query from the menu or click Query in the
menu toolbar.
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 12 of 47
15 . Now run the Customers form from Forms Builder and click Show Orders.
16 . The Orders form displays the orders for the selected customer.
Click Query, or select File > Query from the menu.
The same query is executed, showing orders only for the selected customer.
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 13 of 47
Back to Topic
Gets the ID of a menu item; the receiving variable must be declared as a menu
item type
GET_MENU_ITEM_PROPERTY Returns the current value of the given property for a specified menu item
SET_MENU_ITEM_PROPERTY Modifies the state of a menu item-specific characteristic
REPLACE_MENU
Replaces the current menu with a specific one, without making it active (use this
procedure to modify the display style and security)
Just as multiple form modules can be combined into a single application, so too can multiple menu modules be used as
needed. You can design an application so that several form modules share the same menu module, or have each form
in the application run its own menu. How menus are loaded in multiple-form applications depends on whether you are
using OPEN_FORM, NEW_FORM, or CALL_FORM.
In this tutorial section, you use menu built-ins to perform the following tasks:
Replace a menu
Change menu item properties
Replacing a Menu
There are two ways to replace a form's menu with another:
Use the REPLACE_MENU built-in procedure to dynamically replace the current form's menu with a different menu.
Note that if REPLACE_MENU is called from a menu item, code that follows the REPLACE_MENU call is not executed
because the context of that menu has been destroyed and replaced with the new menu.
Use the CALL_FORM built-in with the DO_REPLACE argument to replace the default menu of the called form with the
menu being used by the calling form. Note that if you use OPEN_FORM or NEW_FORM to call the second form, the
called form's menu is not replaced.
The Customers form uses a menu that is similar to the Forms default menu except that it has the Forms menu item
added, with a menu item that enables users to display the orders for a customer. Some users would prefer to have the
limited set of options that are defined in the Summit_menu menu, so you decide to provide a button that switches the
Customers form to that menu. Additionally, when the Orders form is called from the Customers form, you want its menu
to be the same as whatever is being used by the Customers form.
To perform this menu replacement for the Customers and Orders forms, perform the following steps:
1.
Add a button to the Control block of the Customers form, setting its properties as follows:
Property
Value
Name
MENU_BTN
Item Type
Push Button
Label
Summit Menu
Keyboard Navigable
No
Mouse Navigate
No
Canvas
CANVAS4
X Position
400
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
2.
Y Position
20
Width
75
Height
18
Page 14 of 47
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 15 of 47
ELSE
REPLACE_MENU ('customers');
SET_ITEM_PROPERTY('menu_btn',LABEL,'Summit Menu');
END IF;
3.
The When-Button-Pressed trigger for the Orders_Btn button currently uses the OPEN_FORM built-in to open the
Orders form. This enables both forms to be open at the same time time so that the user can navigate between them.
However, because you want the Orders form, when opened from Customers, to use whatever menu the Customers
form is using, you need to change the built-in to CALL_FORM with the DO_REPLACE argument.
Change the When-Button-Pressed trigger for the Orders_Btn button to use the following code:
:global.customer_id := :s_customer.id;
call_form('orders',NO_HIDE,NO_REPLACE);
4.
Run the Customers form to test it. When you click the Show Orders button, notice that the menu from the
Customers form is also used for the Orders form.
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 16 of 47
5.
Click Exit to return to the Customers form and then click Summit Menu. The menu for the Customers form changes,
and the button's label changes to "Default Menu".
6.
Now click Show Orders again. The Orders form inherits the Summit menu.
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 17 of 47
Back to Topic
Changing Menu Item Properties
The Summit_Menu menu contains a File_Menu.Query menu item that is specific to the Orders form. You do not want to
display this item when you are using this menu with the Customers form. Additionally, the Customers menu has a
submenu called Forms that should not be shown when the Orders form is using that menu.
To use menu built-ins to conditionally change the visibility of these menu items, perform the following steps:
1.
Modify the When-Button-Pressed trigger for the Control.Menu_Btn button in the Customers form by adding the
following line of code just before the ELSE statement:
SET_MENU_ITEM_PROPERTY('File_Menu.Query',DISPLAYED,PROPERTY_FALSE);
2.
Modify the When-Button-Pressed trigger for the Control.Orders_Btn button in the Customers form to contain the
following code:
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 18 of 47
DECLARE
s_menu MenuItem;
c_menuMenuItem;
BEGIN
c_menu := FIND_MENU_ITEM('Main_Menu.Forms');
-- If we're using the Customers menu, disable the Forms item
IFNOT ID_NULL(c_menu)THEN
SET_MENU_ITEM_PROPERTY(c_menu,DISPLAYED,PROPERTY_FALSE);
ELSE
-- If we're using the Summit menu, enable the Query item
s_menu:= FIND_MENU_ITEM('File_Menu.Query');
IFNOT ID_NULL(s_menu) THEN
SET_MENU_ITEM_PROPERTY(s_menu,DISPLAYED,PROPERTY_TRUE);
END IF;
ENDIF;
:GLOBAL.customer_id:= :s_customer.id;
CALL_FORM('orders',NO_HIDE,NO_REPLACE);
-- When returning from the Orders form
-- If we're using the Customers menu, enable the Forms item
IFNOT ID_NULL(c_menu)THEN
SET_MENU_ITEM_PROPERTY(c_menu,DISPLAYED,PROPERTY_TRUE);
ELSE
-- If we're using the Summit menu, disable the Query item
IFNOTID_NULL(s_menu) THEN
SET_MENU_ITEM_PROPERTY(s_menu,DISPLAYED,PROPERTY_FALSE);
END IF;
ENDIF;
END;
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
3.
Page 19 of 47
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 20 of 47
Exit the forms and close the browser window when you are finished testing.
Back to Topic
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 21 of 47
Duplicating code between menus and forms is inefficient and makes maintenance of forms and menus more difficult. In
this tutorial section, you define shared code by performing the following tasks:
Use a shared library
Create a user-defined trigger
Use the DO_KEY built-in
Using a Shared Library
A shared library is especially useful when code is to be shared among multiple modules. A single library can be
attached to multiple form and menu modules.
You have modified the button in the Customers form that calls the Orders form, but you have not modified the
Forms.Orders menu item, so it is not calling the Orders form in the same way. This is a common problem when you
simply copy code from a form trigger to a menu item; this duplication in code often results in inconsistencies. Placing
the code in a shared library, and then calling the code from both the menu and the button, solves this problem.
To define shared library code to call the Orders form from the Customers form, perform the following steps:
1.
Copy all of the code from the When-Button-Pressed trigger of the Orders_Btn button in the Customers form.
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
2.
Page 22 of 47
In the Object Navigator, select the PL/SQL Libraries node and click Create.
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 23 of 47
3.
Under the new library's node, select Program Units and click Create.
4.
5.
The PL/SQL editor opens. Select all except the first line of code, and then paste the code you copied earlier.
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
6.
Page 24 of 47
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
7.
Page 25 of 47
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 26 of 47
8.
In the Customers_Menu menu, select the Attached Libraries node and click Create.
9.
In the Attach Library dialog box, click Browse to navigate to the saved library and open it, then answer Yes to the
alert that asks if you want to remove the path.
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 27 of 47
10. Modify the code in the Forms_menu.Show_Orders menu item of the Customers_Menu menu to simply call the
SHOW_ORDERS procedure from the attached library:
show_orders;
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 28 of 47
12. In a similar fashion, attach the library to the Customers form, and then modify the When-Button-Pressed trigger of
the Control.Orders_btn button to call the SHOW_ORDERS procedure from the attached library.
13. Save and run the Customers form. Test that the Forms > Orders menu item and the Show Orders button function
identically. Exit the forms and close the browser when you are finished.
Note: If you are using Forms 11g and receive FRM-40735 or FRM-21011 and ORA-06508 errors when clicking the
button or selecting the menu item, you may need to apply Patch 10407723 to the Fusion Middleware 11g
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 29 of 47
ORACLE_HOME directory.
Back to Topic
Creating a User-Defined Trigger
Another option for sharing code is a user-defined trigger. This is ideal if the code is used by only one form, so it would
work for our example of calling the Orders form from the Customers form.
To revise this application to utilize a user-named trigger instead of the PL/SQL library, perform the following steps:
1.
Copy the code to call the Orders form from the Show_Orders procedure in the library.
2.
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 30 of 47
Hint: First create the trigger, and then rename it by clicking its name in the Object Navigator and typing over it.
3.
The PL/SQL editor opens; paste in the code that you copied from the library and replace the first line with the
following: DECLARE
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
4.
Page 31 of 47
Detach the attached library from both the Customers form and the Customers_Menu menu by selecting the nodes
in the Object Navigator and clicking Delete.
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
5.
Page 32 of 47
For both the When-Button-Pressed trigger of the Control.Show_Orders button of the Customers form, and for the
Forms_Menu.Show_Orders menu item of the Customers_Menu menu, set the code to:
EXECUTE_TRIGGER('Show_orders');
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
6.
Page 33 of 47
Save and compile the Customers_Menu menu, and then save and run the Customers form. The menu item and
the button should function identically.
Back to Topic
Using the DO_KEY Built-in
The DO_KEY built-in executes the key trigger that corresponds to the specified built-in subprogram. If no such key
trigger exists, then the specified subprogram executes. This behavior is analogous to pressing the corresponding
function key.
Using the DO_KEY built-in in combination with defining a key trigger ensures consistent behavior whether the user
presses a function key or executes the key functionality in some other way, such as by clicking a button. The DO_KEY
built-in can also be called from a menu item, providing another way to share code between a form and a menu.
The Orders form uses special code in a menu item and in the When-New-Form-Instance trigger to execute a restricted
query if the form is called by the Customers form. However, when a user executes a query by using a function key, the
code is not executed and an unrestricted query is always performed.
To ensure consistent behavior, perform the following steps:
1.
In PL/SQL Editor of the File_Menu.Query item of the Summit_Menu menu, select all the code and Cut it.
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
2.
Page 34 of 47
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 35 of 47
3.
In the Orders form, define a form-level Key-Exeqry trigger and paste into it the code that you previously cut from the
menu item.
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 36 of 47
Note: Because this code is part of the form, it does not need to use indirect references, even when it is called from a
menu. However, using indirect references is always a good idea because you would not need to change the code if
you move it to a menu or a PL/SQL library.
4.
Modify the form-level When-New-Form-Instance trigger of the Orders form; replace its code with the DO_KEY bultin:
DO_KEY('Execute_Query');
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
5.
Page 37 of 47
Back to Topic
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 38 of 47
Once the users and roles are defined, any developer can assign those roles to the menu module or menu items. This
controls who has access to any part of the menu application.
In this tutorial section, you perform the following tasks:
Define security roles
Assign access to menu items
Defining Security Roles
A role is a named set of privileges. You create roles once, and then assign them to users to provide:
Database-level access privileges, including table privileges (such as inserting data in tables)
System privileges (such as connecting to the database)
Application security (by limiting access to certain menu items)
You can think of a role as being a list of users that, because of their job responsibilities, have similar requirements for
access to information.
With respect to Forms menus, by using database roles you can grant access privileges to each menu item individually.
If access is granted only to some roles, only users belonging to those roles can access those items. Using this feature,
you can deliver the same application for different kinds of users.
To create the roles, perform the following steps:
1.
As the DBA, run the script to create the FRM50_ENABLED_ROLES view; this view of the enabled roles for a user is
necessary to implement menu security.
The DBA can create this view by running the script frmXXsec.sql, where XX is the Forms version number. For
10.1.2 and above the script name omits the version number, so it is frmsec.sql.
This script is located in a subdirectory of ORACLE_HOME. For example, for 11g this script is located in the following
directory: <ORACLE_HOME>\tools\dbtab\forms.
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 39 of 47
2.
As the DBA, grant the summit user access to the FRM50_ENABLED_ROLES view by running the frmXXgrt.sql
script.
3.
As the DBA, create two roles: TEST_CLERK and TEST_MGR, and grant the TEST_CLERK role to the SUMMIT user.
Execute the following statements:
create role test_clerk;
create role test_mgr;
grant test_clerk to summit;
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 40 of 47
Back to Topic
Assigning Menu Access
Your department is in charge of maintaining customer information. Clerks in your department should have access to
some parts of the application, but other parts should be available only to managers. Clerks have been assigned the
TEST_CLERK role, while manager have the TEST_MGR role.
To use menu security to restrict access to certain menu items, perform the following steps:
1.
In the Property Palette for the Customers_Menu menu, set Use Security to Yes, and then click More in the Module
Roles property to add the roles TEST_CLERK and TEST_MGR in the Menu Module Roles dialog box, typing over the
default CLERK and MANAGER roles that were previously defined.
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 41 of 47
2.
When you first implement security for a menu, none of the menu items has access granted to it. In other words, if you
were to run the Customers form at this point, you would get an error stating that there are no active items in the
application's root menu, and the form would appear without a menu.
When security is implemented, you must go to each menu item and specify which role or roles should have access to
it.
To test assigning access to menu items, give both roles access to the Exit menu item.
In Customers_Menu, open the Property Palette for the Action.Exit menu item and click More in the Item Roles
property. Then in the Menu Item Roles dialog box, Ctrl-click to select both roles that you have specified to use for
the menu and click OK.
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
3.
Page 42 of 47
The user must also have access to an item on the root, or main, menu of the application. In the same way as you did
in the previous step, grant access to both roles for the Main_Menu.Action submenu, which is the parent of the Exit
menu item.
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 43 of 47
4.
In a similar fashion, grant access to TEST_CLERK on the Action.Save menu item, and to TEST_MGR on the
Action.Print menu item.
When you change the Action.Save menu item, also change its Icon Filename property from rt_save to save.
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 44 of 47
5.
Save and compile the menu, and then run the Customers form. Because the SUMMIT user has been granted only
the TEST_CLERK role, you should see only the Action > Save and Action > Exit menu choices.
6.
The user has been promoted from clerk to manager. In the SQL*Plus window, grant the TEST_MGR role to the
SUMMIT user:
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 45 of 47
7.
Run the Customers form again. Both the Save and Print menu choices should now appear, because the SUMMIT
user has been granted both roles.
8.
In the SQL*Plus window, revoke the TEST_CLERK role from the SUMMIT user:
revoke test_clerk from summit;
9.
Run the Customers form again. The Print menu choice appears, but not the Save menu choice, because the
SUMMIT user now has only the TEST_MGR role.
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 46 of 47
Back to Topic
Summary
This tutorial showed you how to enhance Forms menus with code and use menu security.
In this tutorial, you should have learned how to:
Use PL/SQL in menu item code
Use menu built-ins to replace one menu with another and to set menu item properties
Share code between forms and menus by using a shared library, a user-defined trigger, and the DO_KEY built-in
Implement menu security to restrict access to menu items based on a user's assigned server roles
User Comments
Title:
Please log in or register first
Post anonymously
By submitting a comment, you confirm that you have read and agreed to the terms and conditions.
This feedback form is for tutorial corrections and suggestions. Because of the volume of suggestions, we cannot reply
to every comment. In particular:
If you have general questions about this Oracle software product, consult the OTN forums instead.
If you are encountering a software problem and need to request support or consulting, file a service request on My
Oracle Support.
If you want to order hardcopy documentation, go to the Oracle Store.
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012
Page 47 of 47
http://www.oracle.com/webfolder/technetwork/tutorials/obe/forms/11g/formsmenusmana... 14/06/2012