Skip to content

WMenuItem

Jump to bottom
marksreeves edited this page Aug 30, 2016 · 15 revisions

WMenuItem is a component used to create functional items within a WMenu. The appearance and interaction model for a menu item is determined by the WMenu type property.

HTML output

WMenuItem will output a HTML button element if the submit property is set "true" or if the url property is set; otherwise a HTML div element.

When output as a HTML button Element WMenuItem outputs an interactive control 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 WMenuItem's WDecoratedLabel contains only an image then that image must have an appropriate alt attribute which indicates the intent and purpose of the menu item;
  • 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.

UI Properties

The following are the properties of WMenuItem which are available for manipulation within an application and which have a UI or interaction consequence.

The URL property

This is an optional property which will turn the WMenuItem into a link.

The targetWindow property

This property is only used if the URL property is set. If set the link will open in a new window or user agent tab (as determined by the user and/or user agent). The window will have an internal reference using the value of this property.

The submit property

If this Boolean property is true the menu item will cause a form submission. If the URL property is set this property is ignored.

The selectable property

This property has three states: true, false and not set. If true then the menu item will be able to be selected; if false the menu item will not be able to be selected; if not set the menu item will be able to be selected if the nearest ancestor WSubMenu or WMenu has a selectMode property set to allow selection.

If you have a WMenu or WSubMenu which supports selection of menu items then you must specify which (if any) WMenuItems in that sub-menu or menu are not selectable; otherwise all WMenuItems in that sub-menu or menu will be selectable.

Conversely, if you have a WSubMenu or WMenu which does not support selection you must specify explicitly any WMenuItem which is able to support being selected; otherwise no WMenuItems will be able to be selected.

The selected property

For the purposes of UI specification this Boolean property indicates whether a menu item is selected by default. This property is ignored if the menu item is deemed to not be selectable.

Allowing a WMenuItem to be selected allows menu driven states of an application to be made "sticky".

The disabled property

A WMenuItem may be disabled on page load. When disabled the WMenuItem will not respond to user input or interaction. A WMenuItem will also be disabled if any ancestor WSubMenu or the WMenu is disabled.

The hidden property

A WMenuItem may be hidden on page load. When hidden the WMenuItem 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.

The cancel property

This is a Boolean property. If set true then the WMenuItem will act as a cancel button and the user will receive an unsaved changes warning if:

  • the user has made changes in the current screen; or
  • the server has set an unsaved changes flag.

The msg property

This property is set to create a custom confirmation message for the WMenuItem. If set the user will have to confirm that they wish to undertake the action. If the cancel property is set true then this message will only appear if there are unsaved changes.

Access Keys

A WMenuItem may be given an access key to provide rapid keyboard access. This will only be available is the WMenuItem is added directly to a WMenu. keyboard access to other menu items is through the initial letter of the item's text label as per the WAI-ARIA authoring practices for a menu.

Adding an icon to a WMenuItem

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

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

  • If the WMenu Type is BAR or FLYOUT:
    • If the WMenuItem is at the top level of the WMenu then either:
      • all WMenuItems and WSubMenu openers should consist of only an iconic WImage which should be added to the WDecoratedLabel body segment; or
      • all WMenuItems and WSubMenu openers 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 WMenuItem is inside a WSubMenu then all WMenuItems and WSubMenu openers 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 WMenuItems and WSubMenu openers 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. 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 WMenuItems and WSubMenu openers 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.

Related Components

Further information

Some start pages

Clone this wiki locally