Skip to main content

Form Template Basic Fields

The basic fields are the foundation of any template: whether is a text field to write a component name, or a checkbox to indicate the presence of sensitive information, basic fields provide the easiest way to ask the user information but with the ability to be flexible enough for the different constraints that a form may have.

All examples shown here are taken from the accompanying basic_fields.yaml template file, which you can see live by following the steps explained here.

Text fields​

Text fields, also called string fields, provide the user the possibility to write text on a provided textbox. The template creator can customize these fields in order to add validations, style, or to constrain the options that the user can write or select.

You can define a string field like this:

basicStringField:
  title: Basic String Field
  type: string

Basic string field

As you can see, a text field is simply the base of any field without any extra parameters.

Date & Time fields​

You can also set up the string fields to act as date and date-time pickers. The stored value will be an ISO8601 date or date-time string.

dateTimeField:
  title: Date-time
  type: string
  "format": "date-time"

date_time_field.png

dateField:
  title: Date
  type: string
  "format": "date"

date_field.png

Constraining and validating the input​

From the basic text field, you can start adding constraints, like changing the type to number in order to constraint the input to only accept integers. By adding other parameters to the field, it is possible to add extra constraints, like the ones shown below.

For other constraints, check the Witboost documentation and the react-json schema form documentation.

Input length​

You can constrain a string length minimum and maximum. (Here we also show how to set the default value for any field):

defaultStringField:
  title: Basic String Field + Default + Max Length
  type: string
  default: Default value here
  ui:options:
    minLength: 3
    maxLength: 10

maxLengthField.png

Integer ranges​

It is possible to constraint a number input to set minimum and/or maximum acceptable values. These values are inclusive.

constrainedNumberField:
  title: Number field with constraint 0 <= x <= 10
  type: number
  minimum: 0
  maximum: 10

constrained_number_field.png

Closed list of values​

Instead of letting the user write the value, you can provide a list of values (enum) that will be rendered as a select widget. You can either set the labels equal to the values, or decouple the two of them.

enumField:
  title: Closed list field
  type: string
  enum:
    - Option 1
    - Option 2
    - Option 3
enumNamesField:
  title: Closed list field with underlying values
  type: number
  description: You can decouple the label and the actual value saved on the form
  enum:
    - 1
    - 2
    - 3
  enumNames:
    - Option 1
    - Option 2
    - Option 3

string_enums.png

Email validation​

Validates that the user input is a correctly formatted email.

emailStringField:
  title: String field with email validation
  type: string
  format: email

email_validation.png

RegEx validation​

Validates the user input using a regular expression. This is the first instance of a Witboost Picker, a special kind of field with extra features. You can set the regular expression, the error message to be shown, and any RegEx flags like global g, case-insensitive i, etc.

regexPicker:
  title: String field with RegEx validation (RegexPicker)
  type: string
  ui:field: RegexPicker
  description: Sets a regular expression and validates the input when proceeding to the next section
  # This field can contain the placeholder for the text area in the regex picker
  ui:placeholder: ''
  validation:
    errorMessage: "Error message: This field accepts only the best food"
    regularExpression: ^pizza$
    flags: i

regex_validation.png

URL validation​

Validates that the user input is a correctly formatted URL.

urlPicker:
  title: String field with URL validation (UrlPicker)
  type: string
  description: Accepts only inputs which are valid URLs
  ui:field: UrlPicker

url_validation.png

Filesystem path validation​

Validates that the user input is a correctly formatted path from a Linux/macOS or Windows filesystem.

fileSystemPicker:
  title: String field with filesystem path validation (PathPicker)
  type: string
  description: Accepts only inputs with are valid filesystem paths, matching Linux/macOS and Windows paths
  ui:field: PathPicker

path_validation.png

Styling​

The following styling tips are also applicable to most of the more complex fields, like the Witboost Pickers.

Disabled field​

The field will be shown to the user, but it cannot be edited. It should include a default value which will effectively be the value of the field.

disabledField:
  title: Disabled field
  type: string
  default: Non-editable value
  ui:disabled: true

disabled_field.png

Hidden field​

You can hide any type of field, not only basic fields, and its value will still be saved on the form.

hiddenField:
  title: Hidden field
  type: string
  default: I am hidden!
  ui:widget: hidden

Required field​

You can set a field as required, by adding it to the required property at the top object level:

...
required:
  - requiredStringField
properties:
  requiredStringField:
    title: Required field
    type: string
    description: This field will prevent you from going to the next section until filled
...

required_field.png

Multiline​

You can convert a field into a text area by setting ui:options.multiline to true and specifying the minimum amount of rows to be displayed.

multilineField:
  title: Multiline field
  type: string
  description: Text area field
  ui:options:
    multiline: true
    rows: 5

multiline_field.png

CSS styling​

Some fields allow to pass CSS properties to the field in order to further customize the picker. All the properties inside ui:style will override the field style ones.

codeStyleField:
  title: Code-like style field
  type: string
  description: Usage of ui:style to give a different look to the field
  ui:options:
    multiline: true
    rows: 5
  ui:style:
    font-family: Consolas
    color: "#111"

css_styled_field.png

Boolean fields​

You can create boolean fields which will store a true or false value. They come in two flavors: checkboxes/radio buttons and select widgets.

warning

If a default is not given, the field will store by default a null value, not a false value.

  • Checkboxes/Radio buttons

    checkboxField:
      title: Checkbox field
      description: Description is not shown
      type: boolean
    radioField:
      title: Radio field
      description: If no default is set, the field will be null unless user checks and unchecks it to make it `false`
      type: boolean
      ui:widget: radio

    boolean_check_radio.png

  • Select

    selectField:
      title: Yes/No field
      type: boolean
      ui:widget: select
    selectWithNamesField:
      title: Custom names boolean select field
      type: boolean
      ui:widget: select
      oneOf:
        - const: true
          title: "This is the true option"
        - const: false
          title: "This is the false option"

    boolean_select_field.png

info

As of Witboost 1.5.1, we are aware that the boolean select with custom names is currently presenting inconsistent behaviour. An alternative in the meantime would be using the string field with a closed list of values.

Array fields​

All the template fields can be rendered as an ordered list by using the array type. By defining a field as an array, you can set the children schema as any kind of field shown in the Templates Gallery.

stringArray:
  type: array
  title: Free-form string array
  items:
    title: Basic String Field
    type: string

basic_array.png

You can add new items, delete them and change the order between them using the buttons at the side of each item.

There is a special case of array field which allows to choose several options from a closed list of values and that is rendered in a more natural way.

enumStringArray:
  type: array
  title: Enum string array
  uniqueItems: true
  items:
    title: Basic String Field
    type: string
    enum:
      - "Option A"
      - "Option B"
      - "Option C"

enum_string_array.png

Constraining and validating the input​

Array size​

You can constrain the array minimum and maximum size.

constrainedArray:
  type: array
  title: Constrained string array
  minItems: 2
  maxItems: 10
  items:
    title: Basic String Field
    type: string

array_size.png

Object fields​

You can group different fields into objects in order to group common information, to add subsections with their own titles and description, to make templates with a richer style and structure, or to enable the DescriptorPicker functionality to retrieve local form values.

Object descriptions, as well as step descriptions, support Markdown syntax to enrich the form visuals. For more information, check the Layouts examples.

numberFields:
  title: Number fields
  type: object
  description: Number fields are a way to enforce an input to accept only integer values 
  required:
    - numberField
  properties:
    numberField:
      title: Integer field
      type: number
    constrainedNumberField:
      title: Number field with constraint 0 <= x <= 10
      type: number
      minimum: 0
      maximum: 10

object_field.png

You can also set required fields on objects, and you must define them at this level if you want to render them mandatory. If you set on the object root level a field as required, but it is contained in an object, it will not be enforced by the platform.

To understand how to add style to these objects in order to make better templates, check the Layouts examples.

To understand how to leverage objects to retrieve information from other parts of the form using the DescriptorPicker, check the Dynamic Select examples.