Oracle Fusion Middleware Tag Reference for Oracle ADF Faces
11g Release 2 (11.1.2.0.0)

E17491-02

<af:menuBar>

af:menuBar menuBar menu bar

UIComponent class: oracle.adf.view.rich.component.rich.RichMenuBar
Component type: oracle.adf.RichMenuBar

Unsupported agents: pda

A menuBar is a single row container designed to hold menus, commandMenuItems, goMenuItems, and groups of these same components. MenuBars are not rendered on printable pages.

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.

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.

Please also 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.

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.

Arrow Key Support

Arrow keys provide convenient keyboard focus movement between items in a menuBar and its child menus. Pressing left and right arrow keys cycles through the menuBar items. 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 close that menu and move focus to the previous or next menu item on the menBar. The exception to this is pressing the right arrow key while on a submenu item, which 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 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. This is not supported for 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

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:

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:

Screen Shot(s)


menuBar screenshot
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>
   

Events

Type Phases Description
org.apache.myfaces.trinidad.event.AttributeChangeEvent Invoke Application,
Apply Request Values
Event delivered to describe an attribute change. Attribute change events are not delivered for any programmatic change to a property. They are only delivered when a renderer changes a property without the application's specific request. An example of an attribute change event might include the width of a column that supported client-side resizing.

Supported Facets

Name Description
nodeStamp the component to use to stamp each element in the navigation. A CommandNavigationItem is expected. This facet is only needed when attaching the menuBar to a menu model.

Attributes

Name Type Supports EL? Description
attributeChangeListener javax.el.MethodExpression Only EL a method reference to an attribute change listener. Attribute change events are not delivered for any programmatic change to a property. They are only delivered when a renderer changes a property without the application's specific request. An example of an attribute change events might include the width of a column that supported client-side resizing.
binding oracle.adf.view.rich.component.rich.RichMenuBar Only EL an EL reference that will store the component instance on a bean. This can be used to give programmatic access to a component from a backing bean, or to move creation of the component to a backing bean.
clientComponent boolean Yes Default Value: false

whether a client-side component will be generated. A component may be generated whether or not this flag is set, but if client Javascript requires the component object, this must be set to true to guarantee the component's presence. Client component objects that are generated today by default may not be present in the future; setting this flag is the only way to guarantee a component's presence, and clients cannot rely on implicit behavior. However, there is a performance cost to setting this flag, so clients should avoid turning on client components unless absolutely necessary.
customizationId String Yes This attribute is deprecated. The 'id' attribute should be used when applying persistent customizations. This attribute will be removed in the next release.
disabled boolean Yes Default Value: false

whether the menu bar should be disabled. If a menuBar is disabled, child menus, commandMenuItems, and goMenuItems on the menuBar are disabled. Also in case the menuBar is attached to a menu model and the menuBar is disabled, the commandNavigationItems on the menuBar are disabled.
flex int Yes Default Value: 0

a non-negative integer that indicates the flexibility of this component in its containing toolbox. When in a toolbox, flex is used to determine how horizontal space is distributed among toolbox children in the same row. Components with larger flex values will be assigned more horizontal space than components with lower flex values. This is done using the ratio determined by the flex of each of the child components. The actual value is only relevant if there are other flexible components (components with flex values larger than zero) within the same container.
id String No the identifier for the component. The identifier must follow a subset of the syntax allowed in HTML:
  • Must not be a zero-length String.
  • First character must be an ASCII letter (A-Za-z) or an underscore ('_').
  • Subsequent characters must be an ASCII letter or digit (A-Za-z0-9), an underscore ('_'), or a dash ('-').
inlineStyle String Yes the CSS styles to use for this component. This is intended for basic style changes. The inlineStyle is a set of CSS styles that are applied to the root DOM element of the component. Be aware that because of browser CSS precedence rules, CSS rendered on a DOM element takes precedence over external stylesheets like the skin file. Therefore skins will not be able to override what you set on this attribute. If the inlineStyle's CSS properties do not affect the DOM element you want affected, then you will have to create a skin and use the skinning keys which are meant to target particular DOM elements, like ::label or ::icon-style.
partialTriggers String[] Yes the IDs of the components that should trigger a partial update. This component will listen on the trigger components. If one of the trigger components receives an event that will cause it to update in some way, this component will request to be updated too. Identifiers are relative to the source component (this component), and must account for NamingContainers. If your component is already inside of a naming container, you can use a single colon to start the search from the root of the page, or multiple colons to move up through the NamingContainers - "::" will pop out of the component's naming container (or itself if the component is a naming container) and begin the search from there, ":::" will pop out of two naming containers (including itself if the component is a naming container) and begin the search from there, etc.
rendered boolean Yes Default Value: true

whether the component is rendered. When set to false, no output will be delivered for this component (the component will not in any way be rendered, and cannot be made visible on the client). If you want to change a component's rendered attribute from false to true using PPR, set the partialTrigger attribute of its parent component so the parent refreshes and in turn will render this component.
shortDesc String Yes the short description of the component. This text is commonly used by user agents to display tooltip help text, in which case the behavior for the tooltip is controlled by the user agent, e.g. Firefox 2 truncates long tooltips. For form components, the shortDesc is displayed in a note window. For components that support the helpTopicId attribute it is recommended that helpTopicId is used as it is more flexible and is more accessibility-compliant.
stretchId String Yes the id of a child component that will be given all of the available space left in the menuBar if the contents of the menuBar do not use all of the space that the menuBar has available. 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'. This attribute is not applicable for menu model implementation of menuBar.
styleClass String Yes a CSS style class to use for this component. The style class can be defined in your jspx page or in a skinning CSS file, for example, or you can use one of our public style classes, like 'AFInstructionText'.
unsecure java.util.Set Yes A whitespace separated list of attributes whose values ordinarily can be set only on the server, but need to be settable on the client. Currently, this is supported only for the "disabled" attribute. Note that when you are able to set a property on the client, you will be allowed to by using the the .setProperty('attribute', newValue) method, but not the .setXXXAttribute(newValue) method. For example, if you have unsecure="disabled", then on the client you can use the method .setProperty('disabled', false), while the method .setDisabled(false) will not work and will provide a javascript error that setDisabled is not a function.
value Object Yes the hierarchy of navigation data - must be of type org.apache.myfaces.trinidad.model.MenuModel. This attribute is only needed when attaching the menuBar to a menu model.
var String No Name of the EL variable used to reference each element of this collection. Once this component has completed rendering, this variable is removed (or reverted back to its previous value). This attribute is only needed when attaching the menuBar to a menu model.
varStatus String No Name of the EL variable used to reference the varStatus information. Once this component has completed rendering, this variable is removed (or reverted back to its previous value). The VarStatus provides contextual information about the state of the component to EL expressions. For components that iterate, varStatus also provides loop counter information. Please see the this component's documentation for the specific properties on the varStatus. The common properties on varStatus include:
  • "model" - returns the CollectionModel for this component
  • "index" - returns the zero based row index
This attribute is only needed when attaching the menuBar to a menu model.
visible boolean Yes Default Value: true

the visibility of the component. If it is "false", the component will be hidden on the client. Unlike "rendered", this does not affect the lifecycle on the server - the component may have its bindings executed, etc. - and the visibility of the component can be toggled on and off on the client, or toggled with PPR. When "rendered" is false, the component will not in any way be rendered, and cannot be made visible on the client. In most cases, use the "rendered" property instead of the "visible" property.
Not supported on the following renderkits: org.apache.myfaces.trinidad.core