Formularkonfiguration

Hier wird die Konfiguration des Formular (formConfig) beschrieben. Die Konfiguration wird im JSON Format definiert und enthält folgende Bestandteile.

Minimal gültige formConfig:

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

Schema $schema

Das Schema kann optional über das Attribut $schema definiert werden. Der Renderer verwendet in jedem Fall ein JSON Schema zum Validieren der formConfig.

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

Meta Daten metaData

Das Attribut metaData muss angeben werden. Folgende Werte sind verpflichtend anzugeben:

id (string|number)

Eindeutige ID für dieses Formular. Alle Formulare mit dieser ID und Version sollten mit Ausnahme des state Attributes eine identische formConfig aufweisen.

version (number)

Version des Formulars. Kann genutzt werden, um anzuzeigen, dass es sich um ein Formular in einer bestimmten Version handelt.

Folgende Werte sind optional. Es wird aber empfohlen möglichst viele Metadaten bereitzustellen.

name (string)

Beschreibender Name des Formulars

creationDate (string - Datum im Format ISO 8601)

Datum der Formularerstellung

author (string)

Author des Formulars

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

Konfiguration configuration

submitUrl (string)

Die URL wird für den Submit des Formulars verwendet.
Wenn Flow für die Verbindung zu Process Engines genutzt wird, kann eine Url direkt aus dem Flow-Manager kopiert und hier eingefügt werden.

validationUrl (string)

Die URL wird für die serverseitige Validierung genutzt.

stateUrl (string)

Optionale URL aus der JSON Daten geladen werden. Diese werden dem Formular über den state bereitgestellt.

validateOnChange (boolean)

Wenn true, dann löst eine Änderung von Daten des Anwenders die validate aus, wenn der Anwender den Fokus zwischen den Komponenten wechselt und eine Änderung gemacht hat. Dadurch ausgelöste Fehler werden nur für die vom Anwender bearbeitete Komponente angezeigt. Beispielsweise wenn der Anwender eine Texteingabe macht und dann ein anderes Feld anklickt, wird nur ein Fehler für Feld mit der Texteingabe validiert, sofern die Eingabe nicht den Validierungsregeln entspricht. Default: false

validateOnBlur (boolean)

Wenn true, dann wird die validate ausgelöst, wenn der Anwender den Fokus zwischen den Komponenten wechselt. Der Unterschied zu validateOnChange ist, dass der Anwender die Daten nicht geändert haben muss, um die Validierung auszulösen. Default: false

defaultLanguage (string)

Zu verwendende standard Sprache, sofern keine andere Einstellung höhere Priorität hat. Höhere Priorität hat die Sprache, die vom Formular selbst im state gesetzt wird und die Sprache, die über Url-Parameter gesetzt wird

Konfiguration styles

Das Objekt styles ermöglicht die Feinsteuerung des visuellen Erscheinungsbilds. Unterstützt werden CSS-Variablen, zusätzliche CSS-Regeln und externe Stylesheets.

variables (object)

Die grundlegende Konfiguration erfolgt über CSS-Variablen. Viele Variablen sind hierarchisch verknüpft. So passen sich Werte wie background-color automatisch an den dark-mode an, sofern sie nicht manuell überschrieben werden. Oft genügt es, nur die base-color zu definieren, da das System alle davon abgeleiteten Nuancen (Helligkeit, Kontrast, Fokus) automatisch berechnet.

Basiskonfiguration

Diese Variablen definieren die visuelle Identität der Anwendung und finden in fast allen Komponenten Verwendung.

Variable Beschreibung

dark-mode (boolean)

Aktiviert das dunkle Farbschema. Bei true werden Hintergründe dunkel und Texte hell dargestellt.

base-color (CSS-Farb-String)

Die primäre Farbe der Anwendung.

base-foreground-color (CSS-Farb-String)

Die Kontrastfarbe zur base-color. Sie wird für Texte verwendet, die direkt auf der Primärfarbe liegen (z. B. in Containern).

base-pressed-color (CSS-Farb-String)

Visualisiert Interaktion; wird beim Klicken oder Drücken von Bedienelementen angezeigt.

highlight-color (CSS-Farb-String)

Akzentfarbe für untergeordnete Elemente wie Labels oder dekorative Icons.

Statusfarben

Statusfarben geben dem Nutzer unmittelbares visuelles Feedback über den Erfolg oder Misserfolg von Aktionen.

Variable Verwendungszweck

confirm-color (CSS-Farb-String)

Signalfarbe für erfolgreiche Aktionen und positive Bestätigungen (siehe dialog).

alert-color (CSS-Farb-String)

Signalfarbe für Fehlermeldungen und Warnungen (siehe validate und dialog).

disabled-color (CSS-Farb-String)

Kennzeichnet Bedienelemente, die aktuell nicht interaktiv sind (siehe disabled).

Layoutfarben

Diese Variablen definieren das Grundgerüst der Oberfläche. Eine Anpassung ist meist nur bei speziellen Anforderungen an das UI-Design notwendig.

Variable Verwendungszweck

background-color (CSS-Farb-String)

Die Haupt-Hintergrundfarbe der Anwendungsoberfläche.

selected-background-color (CSS-Farb-String)

Hebt aktiv selektierte Elemente hervor, z. B. markierte Zeilen in einer Tabelle.

hovered-background-color (CSS-Farb-String)

Bietet visuelle Orientierung beim Hovern von Elementen, z. B. in Tabellen.

divider-color / reverse-color (CSS-Farb-String)

Steuert die Farbe von Trennlinien und Abgrenzungen zwischen UI-Bereichen.

color (CSS-Farb-String)

Die Standard-Schriftfarbe für alle Texte der Anwendung.
css (string)

Enthält zusätzliche CSS-Regeln. Diese Regeln werden im Browser eingesetzt. Für grundsätzliche Theming Einstellungen wie die Grundfarbe, sollten nicht CSS-Regeln verwendet werden, sondern Variablen. Die Verwendung von CSS ist zwar möglich, aber fehleranfälliger. Grund dafür ist, dass das unterliegende Framework verschachtelt aufgebaut ist und es dadurch nicht immer einfach ist das passende Element anzuvisieren mit der passenden CSS-Spezifität.

cssURL (string/array)

Eine URL zu einem externen CSS-Stylesheet. Das verlinkte Stylesheet wird dann vom Browser nachgeladen. Um mehrere CSS-Dateien zu laden, können die URLs in einem Array angegeben werden. Durch das Nachladen ergibt sich eine sichtbare Verzögerung bis das CSS angewendet wird. Es ist daher nicht zu empfehlen Einstellungen wie die Grundfarbe über die cssURL anzupassen. Für das CSS selbst gibt es keine wesentlichen Unterschiede zwischen der direkten Angabe über die css-Konfiguration oder über ein externes Stylesheet.

Beispiel:
{
  "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"
    }
  }
}

Formular Komponenten components

Ein Formular besteht aus mindestens einer Komponente und ist in der Regel eine Komposition von einer vielzahl von Komponenten.

Die Komponenten Container und Feld Container können weitere Komponenten enthalten und beliebig geschachtelt werden.

Mit der Button Komponente können Benutzerinteraktionen wie Validierung, Submit und Reset ausgelöst werden.

Zustand state

Jedes Forms hat einen state. Dieser kann verschiedene Daten enthalten, die mit diversen Funktionen wie Mehrsprachigkeit oder Validierung zusammen hängen. Die häufigste Verwendung ist das Binden von Werten an Komponenten. Wenn durch Binding eine Verbindung zum state hergestellt wurde, dann wird der state bei Änderungen der Komponenten ebenfalls verändert.

Formulardaten data

Der data Bereich im state ist für das Platzieren eigener Informationen, wie z.B. Formulardaten, gedacht.

Daten Schema dataSchema

Das dataSchema kann ein gültiges JSON Schema enthalten und wird für die clientseitige Validierung genutzt. Das hinterlegte Schema wird auf den state angewendet.

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