tibi-docs/docs/md/projektkonfig/collections/fields.md

145 lines
7.5 KiB
Markdown
Raw Normal View History

2022-11-19 14:51:34 +01:00
# fields
2023-02-21 15:59:14 +01:00
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).
2022-11-19 14:51:34 +01:00
2023-02-21 15:59:14 +01:00
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.
2022-11-19 14:51:34 +01:00
Zunächst folgt der grundlegende Aufbau des Feld-Objektes:
2023-02-21 15:59:14 +01:00
!!!include(../api/collections/fields/date.yml)!!!
2022-11-19 14:51:34 +01:00
## validator Objekt
2022-11-21 10:33:21 +01:00
<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.
2023-02-21 15:59:14 +01:00
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.
2022-11-19 14:51:34 +01:00
Attribute des Objektes:
2023-02-21 15:59:14 +01:00
| 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 |
2022-11-19 14:51:34 +01:00
### eval-Attribut
Der Javascript-Code in diesem Attribut kann folgende Rückgabe-Werte haben:
2023-02-21 15:59:14 +01:00
| Wert | Bedeutung |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `true` | Der Wert des Feldes ist gültig |
| `false` | Der Wert des Feldes ist ungültig |
2022-11-19 14:51:34 +01:00
| `"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. |
2023-06-07 10:58:23 +02:00
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 Validator berücksichtigt wird.
2022-11-19 14:51:34 +01:00
2023-02-21 15:59:14 +01:00
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.
2022-11-19 14:51:34 +01:00
2023-02-21 15:59:14 +01:00
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.
2022-11-19 14:51:34 +01:00
#### siehe
2023-02-21 15:59:14 +01:00
- [Server Javascript Kontext](./../../server-javascript-kontext/allgemeines.md)
2023-06-07 10:58:23 +02:00
TODO: Validator
2022-11-19 14:51:34 +01:00
## dependsOn
2022-11-21 10:33:21 +01:00
<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:
2023-02-21 15:59:14 +01:00
- name:
2022-11-21 10:33:21 +01:00
de: Standardseite
en: Standard page
id: page
2023-02-21 15:59:14 +01:00
- name:
2022-11-21 10:33:21 +01:00
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"
```
2022-11-19 14:51:34 +01:00
`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:
2023-02-21 15:59:14 +01:00
- [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)
2022-11-19 14:51:34 +01:00
Die Rückgabe des Javascript-Codes beeinflusst die Einblendung des betroffenen Feldes in folgender Weise:
2023-02-21 15:59:14 +01:00
| Rückgabe | Bedeutung |
| -------- | -------------------------- |
| `true` | Das Feld wird angezeigt |
| `false` | Das Feld wird ausgeblendet |
2022-11-21 10:33:21 +01:00
2022-11-19 14:51:34 +01:00
## 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`.
2023-05-26 17:42:23 +02:00
## containerProps
2023-05-28 13:37:50 +02:00
Um Felder auf breiten Bildschirmen eine schmalere Breite zu geben, wird das containerProps Attribut empfohlen. Es hat ein class Attribut, welches klassen ins HTML injiziert. Es gibt außerdem noch das Layout attribut mit breakBefore und breakAfter, welche dafür sorgen, dass vorher bzw. nachher keine weiteren HTML Elemente platz finden. Hier ist des weiteren das size Objekt drin, welches 3 attribute hat. Die attribute sollten col-1 bis col-12 beeinhalten, diese klassen werden ins html injiziert, können also dem zufolge auch misbraucht werden. Die klassen bei den attributen werden bei unterschiedlichen Bildschirmbreiten aktiv.
2023-05-26 17:42:23 +02:00
```yaml
2023-05-28 13:37:50 +02:00
containerProps:
#optional class prop
layout:
breakBefore: false
2023-05-26 17:42:23 +02:00
breakAfter: false
2023-05-28 13:37:50 +02:00
size:
default: "col-8"
small: "col-12"
large: "col-4"
2023-05-26 17:42:23 +02:00
```
2023-05-30 17:41:54 +02:00
## inputProps
Wenn man das Input element direkt bearbeiten möchte (Bspw. readonly oder ähnliches), so kann man diese hier als Objekt übergeben:
```yaml
inputProps: { readonly: true, placeholder: { de: "Wert wird automatisch gesetzt", en: "Value is set automatically" } }
```