docs in sub package
This commit is contained in:
120
docs/md/projektkonfig/collections/fields.md
Normal file
120
docs/md/projektkonfig/collections/fields.md
Normal file
@@ -0,0 +1,120 @@
|
||||
# fields
|
||||
|
||||
Felder im _tibi-server_ müssen einen bestimmten Datentyp haben. Über den _tibi-admin_ können die Felder über Widgets in unterschiedlichen Ausprägungen dargestellt werden (view-Widgets), bzw. dem Benutzer eine Eingabe abverlangen (input-Widgets).
|
||||
|
||||
Es gibt grundlegende Angaben, die jedes Feld haben muss um vom _tibi-server_ akzeptiert zu werden. Darüber hinaus kann auch jedes Feld ein `meta` Objekt haben, was dem _tibi-admin_ mitteilt, wie er dieses Feld für Ausgabe und Eingabe behandel soll.
|
||||
|
||||
Zunächst folgt der grundlegende Aufbau des Feld-Objektes:
|
||||
|
||||
!!!include(../api/collections/fields/date.yml)!!!
|
||||
|
||||
## validator Objekt
|
||||
|
||||
<video width="100%" controls muted autoplay loop>
|
||||
<source src="validator.webm" type="video/webm">
|
||||
</video>
|
||||
|
||||
Wie im Beispiel von **fields/date.yml** unter `validator` zu sehen ist, wird dort ein Datum nach dem aktuellen erwartet. Wie der Validator sich auf die UI auswirkt, ist im obigen Video zu sehen.
|
||||
|
||||
Das `validator` Objekt wird _tibi-server_ seitig genutzt um die Daten zu validieren. Da das `validator` Objekt dem _tibi-admin_ ebenso zur Verfügung steht, kann vorab eine client-seitige Validierung zusätzlich durchgeführt werden.
|
||||
|
||||
Attribute des Objektes:
|
||||
|
||||
| Attribut | Datentyp | Beschreibung |
|
||||
| ----------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `required` | boolean | wenn `true`, dann ist zwingend eine Eingabe zu diesem Feld nötig |
|
||||
| `allowZero` | boolean | in Kombination mit `required: true`, wenn `true`, dann ist der jeweilige "Null"-Wert des Datentyps erlaubt<br><br>z.B. `type: string` erlaubt den leeren String und `type: number` erlaubt `0` |
|
||||
| `eval` | string | Javascript-Code der zu true evaluieren muss um den Wert des Feldes als gültig zu definieren |
|
||||
|
||||
### eval-Attribut
|
||||
|
||||
Der Javascript-Code in diesem Attribut kann folgende Rückgabe-Werte haben:
|
||||
|
||||
| Wert | Bedeutung |
|
||||
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `true` | Der Wert des Feldes ist gültig |
|
||||
| `false` | Der Wert des Feldes ist ungültig |
|
||||
| `"Text"` | Wird ein String zurückgegeben ist, wird der Wert es Feldes ebenso als ungültig erachtet und der String selbst ist eine benutzerdefinierte Fehlermeldung, die in der Serverantwort gelesen werden kann. |
|
||||
|
||||
Da der `eval` Code serverseitig immer ausgeführt wird und ein Fehlschlag zwangsläufig zum Abbruch der Serveraktion führt, ist es wichtig, dass der [serverseitige Javascript-Kontext](./../../server-javascript-kontext/validator.md) berücksichtigt wird.
|
||||
|
||||
Optional kann der Code auch zusätzlich über eine Lauffähigkeit ohne Fehler (z.B. keine Verwendung nicht vorhandender Kontext-Variablen oder Verwendung von `try ... catch`) im _tibi-admin_ verfügen. Das hat den Vorteil, dass eine Vorab-Validierung stattfindet, bevor der Datensatz an der Server gesendet wird.
|
||||
|
||||
Sollte der `eval` Code im _tibi-admin_ nicht lauffähig sein (nicht abgefangene Exception), wird der Validator clientseitig ingoriert und nur die serverseitige Prüfung beeinflusst die Aktion.
|
||||
|
||||
#### siehe
|
||||
|
||||
- [Server Javascript Kontext](./../../server-javascript-kontext/allgemeines.md)
|
||||
- [Validator Javascript Kontext](./../../server-javascript-kontext/validator.md)
|
||||
|
||||
## dependsOn
|
||||
|
||||
<video width="100%" controls muted autoplay loop>
|
||||
<source src="dependsOn.webm" type="video/webm">
|
||||
</video>
|
||||
|
||||
Obige Darstellung wie im Video wird beispielsweise durch folgende Feld-Konfiguration erreicht:
|
||||
|
||||
```yaml
|
||||
# in einer Kollektions-Konfiguration
|
||||
fields:
|
||||
- name: type
|
||||
type: string
|
||||
meta:
|
||||
label:
|
||||
de: Typ
|
||||
en: Type
|
||||
widget: select
|
||||
choices:
|
||||
- name:
|
||||
de: Standardseite
|
||||
en: Standard page
|
||||
id: page
|
||||
- name:
|
||||
de: News
|
||||
en: News
|
||||
id: news
|
||||
|
||||
- name: title
|
||||
type: string
|
||||
meta:
|
||||
label:
|
||||
de: Titel
|
||||
en: Title
|
||||
|
||||
- name: date
|
||||
type: date
|
||||
meta:
|
||||
label:
|
||||
de: Titel
|
||||
en: title
|
||||
widget: date
|
||||
defaultValue:
|
||||
eval: new Date()
|
||||
dependsOn:
|
||||
eval: $parent?.type == "news"
|
||||
|
||||
```
|
||||
|
||||
`meta.dependsOn` kann als Objekt mit `eval`-Attribut für Javascript oder als `string` mit dem Feldnamen (Punktschreibweise, z.B. `"additionalData.author"`) angegeben werden.
|
||||
|
||||
Wird der Feldname verwendet wird nur geprüft, ob das Feld belegt ist. TODO
|
||||
|
||||
Die `eval` Variante verwendet als Javascript-Kontext Variablen die auf folgenden Seite beschrieben werden:
|
||||
|
||||
- [Admin Javascript Kontext](./../../admin-javascript-kontext/allgemeines.md)
|
||||
- [collection.meta..eval](./../../admin-javascript-kontext/collection.meta..eval.md)
|
||||
- [field.meta..eval](./../../admin-javascript-kontext/field.meta..eval.md)
|
||||
|
||||
Die Rückgabe des Javascript-Codes beeinflusst die Einblendung des betroffenen Feldes in folgender Weise:
|
||||
|
||||
| Rückgabe | Bedeutung |
|
||||
| -------- | -------------------------- |
|
||||
| `true` | Das Feld wird angezeigt |
|
||||
| `false` | Das Feld wird ausgeblendet |
|
||||
|
||||
## defaultValue
|
||||
|
||||
Für die Vorlegung neu anzulegender Datensätze kann in `field.meta.defaultValue` direkt der Standardwert hinterlegt werden, oder über `field.meta.defaultValue.eval` ein Javascript-Code angegeben werden, der den Wert ermittelt. Die Rückgabe des Javascript-Codes, sowie auch die direkte Vergabe des Wertes muss dem Datentyp des Feldes entsprechen.
|
||||
|
||||
Der Javascript-Kontext ist der gleiche wie bei `field.meta.dependsOn.eval`.
|
||||
Reference in New Issue
Block a user