Smart forms

Form

General YAML structure

This is an example of a form with 2 fields. The second field (named second) has a visibility condition. In this case, the condition is a reference to the global condition named condition-one. Using global conditions enables re-use and promotes deduplication.

form:
    fields:
    -   name: first
        label: Entering a number greater than 12 will show the second field
        type: number
        placeholder: Placeholder here
    -   name: second
        label: This field will only be visible if the first field has a value greater than 12
        dependsOn:
            ref:
                condition: condition-one

conditions:
-   name: condition-one
    type: greaterThan
    field: first
    value: 12

Form options

Smart form accepts a number of optional settings. These are called options.

form:
    options:
        numbering: "auto"
        numberSuffix: "."

    fields:
    -   <fields go here>

Available form options:

Name	Default value	Description
numbering	`none`	Sets whether fields should be numbered. Possible values are: `none` (field will not be numbered), `auto` (field will be numbered), `per-segment` (numbering will restart for each segment), `per-fieldset` (numbering will restart for each fieldset), `restart` or `reset` (numbering restarts at `startingNumber` or 1).
startingNumber	1	The number at which numbering starts.
numberPrefix	(single space)	A prefix for numbering.
numberSuffix		A suffix for numbering.

Form segments

Forms can be divided into segments. When done, the segment prop of the SmartForm component should be specified. If not, all fields will be rendered regardless.

form:
    segments:
    -   name: this-is-a-segment
        title: Title of this segment
        fields:
        -   name: name-of-field
            label: Label for this field
            type: text
        -   name: another-field
            label: Second field
    -   name: second-segment
        title: Another segment
        fields:
        -   <fields for this segment go here>

Available segment properties:

Name	Mandatory	Default value	Description
name	yes		The name of the segment. This name is used in the `segment` prop of the SmartForm component.
title	yes		A title for this segment.
fields	yes		The fields for this segment.
numbering	no	`none`	Sets whether fields in this segment should be numbered. Possible values are: `none` (field will not be numbered), `auto` (field will be numbered), `per-segment` (numbering will restart for each segment), `per-fieldset` (numbering will restart for each fieldset), `restart` or `reset` (numbering restarts at `startingNumber` or 1).
startingNumber	no	1	The number at which numbering starts.
numberPrefix	no	(single space)	A prefix for numbering.
numberSuffix	no		A suffix for numbering.

Fields

Every field in a smart form can have multiple properties. Some are mandatory and some depend on the type of field.

Common field properties

Name	Mandatory	Default value	Description
`name`	yes		Used in condition references and will be the key JSON data resulting from filling the form.
`type`	no	`text`	The data type for the form field. Possible values are described below.
`description`	no		A descriptive text that is displayed above the rendered field.
`value`	no		The default value for the field. Will not override any value entered by the user. If the value doesn't match the set data type, it will be ignored.
`label`	yes		The text that will describe the field in the generated form. Will automatically append a semicolon (`:`) to the text, except when the text ends with any of the characters `.`, `:`, `!`, `?`.
`required`	no	`boolean` or condition	If boolean, or outcome of condition is true, the field will be marked as required. If the attribute is not specified, the field will never be required.
`disabled`	no	`boolean` or condition	If boolean, or outcome of condition is true, the field will be disabled and can't be edited. If the attribute is not specified, the field will never be disabled.
`visible`	no	`boolean` or condition	If boolean, or outcome of condition is true, the field will be visible. If false, the field will not be visible. If the attribute is not specified, the field will always be visible.
`tooltip`	no		If specified, a tooltip will be rendered near the form field with the text set in this property.
`tooltipPosition`	no		Denotes the position of the tooltip relative to the field. Allowed values: `top`, `bottom`, `left`, `right`. Defaults to `bottom`.
`help`	no		A help text. If specified, a small icon is rendered near the field which, when hovered, will display the text.
`numbering`	no	`none`	Sets whether fields should be numbered. Possible values are: `none` (field will not be numbered), `auto` (field will be numbered), `per-segment` (numbering will restart for each segment), `per-fieldset` (numbering will restart for each fieldset), `restart` or `reset` (numbering restarts at `startingNumber` or 1). When not specified, the value of the parent (fieldset, segment, form) is used.
`startingNumber`	no	1	The number at which numbering starts. When not specified, the value of the parent (fieldset, segment, form) is used.
`numberPrefix`	no		A prefix for numbering. When not specified, the value of the parent (fieldset, segment, form) is used.
`numberSuffix`	no	(single space)	A suffix for numbering. When not specified, the value of the parent (fieldset, segment, form) is used.
`placeholder`	no		The placeholder value (input field hint) for this field. Note that not every field type will display a placeholder.

Supported field types

Supported field types:

Name	Description
`text`	Plain text. When unspecified, the field type defaults to `text`.
`date`	Date field.
`number`	Numeric values.
`select`	A dropdown field.
`checkbox`	Check box for true/false values.
`header`	Renders a simple HTML header. The value rendered is in `label` property.
`fieldset`
`file`	A file upload field. This field type is currently not tested.
`textarea`	Plain text with room for multiple lines of input.
`hidden`	A hidden field. Useful for custom components that have to produce a value.
`info`
`local-only`	A hidden field whose data will not be sent to the back-end. Useful in custom fields that need to temporarily store data.
`radio`
`custom`	A custom field. This field will not produce a value by itself. If a value needs to be stored, use an accompanying hidden field.

Additional attributes

Specific types of input fields support additional attributes:

Text field attributes

Text fields don't have additional attributes.

Example: text field

form:
    fields:
    -   name: name
        label: First name

Textarea field attributes

Name	Mandatory	Type	Description
`rows`	no	`number`	The height (in rows) of this textarea field.
`cols`	no	`number`	The width (in columns) of this textarea field.

Example: Textarea

form:
    fields:
    -   name: textarea
        label: Textarea field
        type: textarea
        cols: 50
        rows: 6

Number field attributes

Name	Mandatory	Type	Description
`value`	no	`number`	The value for this number field.
`min`	no	`number`	The minimal value for this number field.
`max`	no	`number`	The maximum value for this number field.
`step`	no	`number`	The stepping (interval) for this number field.

Example: Number field

form:
    fields:
    -   name: depth
        label: Depth of measurement
        type: number
        min: 3
        max: 35
        step: 1

Select field attributes

Name	Mandatory	Type	Description
`value`	no	`string`	The value for this select field. May be empty.
`items`	yes	array of `select field item` items (see below)	The items which can be selected in this select field.

Select field item

Name	Mandatory	Type	Description
`label`	no	`string`	The label of the select field item. When not specified, the `value` attribute is used instead.
`value`	yes	`number` or `string`	The value for the select field item.

Example: Select field

form:
    fields:
    -   name: state
        label: Project state
        type: select
        items:
        -   label: Requested
            value: 2
        -   label: Starting
            value: starting
        -   label: Ending
            value: 12

Date field attributes

Name	Mandatory	Type	Description
`value`	no	`date`	The value for this date field.
`minYear`	no	`number`	The lowest year that can be picked. Defaults to 2000.
`maxYear`	no	`number`	The highest year that can be picked. Defaults to 2100.

Example: Date field

form:
    fields:
    -   name: start-date
        label: Date field
        type: date

Radio field attributes

Name	Mandatory	Type	Description
`subType`	no	`string`	The type of this radio field. Allowed values are `radio` (for a standard radio field), `smiley` or `smileys` for a smiley rating radio field. Defaults to `radio`.
`values` (for standard radio field)	yes	array of `radio value`	The values that correspond to the radio field options. This field is mandatory for a standard radio field.
`values` (for smiley radio field)	no	array of `string`	The values that correspond to the smiley options. This property is optional but, if specified, must have exactly 5 string values.

Radio field value

Name	Mandatory	Type	Description
label	yes	`string`	The display label of the radio field option.
value	yes	`string`	The radio field option value. This is the value that will be stored for the form.

Example: Standard radio field

form:
    fields:
    -   name: radio
        label: Radio field
        type: radio
        values:
        -   label: First selectable option
            value: 12
        -   label: Second option
            value: 17

Example: Smiley rating radio field

form:
    fields:
    -   name: radio
        label: Radio field
        type: radio
        subType: smiley

Example: Smiley rating radio field with custom values

form:
    fields:
    -   name: radio
        label: Radio field
        type: radio
        subType: smiley
        values:
        -   one
        -   three
        -   five
        -   six
        -   eight

Checkbox field attributes

Checbox fields don't have additional attributes.

Example: Checkbox

form:
    fields:
    -   name: checkbox
        label: Checkbox field
        type: checkbox

Header field attributes

Header fields don't have additional attributes.

Example: Header

form:
    fields:
    -   name: header
        label: Header
        type: header

Fieldset attributes

Name	Mandatory	Type	Description
fields	yes	List of `field`	The fields held by the field set.

Example: Fieldset with three collapsible groups

form:
    fields:
    -   name: first-fieldset
        label: fieldset
        type: fieldset
        fields:
        -   name: first-field
            label: field in first fieldset

File field attributes

File fields don't have additional attributes.

Example: File field

form:
    fields:
    -   name: file
        label: File field
        type: file

Hidden field attributes

Hidden fields don't have additional attributes.

Example: Hidden field

form:
    fields:
    -   name: hidden-field
        type: file

Info field attributes

Name	Mandatory	Type	Description
severity	no	`string`	Denotes the severity of the info message. Allowed values are `success`, `info`, `warn`, `error`. Defaults to `info`.

Example: Info field

form:
    fields:
    -   name: info
        label: "warning: this is a text describing a warning"
        type: info
        severity: "warn"

Label field attributes

Name	Mandatory	Type	Description
`text`	yes	`string`	The static text to render. If this attribute is not specified or is left empty, the value of attribute `html` will be used instead
`html`	yes	`string`	The HTML value to render. If both `text` and `html` are specified, `html` is used.

Example: Label field with text value

form:
    fields:
    -   name: label
        label: Label field with text value
        type: label
        text: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur molestie lacus vel eros tempor varius non quis orci. Quisque a varius orci. Nullam vitae risus in est dapibus placerat in eget nibh. Morbi varius tempus fermentum. Praesent rutrum leo nisl, ut iaculis augue tempus ut. Nunc volutpat lectus viverra, ultricies diam vel, hendrerit diam. Donec dignissim egestas metus, ac ultrices magna vestibulum sed. Fusce vel diam id orci pretium imperdiet non ac sem. Duis non ante elit. Integer efficitur efficitur accumsan. Vestibulum sodales elit sit amet ipsum ultricies, eu tempus felis aliquam. Aenean sollicitudin lorem vel elit malesuada, ac porta ex mollis. Phasellus at leo id enim tempus porta non eu dolor.

Example: Label field with html value

form:
    fields:
    -   name: label
        label: Label field with text value
        type: label
        html: Label fields also accept <strong>HTML</strong> values with <em>HTML</em> tags

Conditions

A number of conditions types have been defined. Most take a target field and return a boolean value, though some may need extra details. They are detailed below.

Condition types

Supported condition types:

Name	References `field`	Description
`valueSet`	yes	Checks if the target field has a value set.
`valueEmpty`	yes	Checks if the target field has no value set. Inverse of `valueSet`.
`all`	no	Checks if all supplied sub conditions are true. Sub conditions are given as an array of `Condition` (see this table).
`any`	no	Checks if at least one supplied sub conditions is true. Sub conditions are given as an array of `Condition` (see this table).
`isTrue`	yes	Checks if the target field has a `true` value.
`isFalse`	yes	Checks if the target field has a `false` value.
`greaterThan`	yes	Checks if the target field has a value that is greater than that of the supplied `value` attribute.
`greaterThanOrEqual`	yes	Checks if the target field has a value that is greater than or equal to that of the supplied `value` attribute.
`equal`	yes	Checks if the target field has a value that is equal to that of the supplied `value` attribute. Supports both text and numbers.
`lessThan`	yes	Checks if the target field has a value that is less than that of the supplied `value` attribute.
`lessThanOrEqual`	yes	Checks if the target field has a value that is less than or equal to that of the supplied `value` attribute.

Conditions referencing a field must have an attribute:

Name	Mandatory	Type	Description
`field`	yes	`string`	The name of the field to which this condition refers.

Field condition

A field can either have an embedded condition or a reference to a global condition. Examples are below.

Embedded condition

When embedding a condition, the property (visible, required, disabled) will have a child named condition that has attributes name, type, field and optionally a value. These are detailed below.

An example configuration is below. Here we have two fields. One (named first) that is numeric, and ane (named second) that is a text field that will only be shown if field first has a numeric value greater than 12.

form:
    fields:
    -   name: first
        label: Entering a number greater than 12 will show the second field
        type: number
        placeholder: Placeholder here
    -   name: second
        label: This field will only be visible if the first field has a value greater than 12
        visible:
            condition:
                name: condition-one
                type: greaterThan
                field: first
                value: 12

Referencing a global condition

A field can also reference a global condition. This is useful for re-using conditions in multiple fields.

This example is the same as in the previous section, but in this case field second references a global condition, called condition-one. This field too, will only be shown if field first has a value greater than 12.

form:
    fields:
    -   name: first
        label: Entering a number greater than 12 will show the second field
        type: number
        placeholder: Placeholder here
    -   name: second
        label: This field will only be visible if the first field has a value greater than 12
        visible:
            condition: condition-one

conditions:
-   name: condition-one
    type: greaterThan
    field: first
    value: 12

Referencing to multiple nested conditions

A field can also reference to nested global conditions. This is useful for re-using multiple conditions in multiple fields.

form:
    fields:
    -   name: first
        label: Entering a number greater than 12 will show the second field
        type: select
        items:
          - value: option 1
          - value: option 2
          - value: option A
          - value: option B
          - value: option I
          - value: option II
          - value: option III

    -   name: second
        label: Show when option 1 or option 2 is selected
        visible:
            condition: condition-one

    -   name: third
        label: Show when option A or option B is selected
        visible:
            condition: condition-two

    -   name: fourth
        label: Show when option I, option II or option III is selected
        visible:
            condition: condition-three


conditions:
-   name: condition-one
    type: any 
    field: first
    conditions: 
    - name: select-option_1 
      type: equal 
      field: first 
      value: option 1
    - name: select-option_2
      type: equal 
      field: first 
      value: option 2

-   name: condition-two
    type: any 
    field: first
    conditions: 
    - name: select-option_A
      type: equal 
      field: first 
      value: option A
    - name: select-option_B
      type: equal 
      field: first 
      value: option B

-   name: condition-three
    type: any 
    field: first
    conditions: 
    - name: select-option_I
      type: equal 
      field: first 
      value: option I
    - name: select-option_II
      type: equal 
      field: first 
      value: option II
    - name: select-option_III
      type: equal 
      field: first 
      value: option III