Form validation

There are three types of form validation: required, regular expression (regex) matcher, and predicate evaluation.

Required

Required is a first-class property on all form elements. To mark a field as required, set required to true. Your app then automatically validates the field to ensure it is not blank when users submit your app's settings form. For example:

elements:
- type: text
  key: login
  label: Login
  help: Your login details for SampleIntegration
  required: true

Regex matcher

A regex matcher tests 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 a user enters must be a value you can pass into new RegExp() in standard JavaScript. For example:

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

Predicates

If you want to use logic to validate user input based on values of other fields in the form, use a predicate instead of a single regex matcher. For example:

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

You can also use booleans to permanently set a value to true or false. This is useful if you want to permanently disable something (until a later update, for example, disabled: true).

Advanced predicates

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). See the examples below:

Enable the submit button after the user completes both the user and password fields:

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

Display a form if a user selects one or more lists or if the user toggles the auto option on:

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

Display a message stating both username and password are required if the user tries to submit the form without completing both:

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.

Comparator

A Comparator allows you to compare using a regex, equality, or to test if a value is empty. See the examples below:

Hide unless auth.email is a valid email:

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

Show when sync.enabled is toggled on:

visible:
  key: sync.enabled
  equals: true

Disable if auth.login is empty/blank:

disabled:
  key: auth.login
  empty: true

ListComparator

The ListComparator has the same functionality as a Comparator, but it is used when comparing to the value of a multi-select option, which produces an array of values. Because you need to compare against multiple values, it includes an operation option so you can test using and (all), or (any), or not (none) logic. See the examples below:

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_/"

Display 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