<af:menuBar>

Usage with a MenuModel

The MenuModel implementation is also supported, namely org.apache.myfaces.trinidad.model.XmlMenuModel. Notice that the MenuModel has no special knowledge of page navigation and places no requirements on the nodes that go into the tree. The nodes in the tree are stamped out using the 'nodeStamp' facet, which should contain a commandNavigationItem component. This allows the default actionListener mechanism to be used for page navigation.

Note: The attributes 'var', 'value' and 'varStatus' are applicable only when attaching the menuBar to a menu model. Please also note that within a single menuBar component there could be either a menu model attached or explicitly defined children (viz. menus, commandMenuItems, goMenuItems, and groups of these same components).

Allowed Children

A menuBar is designed to only hold menus, commandMenuItems, goMenuItems, and groups of these same components, as well as simple decorative (non focusable) components like image and spacer. A menuBar can also dynamically add children of these allowed types using a facetRef, iterator, or switcher. The support for commandNavigationItems as children is only provided when menu model is used.

Besides the components listed, other types of children are not allowed. This is because the menuBar provides special menu functionality, like open menu mode, menu type access key behavior, and arrow key support that will not function correctly if other components are included on the menuBar. If you would like to include a non-menu-type component next to a menuBar, you can do this instead by placing the item in an adjacent toolbar next to the menuBar in the same toolbox row group.

Please note that you should not nest toolbars, menuBars, or other container-type components inside a menuBar. This is incompatible with overflow and is not supported. If you would like to display multiple menuBars or toolbars in a single row, you should instead use a toolbox group.

Note: In the case of a menuBar attached to a menu model only commandNavigationItems can be contained inside the "nodeStamp" facet. This is due to the reason that almost every groupNode and itemNode attribute (of a menu model) corresponds to an equivalent attribute of the commandNavigationItem.

Special Menu Functionality

MenuBars provide special menu functionality, including open menu mode, menu type access key behavior, and arrow key support.

Open Menu Mode

When you open a menu from the menuBar using the mouse, the menuBar is then in open menu mode. If you then move the mouse over another menu on the menuBar, the old menu automatically closes and the newly highlighted menu opens.

Menu Type Access Key Behavior

With menu type access key behavior, once your keyboard focus is in a menuBar or menu, you can simply press the access key without modifiers to move the focus to the menu item in that menu or menubar with that access key.

Keyboard Access

MenuBars are a single tabstop, with arrow key support to move focus between menuBar items. Arrow keys provide convenient keyboard focus movement between items in a menuBar and its child menus. The left and right arrow keys access the items on the menuBar. Pressing the down arrow opens a menu and moves keyboard focus to the first item. You can then press the up and down arrow keys to cycle through the menu items. Pressing left or right arrow keys inside a menu normally closes that menu and returns focus to the menu item on the menBar. Pressing the right arrow key while on a submenu item will open that submenu instead and place focus on its first item.

Note: The above special functionality does not work for menuBar attached to a menu model. The menu model implementation has 'hover to open and click to navigate" behavior. On hovering over any nested itemNode the popup opens up and navigation happens on a click. If a nested item has keyboard focus, it just highlights. The popup opens only when down arrow(for top bar items) or right arrow(for inner menu items) is pressed and navigation happens on pressing enter key. The arrow key support is very much similar to what is mentioned above except that we have commandNavigationItems instead of menus and menuItems.

Grouping Items in a MenuBar

If you use an <af:group> to group items inside a menuBar, the menuBar will by default include separators around the group. You should also note that the group has an effect on certain items. For example, commandMenuItems with type of radio that are grouped together are automatically considered part of the same radio group.

By default visual group separators always appear. If you want a group but do not want the group separator to appear, you can set the group's startBoundary or endBoundary attributes to 'hide' to request that the corresponding boundary be hidden. Note that when a first group's endBoundary and a second group's startBoundary are both set, the separator will only be hidden if both values are set to 'hide' or one value is 'hide' while the other value is 'dontCare'.

Grouping items is not supported for a menuBar attached to a menu model.

MenuBar Layout

MenuBars were designed to be used inside an <af:toolbox>. A toolbox allows highly customizable display of menuBars, by utilizing their flex values and allowing multiple menuBars and toolbars per row.

You may use a menuBar outside of a toolbox, though doing so will cause the menuBar to lose the geometry management functionality that the toolbox provides. Without a toolbox, you cannot have multiple menuBars per row or benefit from flex values.

Because menuBars and toolboxes are overflow components, they do not have a set width size. A menuBar or toolbox should be placed in a section of the page where it can horizontally stretch to the available size for proper rendering. Putting a menuBar or toolbox inside a section of the page where it is horizontally constrained to a minimum size (like a panelStretchLayout end facet) will be error-prone, due to the fact that the width of the menuBar varies with its current overflow state.

Right Justifying Menubar Items

By default menuBars are left (start side) justified. In order to make some or all of the menuBar items right (end side) justified, you can use the stretchId attibute. StretchId is usually set to the id of an af:spacer on the menuBar that you want to stretch to take up any available extra horizontal space. The component that you specify must be present on the client. Therefore, if using a component that may not be present on the client (like af:spacer), you should set the child component's clientComponent attribute to 'true'.

Note that stretchId is not applicable for menu model implementations of menuBar.

Assigning Percent Width to a MenuBar in a Row

Example of right-aligning menuBar children:

            <af:toolbox>
              <af:menuBar flex="1" stretchid="stretch1">
                <af:menu text="Edit">
                  <af:commandMenuItem text="menu item"/>
                </af:menu>
                
                <af:spacer id="stretch1" clientComponent="true"/>
                <af:menu text="Help">
                  <af:commandMenuItem text="menu item"/>
                </af:menu>
              </af:menuBar>
            </af:toolbox>
          

Assigning Percent Values to Items in a Row

When used inside a toolbox row, you can use a flex value on a menuBar to control what percentage of the available horizontal space that menuBar should receive. For example, if your toolbox row has 1 menuBar and 2 toolbars, each with a flex value of "1", then they receive their flex value (1) of the total space available (3). This means that the menuBar (and each toolbar) would be given one third of the available horizontal space.

Updating through PartialTriggers

Note that if a menuBar child component is going to be updated through partial page rendering, you need to update the menuBar as well. You do this by adding the child components id to the menuBar's partialTriggers attribute. This way the menuBar can appropriately manage its children in respect to sizing and placement in overflow.

Geometry Management

• This component can be stretched by a parent layout component that stretches its children, e.g. panelStretchLayout, panelSplitter.
• This component most commonly accepts menus, commandMenuItems, and goMenuItems as children. Other visual children include spacers and images. Children are not by default stretched. This component also has a stretchId attribute. When this attribute is set to the id of one of its children, that child is stretched.

Overflow

MenuBar is an overflow component. When a menuBar does not have enough space to display all items, the children are put into overflow and an overflow button is displayed. When a menuBar in a toolbox row has a flex value, the flex value is strictly followed, even in regards to overflow. When menuBars (or toolbars) in a toolbox row do not have flex values, then the right most (end side) menuBar would be forced into overflow before left side menuBars. Spacer and image children on menuBars are not put into overflow.

Overflow components must be part of a supported layout in order to work properly on the page.

An overflow component requires that it is either:

• in a container that stretches its children, or
• in a container that has a set width.

Under these circumstances, when the overflow component is larger than the parent container, the overflow component will display an overflow button. Selecting the overflow button will show a popup containing the items that didn't fit on the page.

Setting up an overflow component with the following layouts is not supported. If you use one of these layouts, you may have unexpected and inconsistent results:

• in a container that does not stretch its children.
• in a container that displays multiple children horizontally without explicit sizes for each child. For example, a panelGroupLayout with layout='horizontal' would be invalid, but panelSplitter is OK because it has an explicitly set splitter position.
• setting the overflow component with a styleClass or inlineStyle that assigns a percentage width value. Note that this includes assigning styleClass='AFStretchWidth' on an overflow component.

Screen Shot(s)

menuBar component

Code Example(s)

<af:menuBar>
  <af:menu>
    <af:commandMenuItem text="Item1"/>
    <af:commandMenuItem text="Item2"/>
    <af:commandMenuItem text="Item3"/>
  </af:menu>
</af:menuBar>

<af:menuBar var="item" value="#{xmlMenuModel}" id="mb1">
  <f:facet name="nodeStamp">
    <af:commandNavigationItem text="#{item.label}"
                              action="#{item.doAction}"
                              id="cni1"/>
  </f:facet>
</af:menuBar>