Form Configuration

This section describes the configuration of the form (formConfig). The configuration is defined in JSON format and contains the following elements.

Minimum valid formConfig:

{
  "metaData": {
    "id": 0,
    "version": 0
  },
  "configuration": {
  },
  "components": [
    {
      "type": "button"
    }
  ]
}

Schema $schema

The schema can optionally be defined via the $schema attribute. The renderer always uses a JSON schema to validate the formConfig.

schema
{
  "$schema": "https://forms.virtimo.net/5.0.x/schema.json"
}

Metadata metaData

The metaData attribute must be specified. The following values are required:

id (string|number)

Unique ID for this form. All forms with this ID and version should have an identical formConfig , with the exception of the state attribute.

version (number)

Version of the form. Can be used to indicate that this is a form of a specific version.

The following values are optional. However, it is recommended to provide as much metadata as possible.

name (string)

Descriptive name of the form

creationDate (string - date in ISO 8601 format)

Date the form was created

author (string)

Author of the form

metaData
{
  "metaData": {
    "id": "abcdf",
    "name": "The best form ever",
    "version": 4711,
    "author": "Virtimo AG",
    "creationDate": "2021-03-05T12:00:00+0200"
  },
}

Configuration configuration

submitUrl (string)

This URL is used to submit the form.
If Flow is used to connect to Process Engines, a URL can be copied directly from the Flow Manager and pasted here.

validationUrl (string)

This URL is used for server-side validation.

stateUrl (string)

Optional URL from which JSON data is loaded. This data is provided to the form via the state.

validateOnChange (boolean)

If true, then a change to the user’s data triggers the validate when the user switches focus between the Components and has made a change. Errors triggered by this are displayed only for the component the user is editing. For example, if the user enters text and then clicks on another field, an error is displayed only for the field where the text was entered, provided the entry does not comply with the validation rules. Default: false

validateOnBlur (boolean)

If true, then the validate is triggered when the user shifts focus between the Components. The difference from validateOnChange is that the user does not have to have changed the data to trigger the validation. Default: false

defaultLanguage (string)

The default language to use, unless another setting takes precedence. The language set by the form itself in the state and the language set via URL Parameters take precedence

Configuration styles

The ` styles ` object allows for fine-tuning the visual appearance. CSS variables, additional CSS rules, and external stylesheets are supported.

variables (object)

The basic configuration is done using CSS variables. Many variables are linked hierarchically. Thus, values such as background-color automatically adapt to dark-mode unless they are manually overridden. It is often sufficient to define only the base-color, since the system automatically calculates all derived nuances (brightness, contrast, focus).

Basic Configuration

These variables define the visual identity of the application and are used in almost all components.

Variable Description

dark-mode (boolean)

Enables the dark color scheme. When set to true, backgrounds are displayed in dark colors and text in light colors.

base-color (CSS color string)

The primary color of the application.

base-foreground-color (CSS color string)

The contrast color for base-color. It is used for text that appears directly on top of the primary color (e.g., in containers).

base-pressed-color (CSS color string)

Visualizes interaction; displayed when clicking or pressing controls.

highlight-color (CSS color string)

Accent color for subordinate elements such as Labels or decorative icons.

Status Colors

Status colors provide users with immediate visual feedback regarding the success or failure of actions.

Variable Purpose

confirm-color (CSS color string)

Signal color for successful actions and positive confirmations (see dialog).

alert-color (CSS color string)

Highlight color for error messages and warnings (see validate and dialog).

disabled-color (CSS color string)

Identifies controls that are currently not interactive (see disabled).

Layout Colors

These variables define the basic structure of the user interface. Adjustments are usually only necessary for specific UI design requirements.

Variable Purpose

background-color (CSS color string)

The main background color of the application interface.

selected-background-color (CSS color string)

Highlights actively selected elements, such as selected rows in a table.

hovered-background-color (CSS color string)

Provides visual cues when hovering over elements, such as in tables.

divider-color / reverse-color (CSS color string)

Controls the color of separator lines and borders between UI areas.

color (CSS color string)

The default text color for all text in the application.
css (string)

Contains additional CSS rules. These rules are applied in the browser. For basic theming settings, such as the base color, variables should be used instead of CSS rules. While it is possible to use CSS, it is more prone to errors. The reason for this is that the underlying framework has a nested structure, making it difficult to target the correct element with the appropriate CSS specificity.

cssURL (string/array)

A URL to an external CSS stylesheet. The linked stylesheet is then loaded by the browser. To load multiple CSS files, the URLs can be specified in an array. Reloading causes a noticeable delay before the CSS is applied. It is therefore not recommended to adjust settings such as the background color via the cssURL. For the CSS itself, there are no significant differences between specifying it directly via the css configuration or via an external stylesheet.

Example:
{
  "configuration": {
    "styles": {
      "variables": {
        "dark-mode": true,
        "color": "rgb(186, 230, 243)",
        "base-color": "rgb(0, 66, 153)",
        "background-color": "rgb(165, 165, 165)"
      },
      "css": ".textfield .value { font-size: 20px }",
      "cssURL": "https://foo.bar/css"
    }
  }
}

Form Components components

A form consists of at least one component and is typically a composition of multiple components.

The Container and Field Container components can contain additional components and be nested as desired.

The Button component can be used to trigger user interactions such as validation, submit, and reset .

State state

Every form has a state. This can contain various data related to features such as multilingual support or validation. The most common use is binding values to components. Once a connection to the state has been established via binding, the state is also updated when changes are made to the components.

Form Data data

The data section in the state is intended for placing your own information, such as form data.

Data Schema dataSchema

The dataSchema can contain a valid JSON schema and is used for client-side validation. The stored schema is applied to the state.

Keywords:
Press Esc to exit full screen
Modal image placeholder
Press Esc to exit full screen