Skip to main content

Common Settings

Every Form field type shares a set of common settings and behaviors regardless of the chosen type. This page documents those shared settings once. The type-specific options are described on each type's own page.

Export type​

Controls the shape of the data each field writes into the bound form output (mock) datasource. See the Form intro for how to set up the output datasource.

  • Simple: Only the field's value is stored, under the field's name. This is the lightest format.
  • Complex: The full field object is stored: its value, name, type-specific properties, a settings block (type, placeholder, required, alignment, showLabel, and the error settings), and a lastModified timestamp.

Default: Simple

Form summary​

Whenever a field with Validate Field enabled runs its validation, it writes a FormSummary object into the output datasource:

FieldDescription
countTotal number of validated fields.
validNumber of fields currently valid.
invalidNumber of fields currently invalid.
fieldsA map of field name to its boolean validity.
Multiple widgets

Each Form widget is an isolated instance and tracks only its own field. When a widget writes FormSummary, it replaces the whole object with its own field's summary. This means that when several Form widgets share one output datasource, FormSummary reflects only the field that validated most recently, not all of them. To evaluate the validity of an entire multi-field form, use the per-field {FORM-NAME}-valid sensor events (see Collecting and validating a form) rather than relying on FormSummary.

General Settings​

Name​

A unique identifier for this form field instance. It is used as the key in the output datasource and as the base name for the field's sensor events. The field is not rendered until a name is set.

Note

While nothing prevents naming two fields the same, doing so on the same page is highly discouraged and can cause errors.

Placeholder​

The label/placeholder text shown for the field. It is only displayed when Show label is enabled.

Show label​

Shows the placeholder text as a label for the field. Default: Disabled

Alignment​

The horizontal alignment of the input. Possible values: Left, Center, Right. Default: Left

Required​

Marks the input as required. Default: Disabled

Validate Field​

Enables validation for the field. When enabled, the field evaluates its value and writes the result to the output datasource (and to the FormSummary), and emits the {FORM-NAME}-valid sensor event. Whether a field validates and how depends on its type. Default: Disabled

Selection Settings​

These settings apply to the selection types that build their options from a list or a datasource (Radio, Checkbox, Dropdown).

Image folder​

The folder from which option images are loaded when a selection type uses an image-based button style. See Radio and Checkbox for how images are matched to options.

Datasource search key​

When a connected datasource is an array of objects, the value of this key is read from each object and used as the option text. Default: (empty)

Remove duplicates​

Filters out duplicate options coming from the datasource. Default: Enabled

Font Settings​

Controls the typography of the field. The group exposes:

  • Font family
  • Font size
  • Font style
  • Font weight
  • Font color
  • Text decoration

Error Settings​

These settings control how validation results are shown. They are relevant when Validate Field is enabled.

Show validation​

Shows a colored outline indicating whether the field is currently valid or invalid. Default: Enabled

Show error messages​

Shows a textual error message explaining why the input is invalid (for the types that produce one). Default: Enabled

Error alignment​

Where the error message is positioned relative to the field. Possible values: Top Left, Top Center, Top Right, Center Left, Center Right, Bottom Left, Bottom Center, Bottom Right. Default: Bottom Left

Success color​

The color used for the valid state outline. Default: #7cfc00

Error color​

The color used for the invalid state outline. Default: #ff0000

Speech to Text​

Text-based input types can offer voice input. When enabled, a microphone icon is shown next to the input; tapping it starts/stops speech recognition and the recognized text is typed into the field.

Speech recognition only works on a live displayer, on a device/browser that supports the Web Speech API, and requires microphone permission. Recognition stops automatically after about 2 seconds of silence.

Allow speech input​

Enables the speech-to-text feature for the field. Default: Disabled

Disable speech icon​

Keeps the microphone icon visible but non-interactive (tapping it does nothing). Speech can then only be toggled with the external command below. Default: Disabled

Speech input icon size​

The size of the microphone icon, in pixels. Range: 0 - 200. Default: 24

Speech language​

The recognition language (a BCP-47 code such as en-US). A wide list of languages is available. Default: en-US

Speech external command and sensor event​

  • External command toggleSpeechInput starts or stops recognition for the field.
  • When recognition ends, the field emits the sensor event {FORM-NAME}-VoiceInputDetectionEnded with the value true.

Localisation​

A field's text (labels and option labels) can be translated at display time without changing its configured value.

Localisation text​

A multi-line setting where each line defines one translation, in the format:

[language]key|value
  • [language] is the language code in square brackets.
  • key is the original text.
  • value is the translated text.

Example:

[de]Submit|Absenden
[fr]Submit|Envoyer

The active language is selected at runtime with the external command setLocalisation (its value parameter is the language code; an empty or non-string value clears the localisation and shows the original text). When the language changes, translated fields re-render and re-emit their value sensor event with the translated text.

Shared Sensor Events​

Beyond any type-specific events, every field shares these:

EventValueTriggered
{FORM-NAME}The field's current valueOn every write to the output/mock field (unless suppressed by a silent Clear/Reset).
{FORM-NAME}-validtrue / falseWhen validation runs (only when Validate Field is enabled).

{FORM-NAME} is the field's Name.

Shared External Messages​

Most field types respond to the three standard form commands. The exact effect is type-specific (see each type's page):

  • Set Form: Replaces the field's value/options with the value supplied in the message.
  • Clear Form: Clears the field's value.
  • Reset Form: Restores the field to its initial, configured state.
Last updated on