300 lines
8.3 KiB
Markdown
300 lines
8.3 KiB
Markdown
# fields
|
|
|
|
Felder im tibi-server müssen einen bestimmten Datentyp haben. Über die Admin-UI 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 der Admin-UI mitteilt, wie es dieses Feld für Ausgabe und Eingabe behandel soll.
|
|
|
|
Zunächst folgt der grundlegende Aufbau des Feld-Objektes:
|
|
|
|
```yaml
|
|
# Der Name des Feldes wird in der Datenbank zum Objekt ebenso
|
|
# wie in der Ein- und Ausgabe über die API verwendet.
|
|
name: date
|
|
|
|
# Über "type" wird der Datentyp in der Datenbank festgelegt.
|
|
# Mögliche Typen sind weiter unten aufgelistet.
|
|
type: date
|
|
|
|
# Direkt am Feld kann eine Index-Definition erfolgen.
|
|
# Folgende mögliche Werte können ihn die Liste aufgenommen werden:
|
|
# "single" - Standard-Index für diese Feld
|
|
# "unique" - Das Feld muss einen eindeutigen Wert haben
|
|
# "text" - Alle "text"-Indexanganben aller Felder werden zu einem
|
|
# gemeinsamen Volltext-Index kombiniert
|
|
#
|
|
# Die Angabe des Volltextindex ist besser unter "collections.X.indexes"
|
|
# vorzunehmen.
|
|
index:
|
|
- single
|
|
|
|
# Jede Datenübertragung an des Server wird validiert, d.h. es werden
|
|
# keine Datentypen angenommen, die nicht zu "type" passen.
|
|
# Darüber hinaus kann via "validator" eine zusätzliche Validierung
|
|
# vorgenommen werden.
|
|
# Dazu gibt es ein extra Kapitel.
|
|
validator:
|
|
required: true
|
|
eval: new Date($this) > new Date()
|
|
|
|
# Und natürlich gibt es auch hier ein "meta" Objekt zur Steuerung
|
|
# der Admin-UI.
|
|
meta:
|
|
# Das "label" des Feldes wird als Label vor dem Widget verwendet.
|
|
label:
|
|
de: Titel
|
|
en: title
|
|
|
|
# Abgelkeitet vom "type" gibt es Standard-Widgets. für spezielle
|
|
# Aufgaben stehen aber eine Hand voll Widgets bereit, die später
|
|
# beschrieben werden.
|
|
widget: text
|
|
|
|
# Standardwerte für neue Enträge können entweder direkt angegeben
|
|
# werden oder via Javascript client-seitig generiert werden.
|
|
# In den Kontext injizierte Variablen werden später beschrieben.
|
|
defaultValue:
|
|
# Das Ergebnis von "eval" wird hier als Standardwert verwendet.
|
|
# (hier das aktuelle Datum)
|
|
eval: new Date()
|
|
|
|
# Sollen Felder abhängig von bestimmten Bedingungen ein- oder
|
|
# ausgeblendet werden, geschieht das über Anweisungen in "dependsOn".
|
|
dependsOn:
|
|
# Das Feld wird nur eingeblendet wenn der Wert von "type"
|
|
# (auf gleicher Ebene wie das Feld "date" selbst)
|
|
# gleich "news" ist.
|
|
eval: $parent.type == "news"
|
|
|
|
```
|
|
|
|
## validator Objekt
|
|
|
|
Der Validator wird tibi-server seitig genutzt um die Daten zu validieren. Da das "validator" Objekt der Admin-UI ebenso zur Verfügung steht, kann vorab eine client-seitige Validierung zusaä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 Onliner wie `new Date($this) > new Date()` meist ausreichend. Für komplexere Prüfungen ist eine sich selbst ausführende Funktion aber oft 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 (Admin-UI) zur Verfügung. Eine ensprechende Ausnahmebehandlung ist daher nötig.
|
|
|
|
Folgende Variablen stehen zur Verfügung:
|
|
|
|
| Variable | Datentyp | serverseitig | Admin-UI | 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/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/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
|
|
|
|
TODO
|
|
|
|
## 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 input-Element vom 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 input-Element, allerdings vom type="number".
|
|
|
|
### boolean
|
|
|
|
Ein boolcher Wert, also true/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.
|
|
|
|
## Admin-UI Widgets
|
|
|
|
TODO
|
|
|
|
### text
|
|
|
|
### richText
|
|
|
|
### number
|
|
|
|
### checkbox
|
|
|
|
### select
|
|
|
|
### date
|
|
|
|
### datetime
|
|
|
|
### file
|
|
|
|
### image
|
|
|
|
### selectArray
|
|
|
|
### checkboxArray
|
|
|
|
### chipArray
|
|
|
|
### object
|
|
|
|
### objectArray
|
|
|
|
### tabs
|