| sidebar_position |
|---|
1 |
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, 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
As you can see, a text field is simply the base of any field without any extra parameters.
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"
dateField:
title: Date
type: string
"format": "date"
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.
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
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
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
Validates that the user input is a correctly formatted email.
emailStringField:
title: String field with email validation
type: string
format: email
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
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
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
The following styling tips are also applicable to most of the more complex fields, like the Witboost Pickers.
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
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: hiddenYou 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
...
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
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"
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
-
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"
:::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.
:::
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
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"
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
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
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.