252 lines
7.6 KiB
Markdown
252 lines
7.6 KiB
Markdown
# 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
|
|
|
|
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. |
|
|
|
|
Es ist ein Oneliner wie `new Date($this) > new Date()` meist ausreichend. Für komplexere Prüfungen ist eine sich selbst ausführende Funktion aber geeigneter, wie z.B.
|
|
|
|
```javascript
|
|
(function() {
|
|
if (new Date($this) > new Date()) {
|
|
return true
|
|
}
|
|
return false
|
|
})()
|
|
```
|
|
|
|
Dafür eignen sich im YAML Multiline-Modifizierer wie z.B.:
|
|
|
|
```yaml
|
|
eval: |
|
|
(function() {
|
|
if (new Date($this) > new Date()) {
|
|
return true
|
|
}
|
|
return false
|
|
})()
|
|
```
|
|
|
|
Wie im obigen Beispiel zu sehen, gibt es spezielle Variablen die im Javascript zur Verfügung stehen. Nicht alle Variablen stehen server- und clientseitig (*tibi-admin*) zur Verfügung. Eine ensprechende Ausnahmebehandlung ist daher nötig.
|
|
|
|
Folgende Variablen stehen zur Verfügung:
|
|
|
|
| Variable | Datentyp | tibi-server | tibi-admin | Bedeutung |
|
|
| --- | --- | --- | --- | --- |
|
|
| `$this` | | X | X | | Der Wert des Feldes in dem der Validator ausgeführt wird. |
|
|
| `$` (alias `entry`) | object | X | X | Das gesamte Objekt des Dokuments |
|
|
| `$parent` | object oder array | X | X | Der Wert des Elternknotens zum aktuellen Feld |
|
|
| `$stack` | array | X | X | Der Stack bis zum Ursprung des gesamten Objekts |
|
|
| `$namespace` | string | X | TODO | Die Bezeichnung des Namespace des aktuellen Projekts |
|
|
| `$method` | `"post"`/`"put"` | X | TODO | Die HTTP-Methode (Kleinschreibung) |
|
|
| `$auth` | object oder `null` | X | TODO | Das aktuelle Auth-Objekt des eingeloggten Benutzers, siehe Hooks `context.user.auth()` |
|
|
| `context` | object | X | - | Das serverseitige context-Objekt, siehe Hooks |
|
|
|
|
Für die beispielhafte Übertragung von
|
|
|
|
```json
|
|
{
|
|
"title": "Mein Datensatz",
|
|
"meta": {
|
|
"keywords": [
|
|
{
|
|
"key": "pla",
|
|
"description": "Ah Plah"
|
|
},
|
|
{
|
|
"key": "blup",
|
|
"description": "Buh Blup"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
wobei wir den `"key": "pla"` betrachten, wären die Inhalte der Variablen folgende:
|
|
|
|
`$this`:
|
|
|
|
plah
|
|
|
|
`$parent` und `$stack[0]`:
|
|
|
|
```json
|
|
{
|
|
"key": "pla",
|
|
"description": "Ah Plah"
|
|
}
|
|
```
|
|
|
|
`$stack[1]`:
|
|
|
|
```json
|
|
[
|
|
{
|
|
"key": "pla",
|
|
"description": "Ah Plah"
|
|
},
|
|
{
|
|
"key": "blup",
|
|
"description": "Buh Blup"
|
|
}
|
|
]
|
|
```
|
|
|
|
`$stack[2]`:
|
|
|
|
```json
|
|
{
|
|
"keywords": [
|
|
{
|
|
"key": "pla",
|
|
"description": "Ah Plah"
|
|
},
|
|
{
|
|
"key": "blup",
|
|
"description": "Buh Blup"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
`$stack[3]`, `entry` und `$`:
|
|
|
|
```json
|
|
{
|
|
"title": "Mein Datensatz",
|
|
"meta": {
|
|
"keywords": [
|
|
{
|
|
"key": "pla",
|
|
"description": "Ah Plah"
|
|
},
|
|
{
|
|
"key": "blup",
|
|
"description": "Buh Blup"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
|
|
|
|
## dependsOn und defaultValue Kontext
|
|
|
|
Der Javascript-Kontext ist für das `eval`-Attribut von `dependsOn` und `defaultValue` ebenso mit Variablen angereichert, wie es beim `validator.eval` der Fall ist. Da der entsprechende Code allerdings nur client-seitig ausgeführt wird (im Feld `meta` Objekt), sind nicht alle Variablen identisch.
|
|
|
|
Folgende Unterschiede gibt es zu den bereits beschriebenen Variablen von `validator.eval`:
|
|
|
|
| Variable | Unterschied |
|
|
| --- | --- |
|
|
| `context` | nicht vorhanden |
|
|
| `$method` | `"put"` bedeuted, dass der Datensatz gerade in Bearbeitung ist, `"post"` = Datensatz soll angelegt werden |
|
|
| `$navigation` | nur hier vorhanden, da der Server keine `subNavigation` Liste kennt,<br>enthält das aktuelle Objekt der aktiven Unternavigation, also den entprechenden Listeneintrag aus `meta.subNavigation` |
|
|
|
|
|
|
## Datentypen
|
|
|
|
Via `type` wird der Datentyp des Feldes definiert. Folgende Datentypen sind möglich:
|
|
|
|
### string
|
|
|
|
String wird für Zeichenketten verwendet. Das Standardwidget ohne weitere Angabe ist bei der Ausgabe die direkte Textausgabe und bei der Eingabe ein HTML `<input ...>` Element mit dem Attribut `type="text"`.
|
|
|
|
### number
|
|
|
|
Number wird sowohl für ganze Zahlen, wie auch für Gleitkommawerte definiert. Auch hier ist das Standard-Widget für die Eingabe ein HTML `<input ...>` Element, allerdings mit dem Attribut `type="number"`.
|
|
|
|
### boolean
|
|
|
|
Ein boolcher Wert, also `true` oder `false`, wird über den Typ `"boolean"` definiert und standardmäßig als Checkbox dargestellt.
|
|
|
|
### date
|
|
|
|
`"date"` als Datentyp kann sowohl Datumsangabe mit, als auch ohne Uhrzeit aufnehmen. Das Standardwidget ist die einfache Datumseingabe ohne Uhrzeit.
|
|
|
|
### file
|
|
|
|
Der Datentyp `"file"` ist für Dateiuploads vorgesehen. Es daher standardmäßig ein Datei-Auswahl-Dialog als Widget für die Eingabe angeboten.
|
|
|
|
### string[]
|
|
|
|
Für `"string[]` Arrays ist die Angabe des Widgets zwingend notwendig.
|
|
|
|
### number[]
|
|
|
|
Auch für `"number[]"` Arrays wird die Widget-Angabe erwartet.
|
|
|
|
### object
|
|
|
|
`"object"` ist ein spezieller Datentyp der zur Strukturierung der API und der Eingabe dient. Dieser Datentyp fasst `subFields` zusammen.
|
|
|
|
### object[]
|
|
|
|
Wie `"object"` fasst auch das `"object[]"` Array `subFields` zusammen. Diese allerdings als Liste von Objekten, anstatt als Einzelobjekt.
|
|
|
|
### any
|
|
|
|
Felder vom Typ `"any"` können beliebige Daten aufnehmen. Die Validierung schlägt auf Basis der Typ-Validierung hier nie fehl.
|
|
|
|
## Widgets
|
|
|
|
Das im *tibi-admin* für die Ein- und Ausgabe von Daten zu verwendente Widget wird über die Feldkonfiguration `meta.widget` festgelegt. Die Angabe erfolgt als String mit dem Widget-Namen.
|
|
|
|
Nicht jedes Widget kann mit jedem Datentyp umgehen, die möglichen Datentypen werden aber nachfolgend bei jedem Widget erwähnt. Außerdem wird auf individuelle Konfigurationsmöglichkeiten eingegangen.
|
|
|
|
### text
|
|
|
|
### number
|
|
|
|
### checkbox
|
|
|
|
### select
|
|
|
|
### date
|
|
|
|
### datetime
|
|
|
|
### richText
|
|
|
|
### file
|
|
|
|
### image
|
|
|
|
### selectArray
|
|
|
|
### checkboxArray
|
|
|
|
### chipArray
|
|
|
|
### object
|
|
|
|
### objectArray
|
|
|
|
### tabs
|