Declaratively configured menu and toolbar

The example application contains a dropdown menu and a toolbar, from both of which the user can trigger some action. In most cases, the functionality of the buttons and menu items is identical: e.g. the button for 'Save' does exactly the same as the equally named menu item in the 'File' menu. To avoid code redundancy (which bloats the application and makes it less maintainable and more error-prone), such functionality is implemented in so-called Command objects, which contain code that can be executed then from both a menu item and a toolbar button.

In this section, we shall see:


Enter the CMenu and CToolBar custom components

For the menu bar, we use a convenience component named CMenu (the 'C' stands for 'Custom' here, which is a convention also used in the SWT libraries). The CMenu reads all information it needs from an XML configuration file.

In that configuration file, every menu item to be added to the menu bar has an entry. Typically, you will want to configure the labels of the items, the dropdown menu to which they are attached, and a command that implements what happens when the item is selected by the user. To add a CMenu component, you need nothing more to do than select it from the widget selector, position it to the WebForm, and specify a configuration file (that is, edit the configFile property). The rest is done declaratively in the config file.

Similarly, the toolbar beneath the menu is configured by an XML file. The component which does the trick is named CToolBar, and it works exactly the same way as CMenu.


Declare yout items

Now, let's have a look at the configuration files CMenu.xml and CToolBar.xml, both in the WEB-INF/conf/ directory of the example application.

To add a new menu item, you would put a snippet like this to the CMenu.xml:


    <menuEntry>
      <!-- entry for a menu item in Menu 'File' -->
      <menu>File</menu>
      <!-- the item will be labelled 'Info' -->
      <label>Info</label>
      <!-- a command named 'CMD_INFO' will be executed when the
           user selects the item -->
      <id>INFO</id>
      <!-- the command class, specify this only if you want the
           CMenu to instantiate the command (see below) -->
      <command>com.to.know.InfoCommand</command>
    </menuEntry>
  

In case you want your item to appear in a new menu on the menu bar (let's say, a menu named 'Options'), you simply specify the name you want as the menu attribute. If the CMenu finds no menu of that name, it will create one.

The toolbar configuration is even simpler: just specify image names and tooltip texts (optional - leave the entry empty if you want no tooltips).


Command use and re-use

(For the following, you should have understood the use of commands as described in the previous section.)

Commands are declared in the CMenus and CToolBars configuration files by specifying their command name. In the application, a command with that name (prefixed by "CMD_" must exist in the command repository. (That is, it must have been added via W4TContext.addCommmand() somewhere in the initialization code of the application; but see below for an exception.)

This means, if you have created a command named CMD_LOGIN in your application, you can now reference this command by entering "LOGIN" into the id attribute of a menu entry. Enter the same into the id attribute of the CToolBar, and the toolbar will re-use the same command object.

What's more: if you also specify the commands fully qualified classname in one of the configuration files (in the command attribute), the menu or toolbar will then even take the job of instantiating the command object from you. (But the command must have a parameterless constructor in this case, of course.)

Note one thing, however: a CMenu or CToolBar will always call the parameterized process() method of a command, and it will pass an array as parameter that contains exactly one element: the menu item (of type com.w4t.dhtml.MenuItem) resp. the toolbar button (com.w4t.WebButton) that has caused the event.

More information about how the CMenu and CToolBar components handle commands can be found in the respective API docs .


Copyright (c) 2003 by Innoopract Informationssysteme GmbH. All rights reserved.