Advanced Form
The advanced form was introduced to provide more flexibility when building compilations used to capture user input. It is based on the react-jsonschema-form library.
The advanced form offers many features that are not explained in detail here but are described on the library documentation pages. The live playground is also a very useful resource to interactively experiment with the various form options. Additionally, also have a look at the JSON Schema online documentation.
Model
{
"type": "advancedform",
"data": {}, // form field data object
"schema": {}, // Define the structure of the form data
"uischema": {}, // Define which input control to use when editing a field
"formOptions": {} // Define field specific actions and styling
}
Data
Refer to the generic widget page for a description of the general principles governing the treatment of data retrieved from a dataSource
The advanced form data
element is an object with structure that matches the schema
definition. It can be a flat set of key-value pairs but may also contain nested complex elements. For example:
{
"house_address": {
"street": "7 Church Street",
"city": "Digby"
},
"firstName": "Joe",
"lastName": "Bloggs",
"age": 27,
"telephone": "555 123 456"
}
Schema
The schema element serves to define the structure of the form data.
{
"type": "object",
"definitions": {},
"dependencies": {},
"description": "Form description",
"title": "Form tile",
"required": [],
"properties": {}
}
Field | Description |
---|---|
|
The definitions property can be used to declare one or more named composite object types which are referenced when defining Note: If a particular object field only appears once in the form, the nested structure can be declared in situ by directly providing the object |
|
Optional description, shown after the title. |
|
Used to define inter-field dependencies. |
|
Contains the declarations for the named form fields. They are always nested in schema elements of type "object". Refer to the properties section below for more detail. |
|
Render all the fields in the form read-only. Individual fields can be be made |
|
List of required fields which must have a value before the form can be submitted. Required fields without appropriate values will be shown with a red border when a submit is attempted. The entries in the list refer to fields at the current object level. If the form contains nested fields, such as street and city in the example above, and these are |
|
Optional form title shown at the top of the form. |
|
Defines the top level type of form data and needs to be of set to object |
Properties
The properties
element, inside the schema
section, is used to declare named fields shown on the form and save in the data. At the schema
level it defines the root data properties, which may in turn be complex objects containing their own properties
.
Each property needs a type
and may be further qualified using a number of available attributes, some of which are highlighted in the table below:
Field | Description |
---|---|
|
These properties allow different elements of a schema to be selected from an array of possibilities providing a means to dynamically control which fields ultimately appear in the data. When using |
|
Optional default value to assign if none is provided. |
|
The definitions property can be used to declare one or more named composite object "types". This is particularly useful when multiple fields in the form have the same object structure. |
|
Optional field description, shown after the title. |
|
Used to define inter-field dependencies. |
|
Enumeration used to define selectable options for a field. Note: When using enum fields be sure to select the appropriate |
|
Custom labels used to provide readable names for numeric enum fields. |
|
Defines the type of elements in array fields. This can be a simple type such as |
|
Named properties of the root or nested form elements of type "object". |
|
The field |
|
Defines the type of the enclosing element. The root element must be of type object since it contains all the form fields. Individual form fields can have any of the following types:
The field type can also be an array of two elements. One being the base type, the other "null" if the field in question is nullable. (For example “type”: ["integer", "null"]). Since a null cannot be entered, the field default would also need to be set to |
|
Apply this property to array type fields to ensure that a specific entry can only be selected once. |
Schema Examples
Definition and reference
In this example a number of schema options are shown. Note the use of definitions
to define the address object with two fields and its use in the house_address field by referring to it with a $ref
path.
{
"type": "object",
"required": [
"firstName",
"lastName",
"age"
],
"definitions": {
"address": {
"type": "object",
"properties": {
"street": {
"type": "string",
"title": "Street"
},
"city": {
"type": "string",
"title": "City"
}
},
"required": [
"street",
"city"
]
}
},
"properties": {
"firstName": {
"type": "string",
"title": "First name"
},
"lastName": {
"type": "string",
"title": "Last name"
},
"age": {
"type": "number",
"title": "Age",
"minimum": 18,
"maximum": 67
},
"birth_month": {
"type": "integer",
"title": "Month of Birth",
"enum": [1,2,3,4,5,6,7,8,9,10,11,12],
"enumNames": [ "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"
]
},
"telephone": {
"type": "string",
"title": "Telephone",
"minLength": 10
},
"house_address": {
"type": "object",
"title": "House Address",
"$ref": "#/definitions/address"
},
"email": {
"type": "string",
"title": "Email",
"format": "email"
}
}
}
Composite array values
In this schema, the input field, called tuples, is an array containing objects with a name and a value declared directly in the property, rather than using a definition and reference as in the example above:
{
"type": "object",
"properties": {
"tuples": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "number",
"enum": [ 1, 2, 3, 4 ]
}
}
}
}
}
}
Refer to the uiSchema
example to see how to set the input controls to use for each of the fields.
Schema validation properties
The following schema validation properties are provided in the schema
section of the form. Also refer to the uischema
for additional validation options.
Field | Description |
---|---|
|
Validate number to be strictly larger than or less than the stated minimum or maximum
|
|
|
|
Enable validation on the allowed values of
|
|
Set limits on the number of elements allowed in an array field. |
|
Set limits on the allowed length of a string property |
|
Constrain the numeric field value to be a multiple of the
|
|
Validation regular expression to applied to string fields. Patten validation is only done on fields which contain data. This implies that to enforce patterns which require the text to contain a minimum number of characters, the field must also be |
UI Schema
The UI Schema is used to manage the appearance of the form fields and specify which controls to use to edit them. It is recommended that a ui:widget
be assigned to all form fields to ensure the edit controls used adhere to the overall styling of the WebStudio compilation and the selected theme.
The uiSchema
property contains elements for all form-fields requiring configuration to be applied, the model for which looks something like this:
{
"ui:order" : [] // Optional array used to set the display order of the form fields
"<field-name>": { // Entry for each field requiring ui-configuration
"<ui:xxx>" : "value" // See table below for available options
"<nested-field-name>": {
// configuration detail for fields in nested objects.
}
}
}
The angle brackets in the above fragment are used to indicate placeholders for implementation specific content.
Field | Description | |
---|---|---|
|
String field containing the names of one or more style classes to assign to the field. Refer to |
|
|
Alternative / override field description. This one takes precedence over the |
|
|
Set to true to disable the field and prevent the content from being selected. This setting on the face of it does the same as |
|
|
This array property can be used to disable one or more options from an enum list. For example:
|
|
|
Display an additional help string after the field input control. |
|
|
This is a composite property with the following fields: |
|
|
when set to true, radio buttons and check-boxes can be shown in-line rather than on separate lines. For example, using an array field to allow users to select multiple options, the following setting could be used:
|
|
|
Note: Not all the options from the underlying library have been fully integrated with WebStudio yet. These will be documented as they are introduced.
|
|
|
Setting the |
|
|
Place-holder text shown in the input box to provide users with a hints of the expected content. |
|
|
Used with a "textarea" |
|
|
This is the same as the placeholder in the options field. |
|
|
When set to true, the field value cannot be edited but is still selectable and can be copied to the clipboard. |
|
|
Overrides the field title provided in the |
|
|
This property is used to select the specific widget to use as the input control for the field. Available options are:
|
uiSchema examples
Nested Fields:
Referring to the "Definition and Reference" example above, the uiSchema
to set the address input controls for the street
to a text-box and the city
to a regular input would look something like this.
{
"house_address": {
"street": {
"ui:widget": "textarea"
},
"city": {
"ui:widget": "text" // Not really needed since string fields use this widget by default
}
}
}
The outer object name used is that of the containing field "house_address", rather then the type "address"
Nested fields in an array:
When the fields are contained in an array as is the case for the second schema example and require specific ui:widget
specs, an items
element needs to be added to the specification as shown:
{
"tuples": {
"items": {
"name": {
"ui:widget": "text"
},
"value": {
"ui:widget": "select"
}
}
}
}
Form Option
The form options provide further customization features that are specific to WebStudio. The formOptions
property has the following structure:
{
"formOptions" : {
"entryOptions": {
"<field-name>" : {
"actions": { }
}
},
"styleByClassName": {
"<custom-class-name>" : { }
}
}
}
Field | Description |
---|---|
|
Action pipelines can be triggered on changes to individual fields. To do so, add the field-name as a key under the
The actions available at field level are: Field level actions for nested entries can be declared by providing the dot-notation path. Consider a form with the following schema:
To define an action pipeline to trigger when
|
|
This property is used to add custom styling to form fields. Let’s say for some fields in the form we want to use a different font. The style can be declared as follows:
|
|
Validation error can be shown directly as annotations in the form by setting this property to true, or suppressed entirely by setting it false |
Options
Set widget options.
{
"options": {
"showRefreshButton": true,
"showToolbar": false,
"refreshInterval": 10
}
}
name | description |
---|---|
|
Set this to false to hide the refresh button. By default the refresh button is visible. |
|
Use to hide the complete toolbar. |
|
Refresh with an interval in seconds. |
Actions
The Advanced Form supports a number of action hooks in addition to the default lifecycle ones, most of which can be used at form and field level by defining entryOptions
as described above. The exceptions are onSubmit
and onValidationError
, which are not triggered separately for each field.
The Advanced Form actions are:
-
onBlur : This event fires whenever a field loses input focus.
-
onChange : Triggers on every input change.
-
onChanged : The action only triggers if the content of the field, when it loses input focus, is different from that when it received focus.
-
onFocus : Triggers when a field receives input focus.
The message payload for these actions contains the name of the affected field expressed, in dot-notation if it is nested, and optionally the current value. The
value
is omitted if the field is blank. For example:{ "payload": { "name": "nested.field1", "value": "some text" } }
-
onSubmit : Gets called when the form submit button is pressed. The submit will not fire if there are validation error on the page.
When the form is valid, the message payload will be the form data object. Only fields containing values will be present in the output.
-
onValidationError : Triggers when the form is submitted but there are validation errors.
The message payload in this case is an array of error messages for all invalid fields.