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.
{
"label": {
"LANGUAGE-1": "String in language 1",
"LANGUAGE-2": "String in language 2",
"LANGUAGE-n": "String in language n"
}
}
{
"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) |
{
"icon": "font-awesome-css-class"
}
{
"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.
{
"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.
{
"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.
{
"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.
{
"$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 |
-
validate: die Validierung des Formulars wird ausgelöst.
{
"components": {
{
"type": "textfield",
"label": "Text field",
"onChange": {
"action": "getFormState",
"data": {
"stateUrl": "http://localhost:3000/loadState/addressDirectory"
}
}
}
}
}
{
"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
oderfailure
Im Fall eines Fehler sollen weitere Attribute definiert werden, um dem Nutzer auf den Fehler hinzuweisen. |
-
action
: es muss den WertsetFormState
enthalten, damit das Formular aktualisiert wird. -
data.state
: enthält die neue States.
{
"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.