Form validation

There are 3 types of validations: required, regex matcher, or predicate evaluation.

Required

Required is a first-class property on all form elements. Set it to true and the field is identified as required and automatically validated to ensure it is not blank when submitting a form.

Regex

A regex matcher will test if the user input value matches a regex. If not, the error message is displayed when the user tries to submit the form. The string entered must be a value you can pass into new RegExp() in standard javascript.

Example:

validations:
- regex: "^\\w+$"
  message: Only letters, numbers, and undescore are allowed.

Predicate

A predicate can be used instead of a single regex matcher and allows you to use more advanced logic in order to validate the input based on the values of other fields throughout the form. See Advanced Predicates for more details and examples.

Example:

validations:
- predicate:
  operation: all
  comparators:
  - key: auth.username
    empty: false
  - key: auth.password
    empty: false
  message: Username and Password are both requried if you are authenticating by username.

Advanced Predicates

A predicate can be used instead of a single regex matcher and allows you to use more advanced logic in order to validate the input based on the values of other fields throughout the form.

An example:

validations:
- predicate:
  operation: all
  comparators:
  - key: auth.username
    empty: false
  - key: auth.password
    empty: false
  message: Username and Password are both requried if you are authenticating by username.

Boolean

Permanently set the value to true or false. Useful if you want to permanently disable something (until a later update, for example).

Example: disabled: true

Comparator

A Comparator includes the ability to compare using a regex, equality, or to test if a value is empty.

Examples:

Disable if auth.login is empty/blank.

disabled:
  key: auth.login
  empty: true

Hide unless auth.email is a valid email:

visible:
  key: auth.email
  regex:"/[^@][email protected][^\\.]+\\..{2,}/"

Show when sync.enabled is toggled on:

visible:
  key: sync.enabled
  equals: true

ListComparator

The ListComparator has the same functionality as a Comparator but it is used when comparing to the value of a multi-select, which produces an array of values. Because you need to compare against multiple values, it includes an operation option to allow you to test using and/or/not logic.

Examples:

Assume there is a multi-select option called lists on the sync section.

Disable a control if all sync.lists are prefixed with default_:

disabled:
  key: sync.lists
  operation: all
  regex: "/^default_/"

Show a control if the user included the default list:

visible:
  key: sync.lists
  operation: any
  equals: default

Disable a control unless the user included the default list:

disabled:
  key: sync.lists
  operation: none
  equal: default

Advanced Predicate

For more advanced logic, you can use a predicate to generate a logic tree. This is especially useful when you want to check values in multiple fields.

A Predicate contains an operation (all, any, none) which translates directly to boolean logic (and, or, not) and a list of comparators (Comparator, ListComparator, or another Predicate).

Examples:

Enable the submit button after the user and password fields are both filled in:

disabled:
  operation: all
  comparators:
  - key: auth.user
    empty: false
  - key: auth.password
    empty: false

Show a form if either one or more lists are selected OR the user toggled on the auto option:

visible:
  operation: any
  comparators:
  - key: sync.auto
    equals: true
  - key: sync.lists
    empty: false