Oracle Forms

Creating Oracle Forms Menus

Purpose

In this tutorial, you learn how to develop your own menu modules to replace the Forms default menu. You also learn how to enhance your applications by including menu toolbars and pop-up menus. Finally you learn how to modify the Forms default menu.

Time to Complete

Approximately 30 minutes.

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 improve the usability of Forms applications by adding custom menus.

Scenario

In this tutorial, you design a custom menu with very basic commands to use with an order entry application. You also provide a context-sensitive popup menu for a text item.

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

Before starting this tutorial, you should perform the following setup steps::

Download the file MenuOBE.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 Middleware Forms Services Deployment Guide

11g Release 1.
Open a command window and navigate to the directory where you unzipped the file.
Run SQL*Plus and log into your database as the SYSTEM user.
Run the script create_user.sql to create the summit user with the password oracle.
In SQL*Plus, connect to your database as the summit user.
Run the script create_schema.sql to create database objects for the user summit.
Log out of SQL*Plus and exit the command window.

Creating a Menu Module

A menu module is a hierarchically-structured object that provides a quick and easy method for operating your Forms application. Like the form module, the menu module is one of the main components of an application.

Each menu module is displayed as a pull-down menu that provides a set of options appearing horizontally under the application window title. Each option can represent a submenu or an action. Selecting a submenu displays a vertical list; selecting an action executes the action. An example of a menu for a running form looks like this:

The main menu appears horizontally in the menu bar above the form and below the window title. It contains options, typically individual menus, which are displayed vertically as shown.

Inidividual menus can contain submenus and/or menu items that appear to the right of the selected individual menu. Menu items are the options that perform programmed actions.

Menu modules can optionally display a toolbar in either a horizontal or vertical orientation. A menu toolbar is a set of iconified buttons that represent menu items.

To create a menu module, perform the following steps:

1 .	In the Object Navigator of Oracle Forms Builder, select the Menus node and click Create.:
2 .	The menu module is created as a separate module in Forms Builder. Select the newly-created menu module.
3 .	Click the menu module again so that the name is highlighted in blue. This enables you to easily change the name of the menu module.
4 .	Enter a new name for the module; for example, enter the name SUMMIT_MENU.
5 .	Click Save to save the menu module. Save it to the same directory where your forms are located (the one where you unzipped the setup files.) The menu is saved with a .mmb file extension.

Using the Menu Editor

The Menu Editor is a graphical design facility for laying out, modifying, and viewing menu modules and their objects. You can use the Menu Editor to carry out all of your menu design work.

As shown above, the Menu Editor provides the following tools:

Tool	Function
Display Menu	Determines the highest level menu that the Menu Editor displays. (Choose from all the menus in your menu module.)
Create Down	Creates a new menu item below the currently active one.
Create Right	Creates a new menu item to the right of the currently active one.
Switch Orientation	Changes display of the top-level menu vertically or horizontally

To use the Menu Editor to create a basic structure for your menu, perform the following steps:

1 .	With the SUMMIT_MENU module selected, perform one of the following actions to invoke the Menu Editor: Double-click the icon to the left of the module Right-click the module and select Menu Editor Select Tools > Menu Editor from the Forms Builder menu
2 .	When you invoke the Menu Editor, it automatically creates the main menu and one menu item. The main menu is the menu whose items, which can be menu items or submenus, show in the menu bar when you run a form. In the Object Navigator, change the name of the main menu to MAIN_MENU in the same way that you changed the name of the menu module.
3 .	In the Object Navigator, change the name of the menu item to File.
4 .	Note that the item's display label in the Menu Editor remains the same. The label is the text that is displayed for the menu item at run time. The label may differ from the name. You use the name programmatically, and it must follow PL/SQL naming conventions. Change the label of the menu item by double-clicking <New_Item> in the Menu Editor and typing the new label of File.
5 .	Create two menu items under File. In the Menu Editor, select File, then click Create Down twice.
6 .	In the Menu Editor, relabel the menu items to Save and Exit. Note that creating menu items under the File object creates a FILE_MENU object as a menu with two items under it. Also, when you relabel the items in the Menu Editor, the names of the items, as shown in the Object Navigator, also change.
7 .	Create another submenu of the main menu and label it Edit by performing the following steps: In the Menu Editor, select the File node. Click Create Right. Relabel the new menu Edit.
8 .	In a similar fashion to the way you created the File menu items, create two items for the Edit menu labeled Copyand Paste.
9 .	You can also use the Object Navigator to add a menu item. Under the Edit_Menu in the Object Navigator, select the Items node and click Create.
10 .	In the same way as you did with other items, relabel the new item in the Menu Editor with the label Cut, which also renames it in the Object Navigator.

Adding Functionality to Menu Items

So far you have created a basic structure and layout for the menu, but the menu items have no functionality. The kind of functionality a menu item has depends upon its type. In addition to the default plain menu items, Forms supports four types of special menu items. The menu types with their descriptions and functionality are as follows:

Menu Item Type	Description	Functionality
Plain	A standard text menu item ( the default menu item type that you have created so far)	Defined by PL/SQL
Check	A menu item that has two possible states.	Defined by PL/SQL
Radio	A set of mutually exclusive buttons, each representing a different action	Defined by PL/SQL
Magic	A menu item with predefined functionality	Usually predefined
Separator	A separating horizontal line for grouping menu items	None

The five menu item types appear at runtime as shown below

Magic items provide a way to quickly create menu items for standard functions available in most GUI applications.

Some magic items include default functionality. For example, the Cut item is automatically enabled or disabled depending on whether text or image elements have been selected. Invoking the Cut command deletes the selected element and places it on the clipboard. If you create a Cut magic item, Forms automatically provides an accelerator key and command statement for you.

The following table describes the magic menu item types with their valid command types and indicates whether the item provides default functionality, or whether you must define your own command:

Menu Item Type	Command Type	Default	Functionality
About, Undo	Any but Menu	No	You must assign a command to perform the desired function.
Clear, Cut. Copy, Paste	Null	Yes	These items perform the default operations indicated by their names.
Help	Menu	No	You must define the submenu to be called by the Help item, and you must assign commands to the items on that submenu.
Quit	Null	Yes	The Quit item prompts the end user to save changes (if any) and exits the form.
Window	Null or Menu	Yes	The Window item invokes a default submenu that lists all open windows. End users can activate a window by selecting it from the submenu. If you define your own submenu to be invoked by the Window item, Forms combines its items with the list of open windows and creates a single submenu. Item order on the combined submenu is undefined.

In this section, you modify the menu type of some of the menu items and define their functionality by performing the following steps:

1 .	The menu items in the File menu are Plain items, so you need to add PL/SQL code to define the functionality. To invoke the PL/SQL Editor, double-click the icon to the left of the Save node in the Object Navigator.
2 .	In the PL/SQL Editor, enter the following code and then click Compile PL/SQL code: DO_KEY('COMMIT_FORM'); If the PL/SQL code compiles correctly, the message in the lower left margin of the PL/SQL editor changes from Modified to Not Modified. If there is a compilation error, a message appears below the code entry window in the editor.
3 .	In a similar fashion, enter the following code for the Exit menu item: DO_KEY('EXIT_FORM');
4 .	The items for the Edit menu are Magic items, so you need to change these from the default of Plain. You do this by changing the properties of the menu item. Open the Property Palette for the Cut menu item by performing one of the following: Double-click the Cut item in the Menu Editor Right-click the Cut item in the Object Navigator and select Property Palette Select the Cut item in either the Object Navigator or the Menu Editor, then select Tools > Property Palette from the Forms menu
5 .	In the Property Palette, select Magic from the Menu Item Type drop-down list.
6 .	In the Property Palette, select Cut from the Magic Item drop-down list.
7 .	In the Property Palette, select Null from the Command Type drop-down list.
8 .	In a similar fashion, modify the properties of the Copy and Paste menu items, changing their Menu Item Type to Magic, their Command Type to Null,and their Magic Item to Copy and Paste respectively.

Implementing a Menu Toolbar

A menu toolbar is a set of iconic buttons that represent individual items from a menu. When you create a custom form menu, you can specify that some or all of its items appear on a menu toolbar. You need to provide icons to represent the associated buttons on the menu toolbar.

If you use the default form menu, Forms Builder attaches a default menu toolbar to your form automatically, as shown in the application pictured below.

Menu toolbars allow developers to easily provide toolbar shortcuts to menu commands without duplicating code or effort.

In this section, you add all of the menu items that you have created so far to a horizontal menu toolbar by performing the following steps:.

1 .

Open the Property Palette for the Cut menu item and set Visible in Horizontal Toolbar to Yes, Icon in Menu to Yes, and Icon Filename to cut.
Screenshot for Step

2 .

In a similar fashion, set the properties of the remaining menu items as follows:

Menu Item	Visible in Horizontal Menu	Icon in Menu	Icon Filename
Copy	Yes	Yes	copy
Paste	Yes	Yes	paste
Save	Yes	Yes	save
Exit	Yes	Yes	exit.

Note: The icon filenames point to standard icons that come with Forms. If you are using custom icons, those files would need to be deployed also.

Deploying and Testing the Menu

Before you can use your customized menu module, you must:

Create an executable version. The resulting file that you create has the .mmx extension. A menu module executable file is not portable between operating systems, so you first must deploy the .mmb to the platform where you intend to use the menu and then create the .mmx file there.
Attach the menu to a form module. When you attach a customized menu module to a form module, you are effectively replacing the Forms default menu with your own menu module.

To compile the menu into an executable file and attach it to a form for testing, perform the following steps:.

1 .	Compile the menu. To do this from within Forms Builder, select the SUMMIT_MENU node (or any of its subnodes) in the Object Navigator, and then perform one of the following actions: Select Program > Compile Module from the Forms Builder menu Click Compile Module Use the keyboard shortcut (Ctrl-T on Windows) This creates the .mmx file in the same directory where you have saved the .mmb file. Note: If you are prompted to log in, use the credentials of the summit user that you created in the setup section.
2 .	To attach the menu to a form, you must modify a property in the form. To do so, first load the form into Forms Builder. Click Open or select File > Open from the Forms menu. Open orders.fmb from the directory where you saved the setup files.
3 .	Double-click the form module node (ORDERS) to invoke its Property Palette, and change the form's Menu Module property from default&smartbar to summit_menu, then click Save to save the modified form. Note: As long as the .mmx file is in a directory specified by FORMS_PATH in your environment file, you do not need to specify the complete path to the menu.
4 .	Ensure that the application server is running. For example, if you are using Forms 11g, ensure that the WLS_FORMS managed server is started. In earlier Forms versions, ensure that you have started OC4J. After starting the application server, click Run Form.
5 .	The form runs with the menu that you defined. You can experiment with the menu's functionality as desired, then click Exit to exit the form.

Implementing a Pop-Up Menu

Pop-up menus are context-sensitive menus. You attach pop-up menus to an item or canvas and display them by right-clicking on that item or canvas. Pop-up menus enable end users to quickly access common functions and commands.

Pop-up menus are objects in the Object Navigator that belong to a form module (similar to alerts, blocks, canvases and so on), as opposed to form menus, which belong to a separate menu module.

Items on a pop-up menu should be contextual to the menu's associated objects. For example, you would not include text-editing items on the pop-up menu for a two-digit numeric text item. However, you might include such items on the pop-up menu for a multiline text item.

To implement and test a pop-up menu, perform the following steps:.

1 .	In the same way as you opened the Orders form, open customers.fmb, then select the Popup Menus node and click Create.
2 .	Rename the new pop-up menu EDIT_MENU.
3 .	Double-click the icon to the left of EDIT_MENU to invoke the menu editor, then click Create Down twice.
4 .	In the Menu Editor, relabel the items Cut, Copy, and Paste, which also renames them in the Object Navigator.
5 .	Set the menu item properties as you did for the magic items in the SUMMIT_MENU menu that you defined earlier.
6 .	In the Object Navigator expand the nodes Data Blocks, S_CUSTOMER, and Items, select the COMMENTS item, and in the Property Palette select EDIT_MENU from the Popup Menu drop-down list.
7 .	Save and run the Customers form. Click the Credit Rating tab and highlight some text in the Comments field. Right-click the text to invoke the pop-up menu that you have defined. When you have finished experimenting with the functionality of the pop-up menu, exit the form and close the browser window.

Modifying the Forms Default Menu

The Forms default menu is not a separate menu module, but is built into every form module. The default menu includes standard commands for editing, navigating, and database interaction, such as Action > Save.

When you build a form module, it automatically uses the default menu with a toolbar, as designated by the form's Menu Module property, DEFAULT&SMARTBAR. If you wanted the default menu without the toolbar, you could change this to simply DEFAULT.

The default menu is internal to Oracle Forms Developer. However you can replace the default menu with a custom menu as you did previously in this tutorial. A custom menu that replicates the Forms default menu is included with Forms Demos that you can download from Oracle Technology Network, such as the 11g Forms Demos. In this demo pack there are two menu files: menudef_10g.mmb that includes default menu commands, and menudefs_10g.mmb that includes the commands and a toolbar. These files are also included in the setup files for this tutorial. Note that these menus include some obsolete built-ins; you work around these in this section.

The Customers form uses the Forms default menu, but you want to add a menu item to that menu to open the Orders form. To make this modification to the default menu, perform the following steps:.

1 .	In Forms Builder, open menudefs_10g.fmb.
2 .	Rename the menu CUSTOMERS_MENU.
3 .	Select File > Save As and save the menu as customers.mmb.
4 .	Open the Menu Editor for the Customers_menu by double-clicking the icon to the left of the CUSTOMERS_MENUnode in the Object Navigator..
5 .	In the Menu Editor, select the Field submenu and click Create Right, then relabel the new submenu Forms.
6 .	In the Menu Editor, select the new Forms node and click Create Down, then relabel the new submenu Show Orders.
7 .	Double-click the Show Orders node in the Menu Editor to open its Property Palette, click More in the Menu Item Code value, and enter the following code in the PL/SQL editor: :global.customer_id := NAME_IN('s_customer.id'); OPEN_FORM('orders'); \|
8 .	To work around the fact that the provided menu file contains obsolete built-ins, add two menu procedures by selecting the Program Units node in the Object Navigator for the Customers_menu module and then clicking Create. Name the procedures DISABLE_ITEM and ENABLE_ITEM, with the following code: PROCEDURE disable_item (menu_name VARCHAR2, menu_item VARCHAR2) IS item_to_disable VARCHAR2(50) := menu_name \|\|'.'\|\| menu_item; BEGIN SET_MENU_ITEM_PROPERTY(item_to_disable,ENABLED,PROPERTY_FALSE); END; PROCEDURE enable_item (menu_name VARCHAR2, menu_item VARCHAR2) IS item_to_enable VARCHAR2(50) := menu_name \|\|'.'\|\| menu_item; BEGIN SET_MENU_ITEM_PROPERTY(item_to_enable,ENABLED,PROPERTY_TRUE); END;
9 .	Save and compile the Customers_menu menu and then attach the menu to the Customers form by opening its Property Palette and then setting its Menu Module property to customers. .
10 .	Run the Customers form to test the menu functionality. You should be able to open the orders for the customer by using the menu (Forms > Show Orders). Close the forms and the browser window when you are finished.