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 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.

(function() {
    if (new Date($this) > new Date()) {
        return true
    }
    return false
})()

Dafür eignen sich im YAML Multiline-Modifizierer wie z.B.:

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
$ (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

{
    "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]:

{
    "key": "pla",
    "description": "Ah Plah"
}

$stack[1]:

[
    {
        "key": "pla",
        "description": "Ah Plah"
    },
    {
        "key": "blup",
        "description": "Buh Blup"
    }
]

$stack[2]:

{
    "keywords": [
        {
            "key": "pla",
            "description": "Ah Plah"
        },
        {
            "key": "blup",
            "description": "Buh Blup"
        }
    ]
}

$stack[3], entry und $:

{
    "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, 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