Smartforms

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:

NameDefault valueDescription
numberingnoneSets 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).
startingNumber1The number at which numbering starts.
numberPrefix (single space)A prefix for numbering.
numberSuffixA 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:

NameMandatoryDefault valueDescription
nameyesThe name of the segment. This name is used in the segment prop of the SmartForm component.
titleyesA title for this segment.
fieldsyesThe fields for this segment.
numberingnononeSets 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).
startingNumberno1The number at which numbering starts.
numberPrefixno (single space)A prefix for numbering.
numberSuffixnoA 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

NameMandatoryDefault valueDescription
nameyesUsed in condition references and will be the key JSON data resulting from filling the form.
typenotextThe data type for the form field. Possible values are described below.
descriptionnoA descriptive text that is displayed above the rendered field.
valuenoThe 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.
labelyesThe 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 ., :, !, ?.
requirednoboolean or conditionIf 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.
disablednoboolean or conditionIf 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.
visiblenoboolean or conditionIf 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.
tooltipnoIf specified, a tooltip will be rendered near the form field with the text set in this property.
tooltipPositionnoDenotes the position of the tooltip relative to the field. Allowed values: top, bottom, left, right. Defaults to bottom.
helpnoA help text. If specified, a small icon is rendered near the field which, when hovered, will display the text.
numberingnononeSets 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.
startingNumberno1The number at which numbering starts. When not specified, the value of the parent (fieldset, segment, form) is used.
numberPrefixnoA prefix for numbering. When not specified, the value of the parent (fieldset, segment, form) is used.
numberSuffixno (single space)A suffix for numbering. When not specified, the value of the parent (fieldset, segment, form) is used.
placeholdernoThe placeholder value (input field hint) for this field. Note that not every field type will display a placeholder.

Supported field types

Supported field types:

NameDescription
textPlain text. When unspecified, the field type defaults to text.
dateDate field.
numberNumeric values.
selectA dropdown field.
checkboxCheck box for true/false values.
headerRenders a simple HTML header. The value rendered is in label property.
fieldset
fileA file upload field. This field type is currently not tested.
textareaPlain text with room for multiple lines of input.
hiddenA hidden field. Useful for custom components that have to produce a value.
info
label
local-onlyA hidden field whose data will not be sent to the back-end. Useful in custom fields that need to temporarily store data.
radio
customA 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

NameMandatoryTypeDescription
rowsnonumberThe height (in rows) of this textarea field.
colsnonumberThe 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
NameMandatoryTypeDescription
valuenonumberThe value for this number field.
minnonumberThe minimal value for this number field.
maxnonumberThe maximum value for this number field.
stepnonumberThe 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

NameMandatoryTypeDescription
valuenostringThe value for this select field. May be empty.
itemsyesarray of select field item items (see below)The items which can be selected in this select field.
Select field item
NameMandatoryTypeDescription
labelnostringThe label of the select field item. When not specified, the value attribute is used instead.
valueyesnumber or stringThe 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

NameMandatoryTypeDescription
valuenodateThe value for this date field.
minYearnonumberThe lowest year that can be picked. Defaults to 2000.
maxYearnonumberThe 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

NameMandatoryTypeDescription
subTypenostringThe 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)yesarray of radio valueThe values that correspond to the radio field options. This field is mandatory for a standard radio field.
values (for smiley radio field)noarray of stringThe values that correspond to the smiley options. This property is optional but, if specified, must have exactly 5 string values.
Radio field value
NameMandatoryTypeDescription
labelyesstringThe display label of the radio field option.
valueyesstringThe 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

NameMandatoryTypeDescription
fieldsyesList of fieldThe 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

NameMandatoryTypeDescription
severitynostringDenotes 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

NameMandatoryTypeDescription
textyesstringThe static text to render. If this attribute is not specified or is left empty, the value of attribute html will be used instead
htmlyesstringThe 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:

NameReferences fieldDescription
valueSetyesChecks if the target field has a value set.
valueEmptyyesChecks if the target field has no value set. Inverse of valueSet.
allnoChecks if all supplied sub conditions are true. Sub conditions are given as an array of Condition (see this table).
anynoChecks if at least one supplied sub conditions is true. Sub conditions are given as an array of Condition (see this table).
isTrueyesChecks if the target field has a true value.
isFalseyesChecks if the target field has a false value.
greaterThanyesChecks if the target field has a value that is greater than that of the supplied value attribute.
greaterThanOrEqualyesChecks if the target field has a value that is greater than or equal to that of the supplied value attribute.
equalyesChecks if the target field has a value that is equal to that of the supplied value attribute. Supports both text and numbers.
lessThanyesChecks if the target field has a value that is less than that of the supplied value attribute.
lessThanOrEqualyesChecks 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:

NameMandatoryTypeDescription
fieldyesstringThe 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