validator

docs/projektkonfig/fields.md

@@ -69,7 +69,152 @@ meta:
 
 ## validator Objekt
 
-TODO
+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