Skip to main content

Checkbox

What is the Form Checkbox?​

The checkbox form type allows users to select multiple items from a list. The settings let you define the available items and control how the boxes look, including an image mode where every option shows a picture.

checkbox.png

Options​

Values​

  • Specifies the selections that will be rendered. Selections are separated by new lines, with each new line representing a new entry. Empty lines are skipped.
  • Entries can be tagged as 'selected', 'correct', or both. Tags are removed from the rendered label and must be at the start of the line.

Tagging System:​

  • [!] - Correct entry
  • [*] - Selected entry
  • [!*] or [*!] - Selected and correct entry

Example Entries:​

  • [*]Large is rendered as Large (selected by default)
  • [!*]Small is rendered as Small (selected and correct)

Button Style​

Defines the appearance of the checkboxes. Default: Rectangular

None​

No box appears; only the label functions as the checkbox.

checkbox-button-style-none.png

Rectangular​

Displays rectangular-styled checkboxes.

checkbox-button-style-rectangular.png

Rounded​

Displays rounded-styled checkboxes.

checkbox-button-style-rounded.png

Color​

No label is shown; each value line is treated as a color code, filling the checkbox with the specified color.

checkbox-button-style-color.png checkbox-button-style-color-setting.png

Image​

Every option is rendered as a picture with its label, instead of a checkbox. This is the mode where the checkbox pulls its images out of the value text.

checkbox-button-style-image.png

How the images are extracted​

When Button Style is set to Image, the widget reads the image for each option from the folder configured in the Image folder general setting (Select Option Image Folder). The image file is referenced from inside the value line using a [fileName] token written in square brackets:

  • The image file name (including its extension) is written in square brackets anywhere after the label text.
  • The [fileName] token is removed from the rendered label, and its contents are matched against the file names in the selected image folder. The matched image is then displayed for that option.
  • The value tags ([*], [!], [*!]) are parsed first and stripped, so a single line can carry both a value tag and an image token.

Example value lines (with an image folder that contains cheese.png and ham.png):

[*]Cheese[cheese.png]
Ham[ham.png]
  • Cheese is shown with cheese.png and is selected by default.
  • Ham is shown with ham.png.
Note

The image is looked up by exact file name in the configured Image folder. If no file matches, the option is shown without an image.

Image styling options​

These options are only visible when Button Style is set to Image.

  • Image placement: Where the image sits relative to the label. Possible values: Left, Right, Top, Bottom.
  • Distance between image and text: Spacing between the image and its label. Range: 0 - 50. Default: 0
  • Image rounding: Rounds the corners of the image, in percent. Range: 0 - 50. Default: 0
  • Image size: The image size, in em. Range: 0.5 - 10. Default: 3
  • Image border width: Border thickness of the image, in pixels. Range: 0 - 30. Default: 0
  • Image unselected border color: Border color of unselected images. Default: #000
  • Image selected border color: Border color of the selected image. Default: #000
  • Selected Background Color: Background color behind the selected image. Default: #00a5fe
  • Image button text box height: Height of the label text box under/next to the image, in pixels. Range: 0 - 150. Default: 30

Width Mode​

Defines how the checkboxes are sized:

  • Default: Uses the minimal required space.
  • Auto: All boxes have equal width.
  • Fixed: Each box takes up at least the specified fixed width.
  • Fixed width (px): The minimum width per box, in pixels. Only visible when Width Mode is Fixed. Default: 100

Additional Appearance Settings​

  • Primary Color: The main color of the checkboxes (box and selected background). Default: #00a5fe
  • Unselected Background Color: The background color for unselected checkboxes.
  • Unselected Font Color: The font color for unselected checkboxes.
  • Background Rounding: The rounding of the checkbox backgrounds. Default: 12
  • Distance between buttons: Spacing between the boxes. Default: 5
  • Line height: The line height applied to the option list. Default: 1
  • Direction: The flex direction (Column, Row, Column-Reverse, Row-Reverse).

Setting Mock Field and Own Value​

The checkbox updates its own value and the mock field with the selected labels joined by , (comma and space; translated if a localisation is active). This happens when:

  • The checkbox renders (pre-selected values are written to the mock field).
  • A selection is made.
  • An external message updates values or selections.

In the editor (not the displayer) the value is not written out; writing only happens on a live displayer.

Validation​

If validation is enabled (the Validate Field general setting):

  • The field is valid only when the set of selected options exactly matches the set of correct options. That is, every correct option ([!]) must be selected and no incorrect option may be selected.
  • If a wrong option is selected, or a correct option is left unselected, the checkbox is marked invalid.
  • If Show Validation is enabled, the field displays a validation border.

Sensor Events​

The checkbox emits the following sensor events:

  • On every value write, an event named after the form carrying the selected labels:

    {FORM-NAME} value: [label1, label2, ...]

  • When validation runs, a validity event:

    {FORM-NAME}-valid value: [true/false]

  • When the active language changes (via the setLocalisation external command), the {FORM-NAME} event is re-emitted with the translated labels of the current selection.

Example:​

example-checkbox -> Large, Small
example-checkbox-valid -> true

External Messages​

The checkbox responds to the three basic external messages:

  • Set Form: Splits the message value by the ; (semicolon) character into options, parsing the same value tags ([*], [!], [*!]) as the Values setting, and replaces the current options. Updates the Mock and Own values. If the value is empty, the options are cleared.
  • Clear Form: Deselects all options and clears the mock field.
  • Reset Form: Restores the checkbox to its initial state (re-reads the Values setting). Validation is re-evaluated.

Value from Datasource​

If a datasource array is assigned to the checkbox (via value from datasource), its elements are converted into selectable options the same way as the Values setting and appended after the static values.

  • String array elements are used directly.
  • For an array of objects, the value of the key set in the Datasource search key general setting is used from each object.
  • For a plain object, its keys are used.
  • The Remove duplicates general setting filters out duplicate options.
Last updated on