Skip to content

WMenuItem

Jump to bottom
Mark Reeves edited this page Jan 3, 2018 · 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 MenuType property.

Accessibility

WMenuItem uses WDecoratedLabel as its labeling component. 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.

If the WMenuItem has a URL and opens a new window or tab then the content should indicate to all users that invoking the button will open a new window/browser tab.

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.

Opening new windows

If a WMenuItem has a URL then this may be used to open the linked resource in a new tab or window using the targetwindow property. This may cause problems for some users and should be avoided where possible. In the case where this is unavoidable the WMenuItem's button will have the attribute aria-haspopup="true".

// with WMenuItem `linkItem`
linkItem.setTargetWindow("_blank");

Commands

A WMenuItem is most commonly associated with a command (such as "Save" or "Search". The Action takes place within the Java application, the WMenuItem serves merely to trigger the Action on the server application. When a WMenuItem has an Action it will submit the current view as a HTTP post unless the WMenuItem is also a trigger for a WAjaxControl.

// with WMenuItem item and Action action:
item.setAction(action);

// Obviously the Action _could_ be instantiated in place
item.setAction(new Action() {
  @Override
  public void execute(final ActionEvent event) {
    // do something
  }
});

// And WMenuItem may invoke a validating action.
// With a diagnostics component messages and a
// validation target target:
item.setAction(new ValidatingAction(messages.getValidationErrors(), target) {
	// only do something if the input is valid:
  @Override
  public void executeOnValid(final ActionEvent event) {
    // do something
  }
});

Confirmation of actions

There are two mechanisms which will result in a user being asked to confirm a button click. If the WMenuItem has its cancel property set true the user will be asked to confirm the cancel action if there are unsaved changes. If the menu item has its msg property set to a non-empty String the user will always be asked to confirm the action (unless the cancel property is also set in which case the action will only need to be confirmed if there are unsaved changes).

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.

See WButton cancel property for more information.

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.

See WButton msg property for more information.

URLs

A WMenuItem would usually be associated with a command (such as "Save" or "Search") but may be used to navigate to another URL. To do this the WMenuItem is not associated with an Action but has a URL attached. If a WMenuItem has a URL and an Action the Action will not be invoked: the URL will take precedence.

// given WMenuItem linkItem
// make the item navigate to a given URL
linkItem.setUrl("http://example.com");

To make the WMenuItem open a URL in a new browser tab or window (where supported) it may have a targetWindow set.

// given WMenuItem linkItem
// make the item navigate to a given URL
// in a new window
linkItem.setUrl("http://example.com");
linkItem.setTargetWindow("_blank");

Selectability

A WMenuItem may be selectable based on the SelectionMode of its ancestor WSubMenu or WMenu.

If an application has a WSubMenu (or WMenu) which supports selection of menu items then one must specify which (if any) WMenuItems in that WSubMenu (or WMenu) are not selectable; otherwise all WMenuItems in that WSubMenu (or WMenu) 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.

If a WMenuItem does not have an Action or a URL then it may still be selectable. The impact of this is entirely dependent on the application context. If a tree-like selection tool is required then WTree may be a more appropriate tool.

HTML output

WMenuItem will output a HTML button element if it has an Action or URL; otherwise a HTML div element.

Disabling

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.

Hiding

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.

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 MenuType 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 (or theme icon) 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 (or theme icon) 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 (or theme icon) which should be added to the WDecoratedLabel head segment.

  • If the WMenu MenuType 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 (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 MenuType 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 (or theme icon) which should be added to the WDecoratedLabel head segment.

Related Components

Further information

Some start pages

Clone this wiki locally