Skip to content

WButton

Jump to bottom
marksreeves edited this page Jul 4, 2016 · 36 revisions

WButton is a component for making buttons. Buttons are useful but must be accessible.

WButton interactions

A WButton will always POST the form without confirmation unless:

  1. it has its cancel property set in which case it will require confirmation if either
    1. the user has made changes; or
    2. there are unsaved changes on the server as flagged by the WApplication or WButton's unsavedChanges property; or
  2. it has a msg attribute set, in which case it will always require confirmation; or
  3. it is a child of a WDialog in which case it will launch the dialog but never POST the form; or
  4. it is an AJAX trigger, in which case it will fire the AJAX request.

Accessibility

WButton will be accessible if it is created with a reasonable labelling string - even if this string is not displayed on the final button.

WButton saveButton = new WButton("Save");

For detailed information and methods to ensure your WButtons are always accessible see WBUtton accessibility.

HTML output

WButton will output a HTML button element of type submit.

Screen shot of a typical use

Screen shot of a button element in Chrome 46 OS X

UI-related Properties

The following are the properties of WButton which are available for manipulation within an application and which have a UI consequence. The following descriptions are, therefore, mostly for the consumption of those who need to specify a UI design.

The Type property

This property is used to alter the appearance of the button. It is an optional property which, if not set, assumes type of BUTTON. Available values for this property are:

  • BUTTON: (the default) the button will take on the appearance of a button as determined by the user agent. This should be used for almost all cases. A typical button of this type may look like: Screen shot of an WButton of Type BUTTON in Firefox 47 OS X. Note, however, that ion order to present a more consistent appearance on OS X the wcomponents-default theme applies a set of CSS rules to buttons to make them inherit font metrics.
  • LINK: the button will look like a link but still act as a button. These buttons are still buttons and you may create a usability issue by implementing this type. A typical button of this type may look like: Screen shot of an WButton of Type LINK in Chrome 46 OS X.

To implement this property one would use the method setRenderAsLink(boolean isLink):

WButton linkLikeButton = new WButton("Link");
linkLikeButton.setRenderAsLink(true);

// to remove the LINK type:
linkLikeButton.setRenderAsLink(false); // duh!

The imageUrl property

This property is used to set an image as the content of the button. Any image may be used and it is output as a HTML image element. If this property is specified without an imagePosition property then the image will be the only content of the button. In this case the string value of the WButton is used as the 'alt' attribute of the image and must be specified. For details of how to create one of these see Accessible "image" buttons.

WButton imgButton = new WButton("Save");
imgButton.setImage("/path/to/save_icon.png");

The imagePosition property

This property allows the image to co-exist with text content. It has four available values:

  • NORTH - the image will appear centred above the button text;
  • EAST - the image will appear to the right of the button text;
  • SOUTH - the image will appear centred below the button text; and
  • WEST - the image will appear to the left of the button text.

Buttons with imageUrl and imagePosition

WButton imgButton = new WButton("Save");
imgButton.setImage("/path/to/save_icon.png");
// put the image to the WEST of the text.
imgButton.setImagePosition(ImagePosition.WEST);

Screen shot of WButtons with ImagePosition set

The validates property

This property is used to explicitly validate a sub-section of the application when a WButton is used to submit data to the server. The validates property holds a reference to a particular container within the page (such as a WPanel or WFieldLayout. If that container holds any form controls which are able to be sent to the server then client side validation rules will only apply to that container. If this property is not set or if the target container holds nothing which can be sent to the server then the entire WApplication form is subject to validation.

To reduce inconsistency and potential for error and to maximise accessibility one should always specify what part of a screen is subject to input validation. In many cases this will be the entire form.

NOTE This property directly conflicts with some interpretations of WCAG 2.0 and may be subject to change in future releases.

Setting the validates property

The validates property is not specified or set directly. It is inferred from the existence of a validating action on the server. If you have specified any WComponents with constraints (such as mandatory or a WTextField with a minLength property or a WNumberField then at least the container for those components must be validated before committing the data. It is common to set this validating action on the innermost container component which holds all of the WComponents which are subject to validation for any particular scenario.

The disabled property

A WButton may be disabled on page load. When disabled the WButton will not respond to user input or interaction.

This property may be used in conjunction with WSubordinateControl controls to enable or disable content without making another server call. In this case it is not necessary to explicitly set the disabled state as this will be managed by WSubordinateControl.

The hidden property

A WButton may be hidden on page load. When hidden the WButton is not available to any compliant user agent. It is present in the source and is not obscured in any way, nor is it disabled. This property is determined by a WSubordinateControl.

The toolTip property

See toolTip.

The popup property

This Boolean property will, if true, merely set a flag on the button to indicate that it will cause a pop up to open. This allows applications to open a WPopup on the next screen load without contravening WCAG 2.0 level A requirements. For details about the use of this property see WBUtton accessibility.

The cancel property

This is a Boolean property. If set true then the WButton 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.

This property may be used with the msg property to present customised warnings to users.

The msg property

This property is set to create a custom confirmation message for the WButton. 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 WButton may be given an access key to provide rapid keyboard access.

Related components

Further information

Some start pages

Clone this wiki locally