Skip to main content

Text Box

What is the Form Text Box?​

The text box form type is a multi-line text area for collecting longer free text from the user. You can control its size, how text wraps, whether it can be resized, and an allowed character-count range.

textbox.png

Options​

Min length​

  • Editor label: Min length. Property textBoxMinLength.
  • The lowest number of characters the value may contain to be considered valid.
  • Minimum: 0. Default: 5.

Max length​

  • Editor label: Max length. Property textBoxMaxLength.
  • The highest number of characters the value may contain to be considered valid.
  • Minimum: 0. Default: 20.
  • The character-count check is only performed when Max length is greater than Min length. If Max length is less than or equal to Min length, no length validation is applied.

Rows​

  • Editor label: Rows. Property textBoxRowsCount.
  • The number of visible text lines (the text area rows attribute).
  • Minimum: 0. Default: 5.

Cols​

  • Editor label: Cols. Property textBoxColsCount.
  • The visible width of the text area in average character widths (the text area cols attribute).
  • Minimum: 0. Default: 5.

Wrapping​

  • Editor label: Wrapping. Property textBoxWrapping.
  • Controls how text wraps and how line breaks are included in the submitted value (the text area wrap attribute). Default: Off.
  • Possible values:
    • Off (off): text is not wrapped; it stays on one long line with horizontal scrolling.
    • Soft (soft): text wraps visually, but the submitted value contains no inserted line breaks.
    • Hard (hard): text wraps and line breaks are inserted into the submitted value at each wrap point.

Resizable​

  • Editor label: Resizable. Property textBoxResizable.
  • When enabled, the user can resize the text area vertically; when disabled, resizing is turned off.
  • Values: enabled / disabled. Default: disabled.

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: minChars, maxChars, rows, cols, wrapping, and resizable.
  • Writes are debounced by 200 ms.
  • A write is triggered when:
    • The widget is rendered (after any initial datasource value is restored).
    • The input changes (on every keystroke).
    • The text area loses focus (on blur).
    • An external message updates the field.

Validation​

  • The text box validates by character count, and only when Max length is greater than Min length.
  • If the value is shorter than Min length, the field is invalid and the message Too few character! Minimum {min} required! is produced.
  • If the value is longer than Max length, 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 box can send two sensor events. {FORM-NAME} is the name assigned to the field.

  • {FORM-NAME}

    • Value: the current field value.
    • Triggered each time the field writes to the Mock datasource (render, input change, blur, 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 box 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, 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 box 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