tibi-docs/docs/projektkonfig/fields.md

# 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