Form element types

Each form element must be declared using a unique id (inside its group) and an element definition.
The id will be used in HTML as is, so mind the standards: no spaces, start with a letter, stick to ASCII characters and use - or _ as separators.
Form elements can be grouped visually and/or logically in fieldsets.
The element definition must contain at least the type of the form element.
Options:

label (optional) - the label of the form element (excluded: hidden, markdown)
labelsmall (optional) - if set to true, the label will be rendered in regular font instead of default bold
tooltip (optional) - Shows a hint for the element. Ignored in structure elements like spacers and HR. Also see Tooltip styling
modal (optional) - Content of a simple Bulma modal in markdown syntax. Refer to the bundled EXAMPLE configuration. Images are interpreted as files located directly in your form directory. The option is ignored in structure elements like spacers and HR.
column (optional) - bulma column sizes defining the width of the form element (excluded: hidden). You can use offset to position the columns, for example is-half is-offset-one-quarter to center a half-width column.

<id>:
    type: <type>
    label: <label>
    column: <column>

Fieldsets

Fieldsets group other form elements (including nested fieldsets).

Options:

children (required) - containing child form elements
background (optional) the background color may be one of [https://bulma.io/documentation/helpers/color-helpers/#background-color](Bulma's colors) (without the prefix has-background-) or a valid CSS definition.
tablestyle (optional) set table view true or false. This will order the contained fieldsets as if they were table columns. The columns will have alternating colors ("zebra"). The head column will be populated by the labels of the children of the first fieldset. Labels in other columns will be hidden to avoid duplication. If cells in the first row must be skipped then Spacers can be used.
scrollable (optional) can be used with tablestyle: The fieldset will not responsively adapt to screen width, but will extend horizontally and can be scrolled. The option may have unpredictable effects in complex forms!
toggle (optional) - the fieldset is disabled and hidden until the toggle condition is met
- field - dotted path to the field whose value will be evaluated to match the toggle condition
- value - required value to toggle the fieldset on, can be a simple string or a YAML array

<id>:
    type: fieldset
    toggle:
      field: <fieldset1>.<fieldset2>.<text1>
      value: 'toogle value'
    children:
      text1:
        type: textinput
      ...

Static fields

Markdown

The provided value will be rendered as Markdown. We use PHP Markdown Extra, which supports some additional syntax.

Options:

markdown (required) - markdown which will be transformed to html

<id>:
    type: markdown
    markdown: Hello _Markdown_!

Image

Representation of an image.

Options:

width (optional) - sets the width of the image
height (optional) - sets the height of the image
src (required) - points to the image file

If the required src starts with

/ the included file is supposed to be placed directly in the document root of the app (public)
'http' or 'https' the value will be interpreted as a url
otherwise the link points to the form directory (data/<form direcotry>/).

  <id>:
    type: image
    label: image label text
    src: /image.png
    width: 200
    height: 200

Download

Representation of a link.

Options:

href (required) - points to the file to download

If the required href starts with

/ the included file is supposed to be placed directly in the document root of the app (public)
http or https the value will be interpreted as a url
otherwise the link points to the form directory (data/<form directory>/).

  <id>:
    type: download
    label: download label text
    href: /download.pdf

The linked file will be opened in a new browser tab / window.

Hidden

Representation of a hidden input.

Options:

value (required) - value of the hidden input

  <id>:
    type: hidden
    value: "hidden value"

Spacer

Representation of a empty table cell. Should be used in table fieldset (tableStyle: true). Options:

label (required) - The label. If the spacer is inside the first fieldset of a table fieldset (tableStyle: true) then the label will be used
double (optional) - If set to true also skips cell below

  <id>:
    type: spacer
    label: "label"
    double: true

Horizontal line

Representation of a hr.

Options:

column (optional)
color (optional) - The color of the hr
height (optional) - The height of the hr

  <id>:
    type: hr
    column: is-full
    color: '#f5f5f5'
    height: 2

Dynamic fields (user input)

All dynamic fields have a value the user can enter. They are required by default.

Options:

validation (optional) - used to apply validation
readonly (optional) - Disables user input. Available only for fields where users type in values. Useful when values are pre-filled from values.yaml

  <id>:
    type: <type>
    tooltip: 'A useful hint for this field.'
    readonly: true
    validation:
      required: false
      match: /^regex_expression$/

Textinput

Simple text input.

  <id>:
    type: textinput
    label: text label
    column: is-half
    placeholder: placeholder value for input
    validation:
      required: false

clone (optional) - When set to true, adds a clone button to the field. That way you can repeat the same input to create a list of variable length.

Numberinput

Simple number (integer) input.

  <id>:
    type: numberinput
    label: numberinput label
    column: is-half
    placeholder: placeholder value for input
    validation:
      required: false

clone (optional) - When set to true, adds a clone button to the field. That way you can repeat the same input to create a list of variable length.

Textarea

Multiline text input field with optional size attributes.

Options:

rows (optional) - sets the number of rows
cols (optional) - sets the number of cols (usage of column should be prefered)

  <id>:
    type: textarea
    label: textarea label
    column: is-half
    placeholder: placeholder value for input
    validation:
      required: false
    rows: 7
    cols: 40

Date

Text input that expects a date and provides a calendar picker.

  <id>:
    type: date
    label: date label
    column: is-two-thirds
    placeholder: placeholder value for input
    validation:
      required: false

Options:

clone (optional) - When set to true, adds a clone button to the field. That way you can repeat the same input to create a list of variable length.

Time

Text input that expects a time and provides a time picker.

  <id>:
    type: time
    label: time label
    column: is-two-thirds
    placeholder: placeholder value for input
    validation:
      required: false

Options:

clone (optional) - When set to true, adds a clone button to the field. That way you can repeat the same input to create a list of variable length.

Datetime

Text input that expects a date and a time and provides a combined picker.

  <id>:
    type: datetime
    label: datetime label
    column: is-two-thirds
    placeholder: placeholder value for input
    validation:
      required: false

Options:

clone (optional) - When set to true, adds a clone button to the field. That way you can repeat the same input to create a list of variable length.

Email

Text input that expects a valid email (the HTML5 validation is handled by the browser).

  <id>:
    type: email
    label: email label
    column: is-half
    placeholder: placeholder value for input
    validation:
      required: false

Options: * clone (optional) - When set to true, adds a clone button to the field. That way you can repeat the same input to create a list of variable length.

Radioset

Representation of a radio group.

Options:

alignment (optional) - sets the alignment of the radios, possible values are vertical or horizontal (default)
choices (required) - defines available options/radios

  <id>:
    type: radioset
    label: radioset label
    alignment: vertical
    validation:
      required: true
    choices:
      - First choice
      - Second choice
      - Third choice

Dropdown

Representation of a select input.

Options:

EITHER choices (optionally required) - defines available options. Markdown is supported.
OR conditional_choices (optionally required) - defines options available if a condition is met (depending on the value of another form field). This option has priority over choices!
empty_label (optional) - a placeholder text shown if no value was chosen (e.g. "Please select"). Note: this is not a real option and has no value that could be saved.
multiselect (optional) - enables selecting multiple options
size (optional) - if multiselect is turned on this defines the number of rows shown, otherwise ignored
default (optional) : Preselects a choice. This is only triggered if the form was never saved before. Preselect in toggles are not supported yet.

  <id>:
    type: dropdown
    label: dropdown label
    multiselect: true
    size: 3
    empty_label: choose an option
    default: 'first choice [a nice link](https://www.cosmocode.de)'
    choices:
      - first choice [a nice link](https://www.cosmocode.de)
      - second choice

    conditional_choices:
      -
        field: fieldsetLevel1.FieldsetLevel2.myFieldname
        value: 'Value A'
        choices:
          - A1
          - A2
      - field: fieldsetLevel1.FieldsetLevel2.myFieldname
        value: 'Value B'
        choices:
          - 10 B
          - 20 B
          - 30 B

Checklist

Representation of a checkbox group.

Options:

alignment (optional) - sets the alignment of the checkboxes, possible values are vertical or horizontal (default)
choices (required) - defines available options/checkboxes. Markdown is supported.
default (optional) : Preselects a choice. This is just triggered if the form was never saved before. Preselect in toggles are not supported yet.

  <id>:
    type: checklist
    label: checklist label
    alignment: vertical
    validation:
      required: false
    default: 'First choice'
    choices:
      - First choice
      - Second choice
      - Third choice

Upload

The uploaded file will be stored with the form element's id as filename. The file extension is preserved, but the original file name is not. It will be sent as an attachment if the form data is configured to be sent by email.

Options:

validation (optional) - the upload form element has special validation rules
- filesize - max upload size, example values: 1048576B, 1024KB, 1MB
- fileext - allowed file extensions, example value (will be lower cased automatically): jpg, pdf, txt

  <id>:
    type: upload
    label: upload label
    validation:
      filesize: 2MB
      fileext: jpg, pdf, txt

Signature

This element lets a user draw a signature on screen to sign the form. If the form data is configured to be sent by email, a JPG image of the signature will be attached. Otherwise it is simply stored along with the rest of inputs as data points to be processed as you wish.

Options:

width (optional) - sets the width of the signature field
height (optional) - sets the height of the signature field

  <id>:
    type: signature
    label: signature label
    height: 400
    width: 900
    validation:
      required: true

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

formelements.md

formelements.md

Form element types

Fieldsets

Static fields

Markdown

Image

Download

Hidden

Spacer

Horizontal line

Dynamic fields (user input)

Textinput

Numberinput

Textarea

Date

Time

Datetime

Email

Radioset

Dropdown

Checklist

Upload

Signature

Files

formelements.md

Latest commit

History

formelements.md

File metadata and controls

Form element types

Fieldsets

Static fields

Markdown

Image

Download

Hidden

Spacer

Horizontal line

Dynamic fields (user input)

Textinput

Numberinput

Textarea

Date

Time

Datetime

Email

Radioset

Dropdown

Checklist

Upload

Signature