refactored

This commit is contained in:
2022-11-19 13:51:34 +00:00
parent 705754f608
commit f173af8e12
47 changed files with 594 additions and 435 deletions

View File

@@ -0,0 +1,6 @@
# assets
Folgende Angaben sind in der `assets`-Sektion der [config.yml](./config.yml.md) geführt als Liste möglich:
!!!include(api/assets/demoassets.yml)!!!

View File

@@ -8,67 +8,10 @@ Eine solche Datei hat folgenden Aufbau:
!!!include(api/collections/democol.yml)!!!
## imageFilter Objekt
### siehe
Die Bildmanipulation von hochgeladen Bildern zu einer Kollektion kann über das `imageFilter` Objekt definiert werden.
Der Filter wird angewandt, wenn an die Bild-URL der Parameter `filter=...` angehangen wird.
Der Prozess selbst erfolgt beim ersten Abruf des Bildes und wird zwischengespeichert.
Eine beispielhafte Konfiguration, die die Bilder nur verkleinert sieht so aus:
!!!include(api/collections/democol/imageFilter.yml)!!!
Folgende Attribute können Filter-Eintrage haben, wobei `fit` und `fill` exklusiv sind:
| Attribut | Typ | Beschreibung |
| --- | --- | --- |
| `fit` | boolean | passt das Bild in ein Rechteck ein |
| `fill` | boolean | streckt/staucht das Bild, so dass es das Rechteck komplett ausfüllt |
| `height` | number | Höhe des Rechtecks |
| `width` | number | Breite des Rechtecks |
| `blur` | number | Verwischungsgrad |
| `brightness` | number | Helligkeit |
| `contrast` | number | Konrast |
| `gamma` | number | Gamma-Wert |
| `saturation` | number | Sättigung |
| `sharpen` | number | Schärfe |
| `invert` | boolean | Farben invertieren |
| `grayscale` | boolean | Schwarz-Weiß |
| `resampling` | "lanczos"<br>"nearestNeighbor"<br>"linear"<br>"catmullRom" | Resampling-Algorithmus |
| `quality` | number | Ausgabequalität 0..100 |
## indexes Liste
TODO
## meta Objekt
Wie bereits an anderer Stelle beschrieben, dient das `meta` Objekt zur Definition von Merkmalen, die im *tibi-admin* finden. Zum Anlegen der Struktur in der Datenbank und Definition der API haben diese Angaben keine Relevanz.
Folgende Angaben sind möglich:
!!!include(api/collections/democol/meta.yml)!!!
### views Liste
`views` werden für die Darstellung der Kollektion-Daten im *tibi-admin* benötigt. Die Auswahl des passenden View erfolgt über CSS Media-Queries.
Optionale Unternavigationen können eigene `views` haben.
Folgende möglche Einträge für `views` gibt es derzeit:
#### simpleList
!!!include(api/collections/democol/simpleList.yml)!!!
#### table
!!!include(api/collections/democol/table.yml)!!!
### tablist
Wird die `tablist` verwendet, ist sicher zu stellen, dass alle Felder in der Definition aufgenommen werden. Werden Felder nicht in die `tablist` aufgenommen, sind diese weiterhin in einer Gesamtliste unterhalb der Tabs und bringen das Layout durcheinander.
!!!include(api/collections/democol/tablist.yml)!!!
- [fields](./collections/fields.md)
- [indexes](./collections/indexes.md)
- [hooks](./collections/hooks.md)
- [imageFilter](./collections/imageFilter.md)
- [meta](./collections/meta.md)

View File

@@ -0,0 +1,67 @@
# 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. |
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
`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`.

View File

@@ -0,0 +1,44 @@
# 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.

View File

@@ -0,0 +1,37 @@
# 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
## contentbuilder

View File

@@ -0,0 +1,30 @@
# imageFilter Objekt
Die Bildmanipulation von hochgeladen Bildern zu einer Kollektion kann über das `imageFilter` Objekt definiert werden.
Der Filter wird angewandt, wenn an die Bild-URL der Parameter `filter=...` angehangen wird.
Der Prozess selbst erfolgt beim ersten Abruf des Bildes und wird zwischengespeichert.
Eine beispielhafte Konfiguration, die die Bilder nur verkleinert sieht so aus:
!!!include(api/collections/democol/imageFilter.yml)!!!
Folgende Attribute können Filter-Eintrage haben, wobei `fit` und `fill` exklusiv sind:
| Attribut | Typ | Beschreibung |
| --- | --- | --- |
| `fit` | boolean | passt das Bild in ein Rechteck ein |
| `fill` | boolean | streckt/staucht das Bild, so dass es das Rechteck komplett ausfüllt |
| `height` | number | Höhe des Rechtecks |
| `width` | number | Breite des Rechtecks |
| `blur` | number | Verwischungsgrad |
| `brightness` | number | Helligkeit |
| `contrast` | number | Konrast |
| `gamma` | number | Gamma-Wert |
| `saturation` | number | Sättigung |
| `sharpen` | number | Schärfe |
| `invert` | boolean | Farben invertieren |
| `grayscale` | boolean | Schwarz-Weiß |
| `resampling` | "lanczos"<br>"nearestNeighbor"<br>"linear"<br>"catmullRom" | Resampling-Algorithmus |
| `quality` | number | Ausgabequalität 0..100 |

View File

@@ -0,0 +1,3 @@
# indexes Liste
TODO

View File

@@ -0,0 +1,29 @@
# meta Objekt
Wie bereits an anderer Stelle beschrieben, dient das `meta` Objekt zur Definition von Merkmalen, die im *tibi-admin* finden. Zum Anlegen der Struktur in der Datenbank und Definition der API haben diese Angaben keine Relevanz.
Folgende Angaben sind möglich:
!!!include(api/collections/democol/meta.yml)!!!
## views Liste
`views` werden für die Darstellung der Kollektion-Daten im *tibi-admin* benötigt. Die Auswahl des passenden View erfolgt über CSS Media-Queries.
Optionale Unternavigationen können eigene `views` haben.
Folgende möglche Einträge für `views` gibt es derzeit:
### simpleList
!!!include(api/collections/democol/simpleList.yml)!!!
### table
!!!include(api/collections/democol/table.yml)!!!
## tablist
Wird die `tablist` verwendet, ist sicher zu stellen, dass alle Felder in der Definition aufgenommen werden. Werden Felder nicht in die `tablist` aufgenommen, sind diese weiterhin in einer Gesamtliste unterhalb der Tabs und bringen das Layout durcheinander.
!!!include(api/collections/democol/tablist.yml)!!!

View File

@@ -6,4 +6,10 @@ Es hat sich jedoch als günstig erwiesen bei Webprojekten die Datei und alle and
## Aufbau
!!!include(api/config.yml)!!!
!!!include(api/config.yml)!!!
### siehe
- [collections](./collections.md)
- [jobs](./jobs.md)
- [assets](./assets.md)

View File

@@ -1,251 +0,0 @@
# 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

View File

@@ -0,0 +1,11 @@
# jobs
In dem ein oder anderen Projekt werden sicherlich Jobs im Hintergrund benötigt, die zu bestimmten Zeiten oder Intervallweise ausgeführt werden müssen (z.B. Datenbereinigung). Diese Jobs können innerhalb der [config.yml](./config.yml.md) definiert werden.
Wie in allen YAML-Definitionen können auch die Jobs via `!include` ausgelagert werden.
Der Aufbau eines Jobs ausgelagert in einer Datei sieht beispielsweise folgendermaßen aus:
!!!include(api/jobs/demojob.yml)!!!
Die Möglichkeiten innerhalb der Javascript-Datei werden im Kapitel [Javascript Kontext](./../server-javascript-kontext/job.md) beschrieben.

View File

@@ -54,11 +54,11 @@ Bei Aufteilung der Kollektionskonfigurationen in einzelne Dateien, sollten diese
### /api/collections/fields
Sollten Feldkonfigurationen wieder verwendet werden, können diese im [api/collections/fields/](./fields.md) Unterordner gepeichert werden. Diese sind pro Feldkonfiguration als einzelne Datei aufzuführen.
Sollten Feldkonfigurationen wieder verwendet werden, können diese im [api/collections/fields/](./collections/fields.md) Unterordner gepeichert werden. Diese sind pro Feldkonfiguration als einzelne Datei aufzuführen.
### /api/hooks
Jede Javascript-Datei, die einen Hook bedient sollte im Unterordner benannt nach der Kollektion im Ordner [api/hooks/](./hooks.md) sein. Der Name der Datei sollte sich nach den Hook richten. Z.B. **get_return.js** ist zustängig für den GET-Hook nach dem Lesen der Daten, bevor diese zurück gegeben werden. Mehr dazu unter [Hooks](./hooks.md).
Jede Javascript-Datei, die einen Hook bedient sollte im Unterordner benannt nach der Kollektion im Ordner [api/hooks/](./collections/hooks.md) sein. Der Name der Datei sollte sich nach den Hook richten. Z.B. **get_return.js** ist zustängig für den GET-Hook nach dem Lesen der Daten, bevor diese zurück gegeben werden. Mehr dazu unter [Hooks](./collections/hooks.md).
### /api/templates