# 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