An example of a text field with a caption retrieved from the localized messages pack:

<textField id="nameField" caption="msg://name"/>

In Web Client with a Halo-based theme, you can set predefined styles to the TextField component using the stylename attribute either in the XML descriptor or in the screen controller:

<textField id="textField"
           stylename="borderless"/>

textField.setStyleName(HaloTheme.TEXTFIELD_INLINE_ICON);

To create a text field connected to data, use dataContainer and property attributes.

<data>
    <instance id="customerDc" class="com.company.sales.entity.Customer" view="_local">
        <loader/>
    </instance>
</data>
<layout>
    <textField dataContainer="customerDc" property="name" caption="msg://name"/>
</layout>

If the field is not connected to an entity attribute (i.e., the data container and attribute name are not set), you can set the data type using the datatype attribute. It is used to format field values. The attribute value accepts any data type registered in the application metadata – see Datatype. Typically, TextField uses the following data types:

<textField id="integerField" datatype="int" caption="msg://integerFieldName"/>

databinding.conversion.error.int = Must be Integer

You can specify a custom conversion error message declaratively in the screen XML descriptor using the conversionErrorMessage attribute:

<textField conversionErrorMessage="This field can work only with Integers" datatype="int"/>

textField.setConversionErrorMessage("This field can work only with Integers");

Text field can be assigned a validator – a class implementing Field.Validator interface. The validator limits user input in addition to what is already done by the datatype. For example, to create an input field for positive integer numbers, you need to create a validator class:

public class PositiveIntegerValidator implements Field.Validator {
    @Override
    public void validate(Object value) throws ValidationException {
        Integer i = (Integer) value;
        if (i <= 0)
            throw new ValidationException("Value must be positive");
    }
}

<textField id="integerField" datatype="int">
    <validator class="com.sample.sales.gui.PositiveIntegerValidator"/>
</textField>

TextField supports TextChangeListener defined in its parent TextInputField interface. Text change events are processed asynchronously after typing in order not to block the typing.

textField.addTextChangeListener(event -> {
    int length = event.getText().length();
    textFieldLabel.setValue(length + " of " + textField.getMaxLength());
});
textField.setTextChangeEventMode(TextInputField.TextChangeEventMode.LAZY);

The TextChangeEventMode defines the way the changes are transmitted to the server to cause a server-side event. There are 3 predefined event modes:

EnterPressListener allows you to define an action executed when Enter is pressed:

textField.addEnterPressListener(enterPressEvent ->
        notifications.create()
                .withCaption("Enter pressed")
                .show());

ValueChangeListener is triggered on the value changes when the user finished the text input, i.e. after the Enter press or when the component loses focus. An event object of the ValueChangeEvent type is passed to the listener. It has the following methods:

If a text field is linked to an entity attribute (via datasource and property), and if the entity attribute has a length parameter defined in the @Column JPA-annotation, then the TextField will limit the maximum length of entered text accordingly.

<textField id="shortTextField" maxLength="10"/>

By default, text field trims spaces at the beginning and at the end of the entered string. I.e. if user enters " aaa bbb ", the value of the field returned by the getValue() method and saved to the linked entity attribute will be "aaa bbb". You can disable trimming of spaces by setting the trim attribute to false.

Text field always returns null instead of an entered empty string. Therefore, with the trim attribute enabled, any string containing spaces only will be converted to null.

The setCursorPosition() method can be used to focus the field and set the cursor position to the specified 0-based index.