WNumberField

WNumberField is a component for creating a number input field. When accessed from a user agent and platform which supports alternate soft keyboards (such as modern tablets and smart phones) the user will be presented with a keyboard optimized for numeric input. WNumberField also provides keyboard drivability in line with modern HTML5 implementations of number fields.

• Why use WNumberField
  • When not to use
  • These are not numbers!
• Creating a WNumberField
  • Setting value
    • Set number value
    • Set data value
  • Input constraints
    • Mandatory
    • Minimum value
    • Maximum value
    • Step
• Accessibility
  • Keyboard operation
  • Labelling a WNumberField
    • Exposing constraints
  • Setting a toolTip
  • Additional labelling text
  • Access Keys
  • Default focus
• Read only
• Appearance
  • Setting input size
  • Customising based on HTML class
• HTML output
• Change action
• Disabling
• Hiding
• Default submit button
• Non-numeric input
• Related components
• Further information

Why use WNumberField

WNumberField should be used when the input is a number and when it makes some sense to use a spinbox to change the value of the number. For example, if one wanted to obtain a year based on the current year and within a small finite range (for example the year of expiry for a credit card), then a WNumberField would be appropriate. In the case of credit card expiry one could set the initial value and min to the current year and max to current year + 10.

When not to use

WNumberField is to be used for input which represent numbers, but not for inputs which represent number-like values which are not strict numbers. It would not be appropriate, for example, to use a WNumberField for an Australian ABN or Postcode. For more clarification see the note on the specification:

The type=number state is not appropriate for input that happens to only consist of numbers but isn't strictly speaking a number. For example, it would be inappropriate for credit card numbers or US postal codes. A simple way of determining whether to use type=number is to consider whether it would make sense for the input control to have a spinbox interface (e.g. with "up" and "down" arrows). Getting a credit card number wrong by 1 in the last digit isn't a minor mistake, it's as wrong as getting every digit incorrect. So it would not make sense for the user to select a credit card number using "up" and "down" buttons. When a spinbox interface is not appropriate, type=text is probably the right choice (possibly with a pattern attribute).

These are not numbers!

• Australian postcode (for numeric characters) is not a number;
• an ABN is not a number;
• a credit card number (or segment thereof) is not a number.

Don't believe me? See the note on the specification

Creating a WNumberField

WNumberField has a single constructor. No default value can be set at this time.

WNumberField field = new WNumberField();

Setting value

The value of a WNumberField is retained from user input during a session. A default or initial value may be set from a data source or manually.

Set number value

The number value of a WNumberField may be set using a BigDecimal, long or double.

// with WNumberField `field`
// set to long max value:
field.setNumber(Long.MAX_VALUE);
// set to 0 using BigDecimal:
field.setNumber(BigDecimal.ZERO);
// set to a float
field.setNumber(0.25);

Set data value

// with WNumberField `field` and a data object `obj`
field.setData(obj);

Input constraints

The input allowed in WNumberField may be constrained in several ways.

Mandatory

A WNumberField may be marked as being a mandatory field in the UI. Its accessors are setMandatory(boolean) and getMandatory(). The input component of the WNumberField has the required attribute set and any WLabel for the component is decorated with a visual indicator that the component is mandatory.

• a mandatory WTextField with no content

  

// given WTextField `field`
// make the field mandatory
field.setMandatory(true);

It should be noted that if the WNumberField is made mandatory and the value 0 (numeric zero) lies within the bounds of any implemented min and max constraints then 0 is considered to be valid input and the constraint of the mandatory field will be met. A WNumberField will only fail mandatory field validation if it does not have any numeric input.

Minimum value

WNumberField may be constrained to accept a minimum value if any input is entered at all. If not specified the default is determined by the user agent and differs greatly in all user agents currently implementing this input type. Note that some browsers which support the number state do not correctly enforce a min of 0.

The minimum value constraint may be set as a long, float or BigDecimal.

// with WNumberField `field`
// set minimum acceptable value to 5:
field.setMinValue(5);

Maximum value

WNumberField may be constrained to accept a maximum value if any input is entered at all. If not specified the default is determined by the user agent and differs greatly in all user agents currently implementing this input type.

The maximum value constraint may be set as a long, float or BigDecimal.

// with WNumberField `field`
// set maximum acceptable value to 2020:
field.setMaxValue(2020);

Step

A WNumberField provides for allowed increments of acceptable values between min and max and the increment through which entries will step when using the input's controls. This is supported on the client in HTML5 capable user agents. If this property is not specified the default is 1.

The step may be set as a long, float or BigDecimal.

// with WNumberField `field`
// set step to 2:
field.setStep(2);

Maintaining step and min specification compliance

The step property can be a float (for example 0.1) but only if min is implemented and is also a float.

If min is not specified, or if min is an integer, then step must be an integer. To work with this WComponents will attempt to set min and step to support both as float if either is defined as a float such that:

• if step is not defined do nothing;
• if step is 0 or 1 then do not add a step attribute to the output and let min be min;
• if min is a float and step is a float do nothing;
• if min is an integer (N) and step is a float then set min to float value N.0;
• if min is a float then let step be as defined;
• if min is not defined and step is a float then set step to the nearest integer value to step;
• if min is not defined and step is defined but not a float then let step be step;

Step mismatch

A WNumberField can have its value set to any number by the user. If this number is not a valid step increment above the min value then the field is suffering from a step mismatch. In this case the user agent may (note: not must) round the number to the nearest value not suffering from a step mismatch. If there are two such values then choosing the one closest to positive infinity.

This means that the user agent may choose to change the value entered by the user. This is analogous to a text input amending user input when it reaches its maxlength.

Accessibility

Keyboard operation

When a WNumberField is active the following keystrokes will change the current value:

• ARROW UP will increase the value by one step unless that step would cause the value to be greater than the max value; and
• ARROW DOWN will decrease the value by one step unless that step would cause the value to be less than the min value.

Remember: if step is not specified it is deemed to be 1 (integer one) as per the HTML 5 specification.

The following value changes may occur when the ARROW UP or ARROW DOWN key is pressed:

• if the value of the field is below min then the value will be set to min;
• if the value of the field is above max then the value will be set to max;

The following value changes may occur when the ARROW UP key is pressed:

• if the field is empty or it has non-numeric content then the value will be set to:
  • the value of the min attribute if it is set to a value greater than or equal to zero; or
  • one step above zero if step is specified; or
  • the value 1 if it is not above the value specified by max; otherwise
  • the value of max.
• if the field is suffering from a step mismatch the value will be increased to remove the step mismatch unless the subsequent value will be above max in which case the value will be set to max.

The following value changes may occur when the ARROW DOWN key is pressed:

• if the field is empty or non-numeric then the value will be set to:
  • the value of the min attribute if it is set to a value greater than or equal to zero; or
  • one step below zero if step is specified; or
  • the value -1 if it is not above the value specified by max; otherwise
  • the value of max.
• if the field is suffering from a step mismatch the value will be decreased to remove the step mismatch unless the subsequent value will be below min in which case the value will be set to min.

Labelling a WNumberField

All WNumberField in a UI must be associated with a label. This may be done using:

• WLabel (preferred) this is required if the label must be visible in the UI; or
• using the toolTip property if the label does not have to be visible in the UI; or
• using the accessibleText property of WNumberField.

The WLabel should be added to the UI before the WNumberField. The best way to add a WNumberField and its WLabel to a UI is to add it to a WFieldLayout.

A WNumberField which is not appropriately labelled may display an unlabelled control warning.

Exposing constraints

If the WNumberField has input constraints then there must be an indication of these constraints somewhere in the UI and available to all users. The appropriate place for this information is in the WLabel hint.

If the control is mandatory this indication is automatically generated within the legend element and the legend (if visible) and pseudo-label (if present) are both decorated accordingly.

Setting a toolTip

See toolTip. A WNumberField may use the toolTip property if it is not possible to include a label in the UI. This should be a last resort.

// given WNumberField `field`
// to set the toolTip
field.setToolTip("context for this field");

Additional labelling text

WNumberField may have accessible text applied as information additional to the visible label text. This should be used with care and restraint as it may result in less accessible applications.

// with WNumberField field
field.setAccessibleText("Some further context to this input.");

Access Keys

A WLabel for a WNumberField may be given an access key to provide rapid keyboard access.

Default focus

A WNumberField in an enabled, interactive state may be set as the default focus point for a page. If this is specified it must comply with accessibility principles regarding focus and not put users into a position where they may skip content required for full understanding of the current view. See Setting focus for more information.

Read only

Setting the read-only state changes the output rendering of the WNumberField so that it appears as text output of the value of the control. The control is not able to be interacted with by the user and does not return any value back to the application.

A WNumberField in a readOnly state may be the target of a WSubordinateControl or WAjaxControl. If it is the target of an AJAX action its read-only state may be changed.

Appearance

WNumberField (when not in a read-only state) outputs a HTML input element in the number state. The appearance of this is dependent on the user agent. The illustrations in this document were all created using Google Chrome v53.x on OS X.

Setting input size

The width of a WNumberField is determined for the most part by the user agent.

If min and max constraints are both implemented the width of the input box is determined by that which has the greater absolute value (in capable user agents).

The width may be modified using WField setInputWidth(int) and in most browsers a WNumberField will be no wider than its containing element.

Note, however, that unlike text inputs (such as WTextField) there is no supported size or columns attribute on a WNumberField.

It is, of course, possible to restrain number input width using CSS in either a theme implementation or as custom CSS.

Customising based on HTML class

WNumberField may have one or more values to be added to the component's wrapper 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.

HTML output

A WNumberField will output a span wrapper containing a HTML input element in the number state. This is an interactive, form bound control and therefore may not be used in any context where the content model forbids this content category.

When a WNumberField is in a read-only state the output is a span element containing the value of the field (if any).

Change action

A WNumberField may be used to trigger an Action which runs if the field's value changes. This will trigger any time the value changes and the server application is informed, not only if the WNumberField triggers the call back to the server by being a trigger for a WAjaxControl.

// with WNumberField `field`
field.setActionOnChange(new Action() {
  @Override
  public void execute(final ActionEvent event) {
    // do something
  }
});

Disabling

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

Hiding

A WNumberField may be hidden on page load. When hidden the WNumberField 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. When a WNumberField is hidden a WLabel associated with it is also hidden.

Default submit button

A WNumberField may be associated with a WButton in a way that if the user hits the ENTER key whilst the WNumberField has focus then the nominated WButton will be deemed to be the control which submits the form to the server. This is discussed in more detail in Implicit form submission.

This property does not apply if the WNumberField is in a read-only state or is a trigger for a WAjaxControl.

Non-numeric input

Many modern user agents do not allow users to enter non-numeric characters into a number field. Some of those that do allow non-numeric input automatically clear that input when the user leaves the field. For primitive user agents which do not support the number state of a HTML input element a validation error will be created for any WNumberField which has non-numeric input.

Related components

• WComponent form controls
• WDateField
• WEmailField
• WPartialDateField
• WPasswordField
• WPhoneNumberField
• WTextField

Further information

• JavaDoc;
• HTML Specification;
• Specification of type number;
• List of WComponents.