ICEfaces Menu Bar Component Tutorial

The menuBar component provides a robust menu system that supports:

Nested child menuItem and menuItemSeparator components.
Horizontal (default) and Vertical menu orientations. Defines whether the sub-menus of the top-level menu items appear beside or below the top-level menu items.
Definition of the hierarchy of menu items and their sub-menus in one of two ways:
1. By using a binding to a bean method that returns a (potentially) dynamic hierarchy of menu items.
2. By statically defining the hierarchy in the page.
The action attribute of the contained menuItem tags or instances can be defined to indicate a string or a backing bean method that can be used in application navigation.
The actionListener attribute of the contained menuItem tags or instances can be defined to indicate an actionListener that resides in a backing bean.
The rest of this tutorial will discuss the following topics:

How to Use the Menu Bar Component

The menuBar component is used as a robust menu system. Among its primary uses is navigation. The menuBar component can be situated horizontally or vertically. Its contents can be defined statically or dynamically in a backing bean. The following is a listing of the attributes that the menuBar component uses:

id: The component identifier for this component. This value must be unique within the closest parent component that is a naming container.
imageDir: Set directory for location of the tree images. Default directory is /xmlhttp/css/xp/css-images/ which is include in the icefaces.jar.
immediate: Flag indicating that this component's value must be converted and validated immediately (that is, during Apply Request Values phase), rather than waiting until Process Validations phase.
noIcons: If true, this component will not render icons and icon spacers in menuItems. The default is false. By default icons are rendered.
orientation: Defines whether the sub-menus of the top-level menu items appear beside or below the top-level menu items. Horizontal (default) and Vertical menu orientations.
rendered: Flag indicating whether or not this component should be rendered (during Render Response Phase), or processed on any subsequent form submit.
renderedOnUserRole: If user is in given role, this component will be rendered normally. If not, nothing is rendered and the body of this tag will be skipped.
style: CSS style(s) to be applied when this component is rendered.
styleClass: Space-separated list of CSS style class(es) to be applied when this element is rendered. This will be discusses in greater detail later in the tutorial.
value: The current value of this component.

There are three other components that can be used to define the content in the menuBar component. The menuItem component defines the menu items contained by a menuBar. The following is a listing of some of the main attributes used for the menuItem component:

action: MethodBinding representing the application action to invoke when this component is activated by the user. The expression must evaluate to either a String or a public method that takes no parameters, and returns a String (the logical outcome) which is passed to the NavigationHandler for this application.
actionListener: MethodBinding representing an action listener method that will be notified when this component is activated by the user. The expression must evaluate to a public method that takes an ActionEvent parameter, with a return type of void.
icon: Location of the icon image to be used by the menuItem.
id: The component identifier for this component. This value must be unique within the closest parent component that is a naming container.
link: For use in navigation, link to another page/site.
value: The current value of this component.

The menuItems component is similar to the menuItem component, the major difference being that menuItems is used if you want to supply a dynamic hierarchy for the menuBar. The following is a list of available attributes that can be used for this component:

action: MethodBinding representing the application action to invoke when this component is activated by the user. The expression must evaluate to either a String or a public method that takes no parameters, and returns a String (the logical outcome) which is passed to the NavigationHandler for this application.
actionListener: MethodBinding representing an action listener method that will be notified when this component is activated by the user. The expression must evaluate to a public method that takes an ActionEvent parameter, with a return type of void.
id: The component identifier for this component. This value must be unique within the closest parent component that is a naming container.
immediate: Flag indicating that this component's value must be converted and validated immediately (that is, during Apply Request Values phase), rather than waiting until Process Validations phase.
rendered: Flag indicating whether or not this component should be rendered (during Render Response Phase), or processed on any subsequent form submit.
value: The current value of this component.

The last component that can be used with the menuBar is the menuItemSeparator component. This component inserts a line similar to the <hr/> html tag. The screen shot below demonstrates how it is displayed:

Static Hierarchy Definition

For the example we have developed a basic menu bar with three top-level menu headers. The top-level menu headers consist of File, Edit, and View. The File sub-menu has the most detail, with icons defined for some headings. It also has another sub-menu defined in the Recent heading, that shows the ability of the component to have a sub-menu hierarchy defined. The following is the code for the basic menuBar component:

<ice:menuBar orientation="#{menuBar.orientation}">
    <ice:menuItem value="File" id="file">
        <ice:menuItem id="open" 
                      value="Open"
                      icon="images/open.gif"
                      actionListener="#{menuBar.listener}">
            <f:param name="myParam" value="Open"/>
        </ice:menuItem>
        <ice:menuItem id="close" 
                      value="Close"
                      actionListener="#{menuBar.listener}">
            <f:param name="myParam" value="Close"/>
        </ice:menuItem>
        <ice:menuItemSeparator/>
        <ice:menuItem id="recent" 
                      value="Recent"
                      icon="images/recent.gif"
                      actionListener="#{menuBar.listener}">
            <ice:menuItem id="photo1" 
                          value="Photo 1"
                          actionListener="#{menuBar.listener}">
                <f:param name="myParam" value="Photo 1"/>
            </ice:menuItem>
            <ice:menuItem id="file2" 
                          value="File 2"
                          actionListener="#{menuBar.listener}">
                <ice:menuItem id="para1" 
                              value="Para 1"
                              actionListener="#{menuBar.listener}">
                    <f:param name="myParam" value="Para 1"/>
                </ice:menuItem>
                <ice:menuItem id="para2" 
                              value="Para 2"
                              actionListener="#{menuBar.listener}">
                    <f:param name="myParam" value="Para 2"/>
                </ice:menuItem>
                <ice:menuItem id="para3" 
                              value="Para 3"
                              actionListener="#{menuBar.listener}">
                    <f:param name="myParam" value="Para 3"/>
                </ice:menuItem>
                <f:param name="myParam" value="File 2"/>
            </ice:menuItem>
            <ice:menuItem id="photo3" 
                          value="Photo 3"
                          actionListener="#{menuBar.listener}">
                <f:param name="myParam" value="Photo 3"/>
            </ice:menuItem>
            <ice:menuItem id="file4" 
                          value="File 4"
                          actionListener="#{menuBar.listener}">
                <f:param name="myParam" value="File 4"/>
            </ice:menuItem>
            <f:param name="myParam" value="Recent"/>
        </ice:menuItem>
        <ice:menuItem id="save" 
                      value="Save"
                      icon="images/save.gif"
                      actionListener="#{menuBar.listener}">
            <f:param name="myParam" value="Save"/>
        </ice:menuItem>
        <ice:menuItem id="print" 
                      value="Print"
                      icon="images/print.gif"
                      actionListener="#{menuBar.listener}">
            <f:param name="myParam" value="Print"/>
        </ice:menuItem>
    </ice:menuItem>
    <ice:menuItem id="edit" value="Edit">
        <ice:menuItem id="cut" 
                      value="Cut"
                      actionListener="#{menuBar.listener}">
            <f:param name="myParam" value="Cut"/>
        </ice:menuItem>
        <ice:menuItem id="copy" 
                      value="Copy"
                      actionListener="#{menuBar.listener}">
            <f:param name="myParam" value="Copy"/>
        </ice:menuItem>
        <ice:menuItem id="paste" 
                      value="Paste"
                      actionListener="#{menuBar.listener}">
            <f:param name="myParam" value="Paste"/>
        </ice:menuItem>
    </ice:menuItem>
    <ice:menuItem id="view" value="View">
        <ice:menuItem id="zoomin" 
                      value="Zoom In"
                      icon="images/zoomin.gif"
                      actionListener="#{menuBar.listener}">
            <f:param name="myParam" value="Zoom In"/>
        </ice:menuItem>
        <ice:menuItem id="zoomout" 
                      value="Zoom Out"
                      icon="images/zoomout.gif"
                      actionListener="#{menuBar.listener}">
            <f:param name="myParam" value="Zoom Out"/>
        </ice:menuItem>
        <ice:menuItem id="fitinwin" 
                      value="Fit In Window"
                      icon="images/fitinwindow.gif"
                      actionListener="#{menuBar.listener}">
            <f:param name="myParam" value="Fit In Window"/>
        </ice:menuItem>
        <ice:menuItem id="actualsize" 
                      value="Actual Size"
                      icon="images/actualsize.gif"
                      actionListener="#{menuBar.listener}">
            <f:param name="myParam" value="Actual Size"/>
        </ice:menuItem>
    </ice:menuItem>
</ice:menuBar>

Dynamic Hierarchy Definition

The menuBar component's menu items can also be defined dynamically through a backing bean. In the static definition we use the menuItem component, for the dynamic definition we will use the menuItems component. By dynamically defining the menu items it requires less code in the page, as shown below:

<ice:menuBar orientation="vertical">
    <ice:menuItems value="#{menuBean.menuModel}"/>
</ice:menuBar>

The backing bean provides (some variation of) the following infrastructure. Actions and ActionListeners are omitted for brevity:

bean


    private List menuModel;

    public List getMenuModel() {
        return menuModel;
    }
    
    public MenuBean() {

        menuModel = new ArrayList();

        MenuItem topLevel1 = new MenuItem();
        topLevel1.setIcon("xmlhttp/css/xp/css-images/menuitem.gif");
        topLevel1.setValue("topLevel1");

        MenuItem topLevel2 = new MenuItem();
        topLevel2.setIcon("xmlhttp/css/xp/css-images/menuitem.gif");
        topLevel2.setValue("topLevel2");

        MenuItem topLevel3 = new MenuItem();
        topLevel3.setIcon("xmlhttp/css/xp/css-images/menuitem.gif");
        topLevel3.setValue("topLevel3");

        menuModel.add(topLevel1);
        menuModel.add(topLevel2);
        menuModel.add(topLevel3);

        MenuItem sub1_1 = new MenuItem();
        sub1_1.setIcon("xmlhttp/css/xp/css-images/menuitem.gif");
        sub1_1.setValue("sub1_1");
        MenuItem sub1_2 = new MenuItem();
        sub1_2.setIcon("xmlhttp/css/xp/css-images/menuitem.gif");
        sub1_2.setValue("sub1_2");
        MenuItem sub1_3 = new MenuItem();
        sub1_3.setIcon("xmlhttp/css/xp/css-images/menuitem.gif");
        sub1_3.setValue("sub1_3");

        topLevel1.getChildren().add(sub1_1);
        topLevel1.getChildren().add(sub1_2);
        topLevel1.getChildren().add(sub1_3);

        MenuItem sub1_1_1 = new MenuItem();
        sub1_1_1.setIcon("xmlhttp/css/xp/css-images/menuitem.gif");
        sub1_1_1.setValue("sub1_1_1");
        MenuItem sub1_1_2 = new MenuItem();
        sub1_1_2.setIcon("xmlhttp/css/xp/css-images/menuitem.gif");
        sub1_1_2.setValue("sub1_1_2");
        MenuItem sub1_1_3 = new MenuItem();
        sub1_1_3.setIcon("xmlhttp/css/xp/css-images/menuitem.gif");
        sub1_1_3.setValue("sub1_1_3");

        sub1_1.getChildren().add(sub1_1_1);
        sub1_1.getChildren().add(sub1_1_2);
        sub1_1.getChildren().add(sub1_1_3);
    }

How to Style the Menu Bar Component

In the basic example we use the default xp style that is located in the icefaces.jar file. The following is a screen shot of the menuBar component with the default xp style:

The following is a screen shot of the menuBar component after the style class has been altered:

The styling of the component is done through a CSS file. The following is an example of the CSS code used:

style.css

.iceMnuBar { 
    padding: 0px;
    white-space: nowrap;
}

.iceMnuBarItem, .myHomeMenuItem { 
    float: left;
    padding: 0px;
    white-space: nowrap;
}

.iceMnuBarItem a, .myHomeMenuItem a {
    background:url("../images/blue004.jpg");
    height: auto;
    padding-left: 10px;
    padding-right: 10px;
    padding-top: 3px;
    padding-bottom: 3px;
    color: #FFF; 
    margin: 0px;
    width: 100px;
    float: left;
    display: block;
    text-decoration: none;
    font-weight:bold;
    white-space :normal ;
}

.myHomeMenuItem a {
    width: 40px;
}

.iceMnuBarItem a:hover, myHomeMenuItem a:hover{ 
    background: #006699;
    color: #FFFFFF;
}

.iceMnuBarItem hr {
    border: none 0;
    border-top: 1px solid #999999;
    width: 100%;
    height: 1px;
    margin-top: 3px;
    padding: 0px;
    text-align: left;
}

.iceMnuBarSubMenu { 
    position: absolute;
    background-color: #0099CC;
    width: 138px;
    border-top:1px solid #FFF;
    padding: 1px;
    height: auto;
    display: block;
}

.iceMnuItm { 
    padding: 0px;
    display: block;
    height: auto;
}

.iceMnuItm a { 
    color: #FFFFFF;
    display: block;
    text-decoration: none;
    padding-left: 3px;
    padding-right: 3px;
    padding-top: 3px;
    padding-bottom: 3px;
    font-weight : bold;
}

.iceMnuItm a:hover { 
    background-color:#0066CC;
}

.iceMnuItm a:hover .iceOutTxt{ 
    color: #FFFFFF;
}

.iceMnuItmLabel, .iceMnuBarItemLabel { 
    font-family: Arial, Helvetica, sans-serif;
    padding-top: 4px;
    font-size: 1.0em;
    display: inline;
}

.iceMnuBarItemImage {
    width:0px;
}

.iceMnuItmImage, .iceMnuBarItemImage {  
    display:inline;
    vertical-align: top;    
}

.iceMnuBarSubMenuInd { 
    display:inline;
    float:right;
    padding-top: 3px;
    padding-right: 1px;    
}

The default style class names are used except for the myHomeMenuItem class. This class is used to get the My Home heading text to wrap, due to its smaller size it needs a smaller width to get the desired text wrapping effect.

The following is a description of the default text style classes and which part of the menuBar component they represent:

iceMnuBar: The base name for the entire menuBar component.
iceMnuBarItem: Represents the top-level heading.
iceMnuBarItemLabel: Represents the text label in the heading.
iceMnuBarItemImage: Represents the image for the heading.
iceMnuBarSubMenu: Represents the sub-menu for the menuBar component.
iceMnuBarSubMenuInd: Represents the indicator for the sub-menu. Displays an arrow when the sub-menu is a header for another menu.

When the menu bar's orientation is set to vertical the style classes change a bit. The following is a list of style classes used when the menuBar components orientation is set to vertical:

iceMnuBarVrt
iceMnuBarVrtItem
iceMnuBarVrtItemLabel
iceMnuBarVrtItemImage
iceMnuBarVrtSubMenu
iceMnuBarVrtSubMenuInd

If the menuBar component is disabled and orientation is set to horizontal(default), the style classes are:

iceMnuBar-dis
iceMnuBarItem-dis
iceMnuBarItemLabel-dis
iceMnuBarItemImage-dis
iceMnuBarSubMenu-dis
iceMnuBarSubMenuInd-dis

If the menuBar component is disabled and the orientation is set to vertical, the style classes are:

iceMnuBarVrt-dis
iceMnuBarVrtItem-dis
iceMnuBarVrtItemLabel-dis
iceMnuBarVrtItemImage-dis
iceMnuBarVrtSubMenu-dis

iceMnuBarVrtSubMenuInd-dis

Tutorial Source Code Downloads

Example	Source	Notes
menuBar-basic	menuBar-basic source code	Basic example demonstrating how to use the menuBar component.
menuBar-styled	menuBar-styled source code	Basic example demonstrating how to style the menuBar component through CSS.

Menu Bar