Allgemeine Komponenten Konfiguration

Es gibt Konfigurationen, die für alle Komponenten gelten.

ID id

(string) Identifiziert die Komponente innerhalb des Formulars und darf nur einmal verwendet werden.

Beschriftung label

Die meisten Komponenten bieten die Möglichkeit einer Beschriftung. Die konkrete Darstellungsform hängt von der Komponente ab. Es kann direkt eine String angegeben werden. Für die Verwendung von Mehrsprachigkeit kann ein Objekt angegeben werden, dass für mehrere Sprachen String enthält.

Syntax
{
    "label": {
       "LANGUAGE-1": "String in language 1",
       "LANGUAGE-2": "String in language 2",
       "LANGUAGE-n": "String in language n"
    }
}
Konkretes Beispiel
{
    "label": {
       "de": "Hallo Welt",
       "en": "Hello world"
    }
}

Siehe auch Mehrsprachige Inhalte

Icon icon

Die meisten Komponenten bieten die Möglichkeit zur Anzeige eines Icons. Die konkrete Darstellungsform hängt von der Komponente ab. Die Icons stammen von der Bibliothek Font Awesome Pro. Es kann direkt eine Font-Awesome CSS-Klasse als String angegeben werden.

Der Renderer unterstützt alle Font-Awesome-Icons der Version 5.15.4 (Pro-Variante)
Syntax
{
    "icon": "font-awesome-css-class"
}
Konkretes Beispiel
{
    "icon": "fal fa-fire"
}

Typ type

Jede Komponenten muss einem Typ entsprechen. Diesen können Sie an der jeweiligen Komponente einsehen.

Einschränkung der Benutzung

Mit readOnly, disabled, hidden und required kann die Benutzung von Komponenten für Nutzer verändert werden. Im folgenden werden die einzelnen Möglichkeiten erläutert. Tatsächlich verwendet werden sie zum Beispiel hier.

Nur lesender Zugriff readOnly

Soll ein Anwender auf eine Komponente nur lesend zugreifen, ohne dessen Inhalte zu verändern, dann kann das Attribut readOnly mit dem Wert true gesetzt werden. Hierbei ist zu beachten, dass nur der Zugriff auf Text in einem Feld beschränkt wird. So kann der Anwender den Text von einem textfield nicht verändern, aber den Wert von einer checkbox schon, da es sich in diesem nicht um Text handelt. Data-Binding ist ebenfalls möglich statt direkt true zu setzen.

Beispiel
        {
          "type": "textfield",
          "label": "Read Only Field",
          "value": "readme.only",
          "readOnly": true
        }

Nur lesender Zugriff und visueller Hinweis disabled

Soll ein Anwender auf eine Komponente nur lesend zugreifen, ohne dessen Inhalte zu verändern, dann kann das Attribut disabled mit dem Wert true gesetzt werden. Dies betrifft alle Komponenten. Der Anwender kann keinen Wert eines input fields verändern, wenn es disabled ist. Dieses Attribut hat zusätzlich den Vorteil, dass das Element visuell anders aussieht als Felder, bei denen der Nutzer etwas eingeben kann. Data-Binding ist ebenfalls möglich statt direkt true zu setzen.

Beispiel
        {
          "type": "textfield",
          "label": "Disabled Field",
          "value": "disabled",
          "disabled": true
        }

Verstecktes Element hidden

Soll ein Anwender eine Komponente unter bestimmten Umständen nicht sehen sollen, dann kann das Attribut hidden per Data-Binding gebunden werden. Direkt auf true setzen an der Komponente selbst ohne Data-Binding ist nicht möglich.

Beispiel
        {
          "type": "checkbox",
          "label": "Hide Textfield",
          "value": "/data/checkboxes/one"
        },
        {
          "type": "textfield",
          "label": "Hidden if checkbox",
          "value": "/data/checkboxes/two",
          "hidden": "/data/checkboxes/one"
        }

Notwendige Eingabe required

Soll ein Anwender auf jeden Fall etwas eingeben, dann kann das Attribut required per Data-Binding gebunden werden. Direkt auf true setzen an der Komponente selbst ohne Data-Binding ist nicht möglich.

Beispiel
{
    "$schema": "http://bpc.virtimo.net/forms/1/schema",
    "metaData": {
        "id": 0,
        "version": 0
    },
    "configuration": {},
    "components": [
        {
            "type": "container",
            "label": "Required Example",
            "components": [
                {
                    "type": "textfield",
                    "label": "Required",
                    "required": "/data/one"
                }
            ]
        }
    ],
    "state": {
        "data": {
            "one": true
        }
    }
}

Aktion bei der Wertänderung eines Feldes onChange

Konfiguration des Feldes

Dieser Konfiguration lässt sich nur an Eingabe-Feldern anwenden, beispielsweise Text Field oder Date Field.

Bei der Wertänderungen eines Feldes kann bestimmte Aktion ausgeführt werden.

Es werden folgende Aktionen unterstützt:

  • getFormState: dazu muss noch ein stateUrl gesetzt werden, von welchem die neue States angeboten werden. Das Formular spricht bei Wertänderung die URL an und setzt die zurückgegebenen States in den Feldern ein.

Der stateUrl kann direkt unter der Komponente (siehe Beispiel 1) oder in der Formularkonfiguration (siehe Beispiel 2) gesetzt werden. An der Komponente soll für mögliche Handlung am Server entweder id oder name gesetzt werden.

  • validate: die Validierung des Formulars wird ausgelöst.

Beispiel 1
  {
    "components": {
        {
          "type": "textfield",
          "label": "Text field",
          "onChange": {
            "action": "getFormState",
            "data": {
              "stateUrl": "http://localhost:3000/loadState/addressDirectory"
            }
          }
        }
    }
  }
Beispiel 2
  {
    "components": {
      "type": "textfield",
      "label": "Text field",
      "onChange": {
        "action": "getFormState"
      }
    },
    "configuration": {
      "stateUrl": "http://localhost:3000/loadState/addressDirectory"
    }
  }
        {
          "type": "checkbox",
          "label": "Check validation",
          "onChange": {
            "action": "validate"
          }
        }

Response-Format

Der Server muss die Antwort in dem richtigen Format zurückschicken, damit das Formular aktualisiert werden kann. Die Antwort soll im Form eines JSON-Objektes sein, welches folgende Attribute enthält:

  • result: success oder failure

Im Fall eines Fehler sollen weitere Attribute definiert werden, um dem Nutzer auf den Fehler hinzuweisen.

  • action: es muss den Wert setFormState enthalten, damit das Formular aktualisiert wird.

  • data.state: enthält die neue States.

Beispiele
      {
          "result": "success",
          "action": "setFormState",
          "data": {
              "state": {
                  "address": {
                    "street": "Behrenstraße",
                    "number": 18,
                    "city": "Berlin",
                    "country": "Deutschland"
                  }
              }
          }
      }
      {
          "result": "failure",
          "message": "Fehler im Server"
      }

Responsive Konfiguration responsiveConfiguration

Für Konfigurationen die sich dynamisch an die gegebene Größe oder verwendeten Geräte anpassen siehe Responsive Forms.

Generische Konfiguration configuration

Über das Attribut configuration lassen sich beliebige Parameter an die Komponente übergeben. Diese werden im Renderer bei der Erstellung der Komponenten übergeben und entsprechend interpretiert. So können z.B. nicht direkt Unterstütze Funktionen an den Komponenten gesteuert werden.

Diese Option sollte mit Vorsicht verwendet werden. Eine falsche Konfiguration kann dazu führen, dass das Formular nicht mehr wie erwartet funktioniert.

Diverse Parameter zu Darstellung

Folgende Attribute können genutzt werden, um Einfluss auf die Darstellung der Komponente zu nehmen.

minWidth

Mindestbreite

minHeight

Mindesthöhe

width

Breite

height

Höhe

maxWidth

Maximale Breite

maxHeight

Maximale Höhe

flex

Gibt an wie sich die Komponente in ihrem Container ausbreiten darf. Dafür werden die flex Werte aller Komponenten im Container zueinander ins Verhältnis gesetzt.

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