WSubMenu

WSubMenu is a component for adding a sub menu to a WMenu. The appearance and interaction model of a sub menu is determined by the WMenu's' MenuType property. WSubMenus may be nested inside other WSubMenus.

• Why use WSubMenu
  • When not to use
• Sample appearance
  • MenuType.BAR
  • MenuType.COLUMN
  • MenuType.FLYOUT
  • MenuType.TREE
• Accessibility
  • Label content
  • Access Keys
• Open sub-menus
• Selection Modes
• Content loading and performance
• Disabling
• Hiding
  • Hidden is not closed
• Adding non-text content to a WSubMenu opener
  • Adding an icon to a WSubMenu
  • Adding other content to the WSubMenu
• Responsive design
• Related components
• Further information

Why use WSubMenu

WSubMenu should be used to group a set of menu options which are adequately described by a single short descriptive label.

Some examples of appropriate use of WSubMenu include:

• as the only child of a WMenu of MenuType.FLYOUT to make a menu which occupies a single icon's worth of space;
• as every child of a WMenu of MenuType.BAR to make a menu bar as commonly found in desktop applications.

When not to use

It is recommended that WSubMenu ought not be nested and should not be nested more than one level (that it, a WSubMenu should not be added to a WSubMenu which is already the child of a WSubMenu - clear as mud).

For most web applications, and especially applications which are likely to be used on the Internet rather than on an intranet, that WSubMenu be avoided if possible and should never be nested in another WSubMenu.

Sample appearance

A sub menu for a WMenu of MenuType.BAR or MenuType.FLYOUT opens downwards if it is added directly to the WMenu or sideways (to the right unless it hits the right edge of the viewport) if it is added to another WSubMenu. A sub menu for a WMenu of MenuType.TREE opens downwards and the sub menu content is indented relative to the sub menu opening control. A sub menu for a WMenu of MenuType.COLUMN opens to the right of the previous WMenu or WSubMenu and is positioned relative to the opener button.

MenuType.BAR

MenuType.COLUMN

MenuType.FLYOUT

MenuType.TREE

Accessibility

WSubMenu may be accessed and opened from the keyboard. It implements the key navigation suggested by the WAI-ARIA authoring practices for a menu. The accessibility of a WSubMenu is dependent on the quality of its label content.

Label content

WSubMenu uses WDecoratedLabel as its labeling component and this is used to provide the content of the sub-menu opening control. This opening control is a button element and its labeling component must comply with:

• the content must include palpable content
• the content must include content which is available to assistive technologies, for example if the WSubMenu's WDecoratedLabel contains only an image then that image must have an appropriate 'alt' attribute which indicates the intent and purpose of the sub menu;
• the content must contain only phrasing content which precludes all WComponents which output non-phrasing content;
• the content may not contain any interactive content or labels.

It is strongly recommended that the content consist of plain text (with optional icon) or an icon if the WDecoratedLabel has as adequate toolTip.

Access Keys

A WSubMenu may be given an access key to provide rapid keyboard access. This will only be available is the WSubMenu is added directly to a WMenu. For WSubMenus which are inside another WSubMenu the WAI-ARIA recommendation for keyboard interaction for a menu which stipulates that pressing a letter key will focus the next visible node the label of which begins with the letter pressed.

Open sub-menus

A WSubMenu be open, with visible content, on page load if and only if the WMenu is of MenuType.TREE.

Selection Modes

The WMenuItems added to a WSubMenu may be selectable. See WMenu item selection for more details: the implementation is exactly the same.

Content loading and performance

A WSubMenu may load its content during initial render or as needed. For more information about Modes, performance implications, and determining the correct mode to specify see Ajax modes.

Disabling

A WSubMenu may be disabled on page load. When disabled the WSubMenu will not respond to user input or interaction. A WSubMenu will also be disabled if any ancestor WSubMenu or the WMenu is disabled. A disabled sub menu will not be able to be opened or closed, if it is open on page load it will remain open. Sub menus of a WMenu of MenuType BAR or FLYOUT are not able to be opened.

Hiding

A WSubMenu may be hidden on page load. When hidden the WSubMenu is not available to any compliant user agent. It is present in the source and is not obscured in any way. This property is determined by a WSubordinateControl. When a WSubMenu is hidden its labelling component and content are also hidden.

Hidden is not closed

When a WSubMenu is closed its content is 'hidden' but its label, which is used to toggle the open state, is available. When a WSubMenu is hidden both the label and content are hidden and the open state is irrelevant and not able to be toggled.

Adding non-text content to a WSubMenu opener

Adding an icon to a WSubMenu

WSubMenu contains a WDecoratedLabel and therefore a WImage may be added to any part of the WSubMenu opener.

To maximise the user's comfort in using a WSubMenu with an image the following are recommended:

• If the WMenu MenuType is BAR or FLYOUT:
  • If the WSubMenu is at the top level of the WMenu then either:
    • all WSubMenu openers and WMenuItems should consist of only an iconic WImage (or theme icon) which should be added to the WDecoratedLabel body segment; or
    • all WSubMenu openers and WMenuItems should consist of a text explanation which should be added to the WDecoratedLabel body segment and an optional iconic WImage (or theme icon) which should be added to the WDecoratedLabel head segment.
  • If the WSubMenu is inside another WSubMenu then all WSubMenu openers and WMenuItems should consist of a text explanation which should be added to the WDecoratedLabel body segment and an optional iconic WImage which should be added to the WDecoratedLabel head segment.
• If the WMenu type is TREE then all WSubMenu openers and WMenuItems should consist of a text explanation which should be added to the WDecoratedLabel body segment and an optional iconic WImage (or theme icon) which should be added to the WDecoratedLabel head segment. Note, however, it is not considered an error to add all iconic WImages to the WDecoratedLabel tail segment in a tree though this is unconventional.
• If the WMenu type is COLUMN then all WSubMenu openers and WMenuItems should consist of a text explanation which should be added to the WDecoratedLabel body segment and an optional iconic WImage (or theme icon) which should be added to the WDecoratedLabel head segment.

Adding other content to the WSubMenu

In general it is poor practice to add any content other than a single image and a single piece of text to a WSubMenu's WDecoratedLabel. In particular nothing should be added to the WDecoratedLabel tail component for any WSubMenu unless that WSubMenu is in a WMenu of type TREE. In all other cases the tail component may become reserved for displaying the sub-menu opener indicator.

Responsive design

The default WComponents theme has a set of simple responsive design styles which can be applied to WSubMenu (except when the ancestor WMenu is of MenuType.TREE). The in-built responsive design aspects of WSubMenu are:

• triggered at small screen width as commonly found on phone-like devices;
• all WSubMenus open full-screen with larger text items which are easier to hit;
• open WSubMenus show a close option which contains the text content of the WSubMenu opener.

See Responsive Design for more information about responsive design built in to WComponents.

Related components

• WMenu
• WMenuItem

Further information

• JavaDoc;
• WAI-ARIA authoring practices for a menu;
• Responsive design;
• List of WComponents.