Skip to content

WButton

Jump to bottom
marksreeves edited this page Aug 25, 2016 · 36 revisions

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

WButton interactions

Under normal (and therefore default) conditions a WButton is used to invoke a form submission which will cause a complete HTTPS post to the server application. The following settings will (in order) change this default interaction.

  1. If the clientCommandOnly property is set true the WButton will never submit the form but may invoke an Ajax request if the WButton is a trigger for a WAjaxControl depending on how the client side command is written and all other interactions of the button are dependent on the commands supplied.
  2. If the WButton is a trigger for a WAjaxControl then the ajax request will be triggered and the button will not invoke a form submission.
  3. If the WButton is a child of a WDialog or is a WDialog trigger component it will launch the dialog but not POST the form.
  4. If it has its cancel property set it will require confirmation before posting the form if either:
    • the user has made changes; or
    • there are unsaved changes on the server as flagged by the WApplication or WButton's unsavedChanges property.
  5. If it has a msg property set it will require confirmation before submitting the form.

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 because an image is displayed as the only content of the button.

WButton saveButton = new WButton("Save");

At a bare minimum a WButton must have at least one of:

  • a displayed text label (preferred);
  • a toolTip which adequately describes the purpose of the button; or
  • setting the accessibleText property to a value which adequately describes the purpose of the button.

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 or (if the clientCommandOnly property is true) button.

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 renderAsLink property

This boolean property is used to indicate that the button should appear to be a link. This is somewhat problematic but is included to maintain compatibility with an obsolete design paradigm from a time when buttons were difficult to style and links were used to invoke commands. It is recommended that this property not be used.

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):

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

// to remove the LINK appearance:
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");

For most cases it is recommended that the inbuilt iconography (by default using Font Awesome) be used instead of static images. See HtmlClassProperties and HtmlIconUtil for more information.

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.
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:

WButton cancelButton = new WButton("Cancel");
cancelButton.setCancel(true);
cancelButton.setMessage(
  "Are you really, really sure you want to throw away all that effort?");

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.

WButton confirmDeleteButton = new WButton("Delete");
cancelButton.setMessage("Are you sure?");

The htmlClass property

This property allows one or more values to be added to the components button element. This can be used for fine-grain styling of specific components but should be used with care. For more information see WComponents HTML class property.

WButton imgButton = new WButton("Help");
// to set class attribute values on the HTML output
cbSelect.setHtmlClass("wc-icon-after fa-question-circle");

The clientCommandOnly property

New in 1.2.5 This boolean property is used to tell the client code that the button should not fire a form submit action when it is invoked. It does not create a client command: that has to be attached to the UI as custom JavaScript.

WButton clientOnlyButton = new WButton(labelText);
clientOnlyButton.setClientCommandOnly(true);
// Some more work may be needed to ensure the command is fired only by
// this button. One way to do this is to set a static id on the button.
clientOnlyButton.setIdName("clientcommandbutton");

If this property is set true then the WButton may still act as a trigger for a WAjaxControl but will not fire a server action. For more information see

WButton clientOnlyButton = new WButton(labelText);
clientOnlyButton.setClientCommandOnly(true);
clientOnlyButton.setAction(new Action() {
    @Override
    public void execute(final ActionEvent event) {
     // This action will never be invoked.
    }
  });

The unsavedChanges property

This boolean property is set to true if the UI is part of a multi-screen process and the final outcome of the process has not yet been committed. It is used to indicate that an unsaved changes warning should be provided to the user if a cancel button is invoked and the user has not yet made any data changes in the current view.

In legacy systems which rely on full HTTP posts it may be easier or more appropriate to flag a WApplication as having unsaved changes but using this flag on a WButton allows it to be set when the process involves AJAX updates.

Note that a user will receive an unsaved changes warning if a cancel button is invoked if they have changed the state of data input controls in the current view even if the unsavedChanges property is not set on any WButton or the WApplication; equally if any one WButton has this property set to true then the unsaved changes warning will be given on invocation of any cancel button.

Access Keys

A WButton may be given an access key to provide rapid keyboard access.

Invoking custom client commands

New in 1.2.5 A custom client-side command may be attached to a WButton using custom JavaScript. Such a command would commonly be attached as a click event handler on the document body element with a test for a particular button description using a static id or custom HTML class attribute value(s).

Adding such a command to a UI will allow any button matching the selector for the event handler to invoke the command. WButton, under normal circumstances, will cause a submit action when it is invoked. There are two ways to prevent this:

  • mark the button as invoking a client side command only by using the clientCommandOnly property; or
  • ensure the invoked action prevents propagation or the default action of a button.

Which is chosen depends on the language preferences of the developer: if one is more comfortable in Java then it is safe and easy to call setClientCommandOnly(true) on a button instance; if one is more comfortable in JavaScript one may prefer to call preventDefault() in one's event handler; or one could do both.

If the button is to run a client command and make an Ajax call then one should not prevent the default action in the JavaScript click handler as this will also prevent the Ajax call being made.

Attaching a client-only command

Commands run in the client (web browser) are written in JavaScript and may be attached in any one of several ways. The preferred method is to write a JavaScript file and attach it to the application using WApplication's addJsFile() methods. For more information see Adding custom JavaScript.

If a command is only required for a specific view it can be attached along with the command button. One might, for example, attach a JavaScript file to the UI when first preparing to paint a button instance:

WButton clientOnlyButton = new WButton(labelText) {
  @Override
  protected void preparePaintComponent(final Request request) {
    if (!isInitialised()) {
      // add a JavaScript resource to the WApplication ancestor
      WebUtilities.getAncestorOfClass(WApplication.class, this)
	    .addJsFile(SCRIPT_RESOURCE_PATH_AND_FILE);
      setInitialised(true);
    }
    super.preparePaintComponent(request);
  }
};
clientOnlyButton.setClientCommandOnly(true);

The script element could be added directly to the UI along with the button but this has a number of disadvantages so is not generally recommended.

One should note that whilst much of the discussion of client-only commands has assumed the button is clicked (or its equivalent to fire a click event) a command may be added to any event which is able to be fired on a button element so one could, for example, use a combination of touch, mouse and key events to provide rich, accessible interactions which are not built into a current WComponent. These actions may be attached to items which are not WButtons but only WButton requires the extra flag that it is not to submit the form when invoked.

Related components

Further information

Some start pages

Clone this wiki locally