Skip to main content

Text

What is the Form Text?​

The text form type is a single-line input field for collecting free text from the user. It can capitalize the input, enforce a character-count range, and reformat what is typed through a character mask.

text.png

Options​

Capitalize​

  • Editor label: Capitalize. Property textInputCapitalize.
  • When enabled, every character typed into the field is converted to upper case as it is entered.
  • Values: enabled / disabled. Default: disabled.

Minimum characters​

  • Editor label: Minimum characters. Property textInputMinChars.
  • The lowest number of characters the value may contain to be considered valid.
  • Numeric range: 1 - 64, step 1. Default: 6.

Maximum characters​

  • Editor label: Maximum characters. Property textInputMaxChars.
  • The highest number of characters the value may contain to be considered valid.
  • Numeric range: 1 - 64, step 1. Default: 16.
  • The character-count check is only performed when Maximum characters is greater than Minimum characters. If Maximum is less than or equal to Minimum, no length validation is applied.

Mask​

  • Editor label: Mask. Property textInputMask.
  • A pattern string that reformats the input as the user types. Default: empty (no mask, the raw value is used).
  • When a mask is set, the masked result becomes the visible value and the value written to the datasource.

Mask syntax​

The mask is read one character at a time. Each mask character is either a wildcard (a placeholder for a user character) or a literal.

  • # - Alphanumeric placeholder. Accepts a single letter (a-z, A-Z) or digit (0-9).
  • X - Alphabetic placeholder. Accepts a single letter (a-z, A-Z) only.
  • 0 - Numeric placeholder. Accepts a single digit (0-9) only.
  • Any other character - Literal. It is inserted into the value automatically at its position.

Mask behavior​

  • A typed character that matches the current placeholder is kept, and both the input and the mask advance to the next position.
  • A typed character that does not match the current placeholder is dropped (for example, a letter typed where a 0 placeholder expects a digit is removed).
  • A literal character is added automatically. If the user did not type that exact literal, the typed character is re-evaluated against the next mask position, so separators such as - appear on their own.
  • Once the mask is fully consumed, no further characters are accepted, so the mask also caps the length of the value.

Example​

With the mask ####-XXX-00 (four alphanumeric characters, a literal hyphen, three letters, a literal hyphen, two digits):

  • Typing ab12cde99 produces ab12-cde-99.
  • The hyphens are inserted by the mask; the user does not type them.

Setting Mock Field and Own Value​

  • Writing only happens in the displayer; in the editor it is disabled.
  • On each write the field calls the SDK to set its own value and writes its value to the bound form-output datasource, together with these properties: capitalize, minChars, maxChars, maskEnabled, and mask.
  • Writes are debounced by 200 ms.
  • The value written is the final value after capitalization and masking are applied.
  • A write is triggered when:
    • The widget is rendered (after any initial datasource value is restored).
    • The input changes (on every keystroke).
    • An external message updates the field.

Validation​

  • The text field validates by character count, and only when Maximum characters is greater than Minimum characters.
  • If the value is shorter than Minimum characters, the field is invalid and the message Too few character! Minimum {min} required! is produced.
  • If the value is longer than Maximum characters, the field is invalid and the message Too much character! Maximum {max} allowed! is produced.
  • If the value is within the range, the field is valid and any error is cleared.
  • An empty value clears the validation state and any error.
  • How the result is surfaced depends on the common Error settings:
    • Validate Field must be enabled for the validity to be written to the form summary and for the {FORM-NAME}-valid sensor event to be sent.
    • Show Validation adds a colored border indicating validity.
    • Show error messages displays the error text under the field while the value is invalid.

Sensor Events​

The text field can send two sensor events. {FORM-NAME} is the name assigned to the field.

  • {FORM-NAME}

    • Value: the current (capitalized and masked) field value.
    • Triggered each time the field writes to the Mock datasource (render, input change, external message), unless the triggering external command is a silent one.

  • {FORM-NAME}-valid

    • Value: true or false, the result of validation.
    • Triggered only when Validate Field is enabled, after each validation check (debounced 150 ms).

External Messages​

The text field listens to the basic form commands:

  • Set Form: reads the value parameter from the message. If it is missing or not a string, the input is cleared; otherwise the input is set to that value. The value is then capitalized, masked, validated, and written to the Mock and own value.
  • Reset Form / Clear Form: empty the input and update the validation, Mock, and own value.
  • The silent variants (silentResetForm, silentClearForm) do the same but suppress the value sensor event.

Value from Datasource​

The text field does not accept a list of options from a datasource. On render it reads any existing value stored under its field name in the bound form-output datasource and pre-fills the input with it.

Last updated on