Implicit form submission

Some WComponents produce HTML input elements which allow the encompassing form to be submitted by pressing the ENTER key (referred to as implicit submission). The default behaviour for this is for the form to be deemed to be submitted by the first submit button in the form (in tree order).

This default behaviour is not necessarily the desired or expected behaviour, therefore WComponents provides a mechanism to change this in-built behaviour of web browsers by specifying an explicit default button for some components.

• The default submit button
• Using a default submit button
  • Use with WPanel
  • Use with an input control
• Input components which support defaultSubmitButton
• Internet Explorer

The default submit button

If the desired default submit button is a WButton and is not the first enabled submit control in source order then this WButton can be marked as being the preferred default submit button.

TODO: Should this be extended to allow a WMenuItem to be a default button?

Using a default submit button

All modern browsers with keyboard input support some form of implicit form submission. It is also common for a complex application to have many submit controls and for the first in source order to not be the best default option. To overcome this an alternate default button may be set on WPanel and any of the input components outlined below.

When creating a UI specification the expected default submit button must be explicitly specified as it is impossible for WComponents to make a judgement on which WButton should be deemed to be the default button for any use-case.

It is strongly recommended that at a default button is set on each screen of an application at the very least on a high level WPanel.

TODO: Should we be able to set a default button on a WApplication? It seems to make sense.

Use with WPanel

When the default submit button is set on a WPanel it will apply to all affected form controls inside that WPanel except those which have their own setting for defaultSubmitButton. This is the most common use of defaultSubmitButton and is the one which is recommended.

It may be appropriate to set defaultSubmitButton on a high level container WPanel and allow the whole application to inherit it, for example for a global "save" button.

// assume access to a WButton:
WButton saveButton = new WButton("Save");
WPanel applicationContainerPanel = new WPanel();
applicationContainerPanel.setDefaultSubmitButton(saveButton);

// ...

// This WPanel _could_ hold all other WComponents in the WApplication
// with WApplication `app`
app.add(applicationContainerPanel);

Use with an input control

Whilst it is recommended that the default button be set on a WPanel the use of a default button on an individual component allows multiple different default buttons as the user progresses though a UI such as within a single WFieldLayout.

Each of the WComponents which extend AbstractInput (and are listed below) can have their own default submit button.

A simple use-case for this could be a "search" form segment consisting of a single WTextField and WButton. Even if the whole application has a default button the search field will need a different default. The code snippet below could create such a form segment with a WTextField which has a default button.

// The search field
WTextField searchField = new WTextField();
// If we do not want a visible label we must
// ensure the field is still accessible
searchField.setAccessibleText("Enter search query");
// placeholder is nice but not sufficient for accessibility
searchField.setPlaceholder("search");
// The button to invoke seach
WButton searchButton = new WButton();
searchField.setDefaultSubmitButton(searchButton);
// ...
// use a "search" icon rather than text on the button
searchButton.setHtmlClass(HtmlClassProperties.ICON_SEARCH);
// If we are not having any visible text in the button (only an icon)
// we need to make sure the button is accessible. Use toolTip rather
// than setAccessibleText as this will also give a visual indicator
// to mouse users.
searchButton.setToolTip("search");
// ...
// searchButton would need an Action
// ...

// Finally: add the mini-form to the UI.
// assume some form of container component `searchFormContainer`
searchFormContainer.add(searchField);
searchFormContainer.add(searchButton);

If the user pressed the ENTER key with the searchField WTextField focussed then the form would be submitted by the searchButton WButton.

Input components which support defaultSubmitButton

At the time of writing (WComponents 1.3.x) setDefaultSubmitButton is available on all WComponents which extend AbstractInput. Not all of these components can actually cause implicit submission as they do not output a HTML element which allows it. The following WComponents are those which allow implicit submission:

• WDateField;
• WEmailField;
• WMultiTextField;
• WNumberField;
• WPartialDateField;
• WPasswordField; and
• WPhoneNumberField.

In most common browsers checkboxes and radio-buttons also cause implicit submission which adds the following as supported components:

• WCheckBox;
• WCheckBoxSelect;
• WRadioButton; and
• WRadioButtonSelect.

Internet Explorer

Internet Explorer takes an interesting approach to implicit submission in that if any element has focus (or implicit focus) and is a descendant of a form element then implicit submission will occur if the user presses the ENTER key.

WComponents attempts to capture this and prevent implicit submission if the component which has focus (or implicit focus) is not one of those listed above. This is done for two reasons:

1. this brings the behaviour of IE into line with more commonly used browsers; and
2. this prevents unexpected implicit submission when no form component has explicit focus.

In this section "implicit focus" is a state in which a non-focusable element (such as a div which has does not have tabindex set to 0 or above) behaves as if it has focus. This can be achieved by clicking on a non-focusable element. It is a "feature" both amusing and annoying.