Skip to content

WTextField

Jump to bottom
Mark Reeves edited this page Jan 3, 2018 · 29 revisions

WTextField is a component for creating a text input control.

Many of the methods and properties of WTextField also apply to WEmailField, WPasswordField and WPhoneNumberField and documentation of those pages may redirect readers here. In these cases references to WTextField may be read as applying equally to these other input components as exceptions are documented in those components' pages.

Why use WTextField

WTextField is intended to acquire user input of a single line of text. It is possibly the most common input control used in web applications. WTextField can be used to acquire constrained input such as numbers or email addresses but the special use input controls, such as WNumberField or WEmailField are usually a better tool for these purposes.

WTextField should be used for number-like input which is not appropriate for a WNumberField.

When not to use

It may be more appropriate to use an alternate input tool under the following circumstances:

Creating a WTextField

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

WTextField field = new WTextField();

Setting value

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

Set text value

// with WTextField `field`
field.setText("Some text");

Set data value

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

Accessibility

Labeling a WTextField

All WTextField in a UI must be associated with a label or otherwise have their usage and intent exposed to all users. This may be done using (in order of preference):

  • WLabel or by using the WTextField in a WFieldLayout (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.

When designing a UI containing a WTextField and a visible label the WLabel must be placed immediately before the WTextField. This is done automatically by WFieldLayout.

A WTextField which is not appropriately labelled may display an unlabelled control warning. A placeholder is not an appropriate replacement or stand-in for a label.

Exposing constraints

If the WTextField 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 label.

Setting a toolTip

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

  • a WTextField with a toolTip

    A WTextField with a toolTip

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

Additional labelling text

WTextField 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 WTextField field
field.setAccessibleText("Some further context to this input.");

Access Keys

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

Submit on change

Up to and including WComponents 1.4.x WTextField supported the notion of SubmitOnChange. This should be avoided as much as possible.

Default focus

A WTextField 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.

This property is ignored if the WTextField is in a read only state.

Input constraints

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

Mandatory

A WTextField may be marked as being a mandatory field in the UI. Its accessors are setMandatory(boolean) and getMandatory(). The input component of the WTextField has the required attribute set and any WLabel for the component is decorated with an indicator that the component is mandatory. If the WTextField does not have a placeholder set then it will have a default placeholder (this defaults to the word "required").

  • a mandatory WTextField with no content

    A mandatory WTextField with no content

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

Maximum length

A WTextField may be constrained to accept a maximum number of characters which the user may enter into the field. When this value is reached the input will not accept any further characters until at least one character is deleted. This is based on characters, not on bytes, and is character set dependent.

This property is ignored if the WTextField is in a read only state.

// given WTextField field
// set the maximum input length to 200 chars
field.setMaxLength(200);

Minimum length

A WTextField may be constrained to accept a minimum number of characters which should be entered into the WTextField if any input is added at all. This is based on characters, not on bytes, and is character set dependent.

This property is ignored if the WTextField is in a read only state.

// given WTextField field
// set the minimum input length to 10 chars
field.setMinLength(10);

Setting a minLength will not automatically make the WTextField mandatory. The minLength is validated only if the WTextField has user input. To make a WTextField mandatory use the mandatory property. These properties may be used in conjunction to enforce a required minimum content input by the user.

// given WTextField `field`
// set the minimum input length to 10 chars
// and make the field mandatory
field.setMinLength(10);
field.setMandatory(true);

Input pattern

The pattern property is used to indicate the format which the content of the WTextField must meet. This is expressed as a JavaScript regular expression. If this property is set then there must be an indication what for required format is in a form which is available to and understandable by users; this indication may be included in the WLabel hint or the component's toolTip. Note that when pattern is set the title has special semantics and is the 'preferred' means for exposing the natural language equivalent of the pattern:

When an input element has a pattern attribute specified, authors should include a title attribute to give a description of the pattern. User agents may use the contents of this attribute, if it is present, when informing the user that the pattern is not matched, or at any other suitable time, such as in a tooltip or read out by assistive technology when the control gains focus.

This property is ignored if the WTextField is in a read only state.

Appearance

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

  • a WTextField with no input

    A typical WTextField with no input

  • a WTextField with user input

    A typical WTextField with user input

Size

A WTextField is always a single line input control (use WTextArea for multi-line input). There are several ways to set or constrain the width of a WTextField. Wherever possible a WTextField will be constrained to be no wider than its containing element.

Width as columns

The columns property is used to set a suggestion for the width of the displayed text input control. The size of a text input is normally proportional to this number in rems in the default fixed-width font of the user agent but may vary. This property has no default and if not specified the user agent will determine the width of the text field.

// given WTextField `field`
// set the width of the field to 3
field.setColumns(3);

  • A WTextField with columns set to 3

    A WTextField with columns set to 3

This property is ignored if the WTextField is in a read only state.

Using WField input width

Setting columns may result in the input element not being able to be resized to fit its container on small viewports. In such cases it may be more appropriate to use WField's setInputWidth(int) to control the width of a WTextField.

Customising based on HTML class

WTextField 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 WTextField will output a HTML input element in the text 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.

The output will be a HTML span element containing the text value of the component if in a read-only state.

Read only

The read only state changes the output rendering of the WTextField 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 WTextField in a readOnly state may be the target of a WSubordinateControl or WAjaxControl. If it is the target of an AJAX action its state may be changed to remove the read-only setting.

  • a read-only WTextField with content

    A read-only WTextField with content

// Create WTextField `field` which is to be read-only
// and have specified content as per illustration:
WTextField field = new WTextField();
field.setText("Initial value");
field.setReadOnly(true);

Change action

A WTextField 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 WTextField triggers the call back to the server by being a trigger for a WAjaxControl.

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

Disabling

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

This property is ignored if the WTextField is in a read only state.

  • a disabled WTextField with no input

    A disabled WTextField with no input

  • a disabled WTextField with content

    A disabled WTextField with content

// given WTextField `field`
// make it disabled
field.setDisabled(true);

Hiding

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

Placeholder

WTextField may have a "placeholder" in an empty instance of an editable WTextField.

One should note that the placeholder is

  • not visible in all browsers;
  • is not visible if the WTextField contains any input; and
  • must not be used as a replacement for a label.

Illustrated below is a sample of a WTextField with placeholder and no content.

A WTextField with placeholder and no content

// given WTextField field
// to set the placeholder
field.setPlaceholder("type here");

This property is ignored if the WTextField is in a read only state.

NOTE that it is not necessary to set the placeholder of a mandatory WTextField. If a placeholder is set on a mandatory WTextField the specified placeholder will be used in preference to the default ("required") placeholder.

Default submit button

A WTextField may be associated with a WButton in a way that if the user hits the ENTER key whilst the WDateField 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.

// given WTextField `field` and WButton `defaultSubmitButton`
field.setDefaultSubmitButton(defaultSubmitButton);

This property is ignored if the WTextField is in a read only state or is a trigger for a WAjaxControl.

Suggestions

WTextField, WPhoneNumberField and WEmailField (not in a read only state) may be made to have a combo-box-like nature by associating them with a WSuggestions.

// given WTextField field and WSuggestions sugg:
// to set the suggestions
field.setSuggestions(sugg);

// to get suggestions for field e.g. to check if the
// value is one of the suggestions
WSuggestions sugg = field.getSuggestions();

Testing

WTextField may be tested using the com.github.bordertech.wcomponents.test.selenium.element.SeleniumWTextFieldWebElement extension of org.openqa.selenium.WebElement.

The best way to get a WTextField from a test view is by using SeleniumWComponentsWebDriver which has a method findWTextField(By). This can be used in conjunction with com.github.bordertech.wcomponents.test.selenium.ByLabel, for example, to find a WTextField using its label's text.

@Test
public void testFindByLabel() {
  SeleniumWComponentsWebDriver driver = getDriver();
  String labelText = "Enter destination";
  SeleniumWTextFieldWebElement field = driver.findWTextField(new ByLabel(labelText, false));
  Assert.assertNotNull("Unable to find text field by label text", field);
}

For more information on members provided by SeleniumWTextFieldWebElement see:

Related components

Further information

Some start pages

Clone this wiki locally