Tutorial 23: How to build a Menu Bar

This tutorial explains how to build and use menu bar in a Formspider application. A menu bar is the region in a Formspider mainframe or dialog where the drop down menus are displayed. For instance in Formspider, the menu bars are always displayed at the top of the container window.

In Formspider, the menu bar‘s purpose is to supply a common housing for application or dialog specific menus which provide access to various functions as closing applications, opening files, displaying help documentations..etc. Drop down menus contained by the menu bar can be activated with shortcut keys and can contain icons.

In this tutorial, you will build a menu bar which will be displayed in a mainframe. You will discover how to create drop down menus which will be displayed by your menu bar and how to display icons on them. Also, you will discover how to define drop down menu events for interacting with the users.

Open Formspider IDE and click “New Application” under the “File” menu. The “New Application” dialog will show up. Enter “menuBar” as the name of the application and “HR” as its Datasource Schema name.  If you are using Formspider Online, you do not need to enter database schema name since your account is already configured to use your online database. Leave other fields empty and click “OK”. This creates the “menuBar” application with a default mainframe (called “mainFrame”) and a default panel (called “mainPanel”).

As the first step, you will create your menu bar. To achieve this, expand the “Miscellaneous” accordion panel, expand the “Menus” root node, select the “Menu Bar” node and click the “+” button from the toolbar of the accordion panel. Alternatively, you may right click the “Menu Bar” node in the navigation tree and click the “New” menu item from the pop up menu that is displayed. The “New Menu Bar” dialog shows up.

Creating a new menu bar

Enter “mainframeMenuBar” as the “Name” and click “OK” to create your menu bar.

Creating “mainframeMenuBar”

Note that when “OK” button is clicked, your newly created “mainframeMenuBar” is automatically opened in the editor for further design.

A menu bar can contain three type of menu elements; menu, menu item and separator.

  • Menu is a container for other menu elements, it can include all type of menu elements and it has not any event.
  • Menu Item is the base menu element, it has  “MenuItemClick” and “KeyEvent” events and it cannot contain other menu elements.
  • Separator shows separate line between other menu items and menus, it has not any event.

Your menu bar will contain two main drop down menus entitled as “File” and “Help”. There will be another menu labeled “New” under “File” menu, displaying “Text Document”, “HTML Document” and “Presentation” options and a separator line between “HTML Document” and “Presentation” options. On the other hand, the “Help” menu will contain only one option labeled “About”.

According to the menu elements definition above, your menu bar XML will look like;

<menuBar>
  <menu label="File">
    <menu label="New">
      <menuItem label="Text Document"/>
      <menuItem label="HTML Document"/>
      <separator/>
      <menuItem label="Presentation"/>
    </menu>
  </menu>
  <menu label="Help">
    <menuItem label="About"/>
  </menu>
</menuBar>

Notice that you added a Formspider menu for each of the “File” and “Help” menu. Then, you have added another menu labeled “New” inside of the “File” menu. Later, for displaying “Text Document”, “HTML Document” and “Presentation” options under “New” menu, you have added three menu items under your “New” menu. For showing a separator line between “HTML Document” and “Presentation” options, you have used a separator. Finally, you have added a menu item labeled “About” under the “Help” menu for displaying “About” option under it.

After completing your menu bar design, you have to add it in your mainframe in order to display it at the top of mainframe window. To accomplish this, expand the “Containers” accordion panel, expand first “Windows” node and then “Mainframe” node from the navigation tree and double click the “mainFrame” to open it in the editor. Edit your “mainFrame” XML by adding the “menuBar” attribute, your XML should look like;

<mainframe title="menuBar" width="500" height="500" menuBar="mainframeMenuBar">
  <borderLayout>
    <cell docking="Center">
      <include panelName="mainPanel"/>
    </cell>
  </borderLayout>
</mainframe>

Run your application, you will see that your menu bar is displayed at the top of the mainframe window. When you expand the “File” menu, notice that “New” menu and Text Document”, “HTML Document” and “Presentation” menu items are displayed.

“mainframeMenuBar” displayed

As a further step you will display a file named help_icon.png as the icon of the “Help” menu. To achive this;

  • Navigate to /tomcat/webapps/[your_context_root]/apps folder existing in your middle tier installation and create a new folder with the name “menuBar” (using the same name with your application is recommended as a best practice, it’s not an obligation)
  • Under “/apps/menuBar” folder create a new folder named “icons”
  • Copy your “help_icon.png” icon into the “/apps/menuBar/icons” folder

In your menu bar xml you will reference this file by using “icon” attribute as below;

icon="/apps/menuBar/icons/help_icon.png"

Note that icon the path value “/apps/menuBar/icons/help_icon.png” is a relative path pointing icon’s address in your middle tier installation. Alternatively you can reference an icon directly through an URL, without creating any folder in your middle tier installation;

icon="http://theformspider.com/learningcenter/wp-content/uploads/2012/01/help_icon.png"

Your menu bar XML will look like;

<menuBar>
  <menu label="File" icon="">
    <menu label="New">
      <menuItem label="Text Document"/>
      <menuItem label="HTML Document"/>
      <separator/>
      <menuItem label="Presentation"/>
    </menu>
  </menu>
  <menu label="Help" icon="/apps/menuBar/icons/help_icon.png">
    <menuItem label="About"/>
  </menu>
</menuBar>

Run your application again, you will see that your icon is displayed next to the “Help” menu.

“Help” icon displayed

As the final step of this tutorial, you will show a popup message when “About” menu item is clicked. To achieve this, you have to create a Formspider action which will be fired when “About” menu item is clicked.

In your datasource schema, create a package called “menuBarTutorial_pkg” and open your newly created “menuBarTutorial_pkg” package in your favorite PL/SQL Editor. Add a procedure named “showAboutMessage” and ensure that the procedure is exposed in the package specification. This procedure uses api_application.showPopupMessage API to display a popup message.

procedure showAboutMessage is
begin
  api_application.showPopupMessage('"About" menu item clicked');
end;

In Formspider IDE expand the “Actions” accordion panel, select the “Actions” node, click the “+” button to create a new action. Alternatively you may right click the “Actions” node and select “New” from the pop-up menu. The “New Action” dialog will show up. Enter “showAboutMessage” as the action name and “menuBarTutorial_pkg.showAboutMessage” as the procedure. Click “OK” to save your action.

creating “showAboutMessage”

Add a menuItemClick event to the “About” menu item triggering the “showAboutMessage” action, the menu bar XML should look like;

<menuBar>
  <menu label="File">
    <menu label="New">
      <menuItem label="Text Document"/>
      <menuItem label="HTML Document"/>
      <separator/>
      <menuItem label="Presentation"/>
    </menu>
  </menu>
  <menu label="Help" icon="/icons/menubar/about.png">
    <menuItem label="About">
      <events>
        <menuItemClick action="showAboutMessage"/>
      </events>
    </menuItem>
  </menu>
</menuBar>

Run your application again, when you click “About” menu item you will see that the popup message appears as expected.

Message displayed when “showAboutMessage” menu item is clicked

  • Ramil

    Thank you, very much Yalim.

  • Ramil

    I want to create dynamic menu from database. How to create a “xmldom.domdocument” definition?

    • http://www.gerger.co Yalim K. Gerger

      Hi Ramil,

      You can use the menubar API documented at http://theformspider.com/API/api_menubar.html to create menus during runtime.

      To be able to create a menu, first you need to create the appropriate DOM document which is created using XML. You can find out about how to create an xmlDom.DomDocument from the Oracle documentation at: http://docs.oracle.com/cd/B19306_01/appdev.102/b14258/d_xmldom.htm or from many other available resources online.

      Kind Regards,
      Yalim

      • Fernando Teixeira

        Hi Yalim, I tried to do like you said above but it’s not working. I was able to detele the menuBar but not create a new one.The msg in the action (using the createmenubar API) is ‘Input XML is not well formed.’. The xmlDom returned from the database is bellow. Anything wrong?

        • Fernando Teixeira

          Forget about it Yalim, my bad. Now it’s working perfectly but using the “setmenubar” method. I’ll probably contact soon about purchasing one/two licenses. I started trying today and sounds to be the perfect solution for us.

          Best Regards from Brazil.

          • http://www.gerger.co Yalim K. Gerger

            Hi Fernando,

            That’s great. Happy to hear that you solved your issue. It would be great to have you as a customer.

            Kind Regards,