From 0979f01478f022539098062166f89b7c3af1bb90 Mon Sep 17 00:00:00 2001
From: robin <binkrassdufass@gmail.com>
Date: Fri, 2 Jun 2023 16:13:58 +0000
Subject: [PATCH] widgets doc

---
 .../collections/fields/widgets.md             | 169 ++++++++++++++++--
 1 file changed, 153 insertions(+), 16 deletions(-)

diff --git a/docs/md/projektkonfig/collections/fields/widgets.md b/docs/md/projektkonfig/collections/fields/widgets.md
index 18f5bf1..232be14 100644
--- a/docs/md/projektkonfig/collections/fields/widgets.md
+++ b/docs/md/projektkonfig/collections/fields/widgets.md
@@ -1,41 +1,178 @@
 # 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.
+Die Verwendung von Widgets innerhalb der Anwendung tibi-admin dient zur Handhabung von Dateninputs und -outputs. Das genutzte Widget wird über das meta.widget Feld in der Konfiguration spezifiziert. Dabei wird der Name des Widgets als Textzeichenkette (String) angegeben.
 
-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.
+Es ist zu beachten, dass nicht jedes Widget für jeden Datentyp geeignet ist. Im Weiteren werden die kompatiblen Datentypen für jedes Widget aufgeführt. Zusätzlich werden spezielle Konfigurationsmöglichkeiten für jedes Widget erläutert.
 
-## string / text / input
+## Texteingabefeld-Widgets: string / text / input
 
-## number / int / integer / float / double
+Diese Bezeichnungen stehen alle für dasselbe Widget. Es handelt sich hierbei um ein Texteingabefeld. Dieses Widget wird für den Datentyp String verwendet. Sollte ein größeres Textfeld (Textarea) anstatt eines einfachen Eingabefeldes (Input) gewünscht sein, so kann dies erreicht werden, indem das Attribut multiline im inputProps Objekt auf true gesetzt wird.
 
-## boolean / bool / check / switch / checkbox
+```yaml
+- name: firstname
+  type: string
+  meta:
+      label: { de: "Vorname", en: "firstname" }
+      inputProps:
+          multiline: true
+```
 
-## select / selectArray
+## Numerische Eingabefeld-Widgets: number / int / integer / float / double
 
-Diese beiden sind eigentlich auch einfach nur unterschiedliche Namen für dasselbe widget, da intern die differenzierung zwischen <select multiple> und einfach nur <select> anhand davon getroffen wird, ob im Datentyp ein "[]" am Ende ist oder nicht. Vorgesehen ist aber natürlich selectArray für string array Datentypen und select für einen normalen String. Es sind (aktuell) nur Strings möglich, da <option> alle values in einen string konvertiert, anpassungen sind hier aber bei bedarf möglich. Anzumerken ist, dass das name attribut das visuell dargestellte ist, wobei die id der abgespeicherte Wert ist. Wird choices als objekt angegeben, so wird die request and den spezifizierten endpoint geschickt und letzten endes das name attribut von ihm angezeigt. Die id der ausgewählten elemente wird intern als String abgespeichert.
+Diese unterschiedlichen Bezeichnungen stehen alle für dasselbe Widget. Hierbei handelt es sich um ein Eingabefeld für Zahlen. Es wird für den Datentyp Number verwendet.
 
-## date / dateTime
+## Auswahl-Widgets: boolean / bool / check / switch / checkbox
 
-Können für type "date" verwendet werden. date erstellt ein <input type="date"> widget (nur das Datum). dateTime erstellt ein <input type="datetime-local"> widget (datum + uhrzeit).
+Diese verschiedenen Bezeichnungen repräsentieren dasselbe Widget. Dieses Widget wird in Form einer Auswahlbox (Checkbox) dargestellt und wird für den Datentyp Boolean verwendet.
 
-## richtext / html
+## Auswahl-Widgets für mehrere Optionen: select / selectArray
 
-Unterschiedliche bezeichnungen für ein und dasselbe widget. Dieses wird für den Datentyp string verwendet und repräsentiert ein Textarea feld mit mehreren bearbeitungsmöglichkeiten (ähnl wie World), wobei der Input als HTML in einen String geladen wird. Das html kann man durch die Checkbox "source" auch manuell anpassen.
+Diese beiden Widgets sind im Prinzip das Gleiche, nur mit unterschiedlichen Namen. Intern wird die Unterscheidung zwischen Mehrfachauswahl (<select multiple>) und einfacher Auswahl (<select>) anhand des Datentyps getroffen. Bei Datentypen mit einem "[]" am Ende wird die Mehrfachauswahl verwendet. Der Einsatz von selectArray ist für String-Arrays vorgesehen, select für einzelne Strings. Aktuell sind nur Strings möglich, da das <option>-Element alle Werte zu Strings konvertiert. Anpassungen sind jedoch bei Bedarf möglich. Es ist wichtig zu beachten, dass das name-Attribut den visuell dargestellten Wert darstellt, während die id den gespeicherten Wert repräsentiert. Wenn choices als Objekt angegeben wird, wird eine Anfrage an den spezifizierten Endpunkt mit den angegebenen Parametern gesendet und das gemappte name-Attribut davon angezeigt. Die id der ausgewählten Elemente wird intern als String gespeichert. Weiterhin ist die Angabe von chipStyle: (style) möglich. Dieser wird als Stil in das Element gerendert und ermöglicht zum Beispiel die visuelle Darstellung von Flaggen.
 
-## file / image / mediaLibraryFile
+```yaml
+- name: filesss
+  type: string
+  meta:
+      label: { de: "Dateien", en: "files" }
+      widget: select
+      choices:
+          - name: "name"
+            id: "id"
+          - name: "namee"
+            id: "idd"
 
-Dies sind unterschiedliche Beziechnungen für das selbe widget <input type=file>. Wird für den Datentyp file verwendet.
+- name: ref
+  type: string
+  meta:
+      label: Reference
+      widget: select
+      choices:
+          #DEPRECATED - FOREIGNKEY STATTDESSEN!
+          endpoint: content
+          params:
+              sort: path
+          mapping:
+              id: id
+              name: path
+          chipStyle:
+              backgroundImage: "linear-gradient(black 33.3%, red 33.3%, red 66.6%, gold 66.6%);"
+              color: white
+              textShadow: 0px 0px 4px black
+```
 
-## checkboxArray
+## Bezug zu anderen Datenbankeinträgen: foreignKey
 
-## chipArray
+Dieses Widget wird verwendet, um eine Referenz zu einem anderen Datenbankeintrag herzustellen. Neben der Angabe von widget: foreignKey gibt es das foreign Attribut, welches die referenzierte Sammlung (collection) angibt. Zudem gibt es ein id Feld, welches die spezifische id für die Sicherheitsüberprüfung angibt. Wird hier "id" angegeben, wird es automatisch auf \_id gemappt, da dies der Name des ID-Feldes in MongoDB ist. Des Weiteren gibt es eine subNavigation, die die Struktur des Modals spezifiziert und neben dem Üblichen a) modal heißen sollte (Konvention) und b) einen defaultCallback haben sollte, der ausgelöst wird, wenn auf den Eintrag geklickt wird. Für die Auswahl gibt es auf dem Fensterobjekt (window Objekt) eine selectEntry Methode, die den ForeignEntry auswählt. Es gibt auch ein sort Attribut, falls die Auswahlmöglichkeiten sortiert werden sollen. Dieses wird einfach an die Anfrage angehängt. Wenn die zurückgegebenen Felder eingeschränkt werden sollen, kann eine Projektion (projection) für die Sammlung spezifiziert werden. Schließlich gibt es das render Attribut, welches ein Objekt ist und ein eval Feld enthält. Hier kann man unter anderem auf $foreignEntry und somit auf alle Werte der ausgewählten Projektion zugreifen. Der zurückgegebene Wert wird schließlich gerendert. Wenn das HTML roh gerendert werden soll, kann das raw Attribut auf true gesetzt werden.
+
+```yaml
+name: page
+type: string
+meta:
+    label:
+        de: Seite
+        en: page
+    widget: foreignKey
+    foreign:
+        collection: content
+        id: id
+        subNavigation: 0
+        projection: dashboard
+        sort: "path"
+        render:
+            raw: true
+            eval: |
+                (function() {
+                    var out = "";
+                    out += "<div style=\"color: #999;\">" + $foreignEntry.path + "</div>";
+                    return out;
+                })()
+```
+
+## Datums-Widgets: date / dateTime
+
+Diese beiden Widgets können für den Typ "date" verwendet werden. date erzeugt ein <input type="date"> Widget (nur das Datum), während dateTime ein <input type="datetime-local"> Widget erzeugt (Datum und Uhrzeit).
+
+## Textbearbeitungs-Widgets: richtext / html
+
+Diese beiden Bezeichnungen stehen für dasselbe Widget. Es handelt sich um ein Textfeld (Textarea) mit erweiterten Bearbeitungsmöglichkeiten (ähnlich wie in Word), wobei die Eingabe als HTML in einen String geladen wird. Das HTML kann auch manuell angepasst werden, indem die "source" Checkbox aktiviert wird.
+
+## Datei-Upload-Widgets: file / image / mediaLibraryFile
+
+Diese verschiedenen Bezeichnungen stehen alle für das gleiche Widget, nämlich <input type=file>. Es wird für den Datentyp File verwendet.
+
+## Mehrfachauswahl-Widgets: checkboxArray
+
+Hierbei handelt es sich um eine Reihe von Auswahlboxen (Checkboxen). Jede einzelne Auswahlbox spiegelt das Array choices wider. Dies entspricht genau dem, was auch im selectArray geschieht, nur dass es hier anders dargestellt wird.
+
+## Eingabe mit Vorschlägen: chipArray
+
+Dieses Widget hat eine ähnliche Funktion wie select, wird jedoch visuell anders dargestellt. Es bietet ein Eingabefeld, in dem nur Elemente akzeptiert werden, wenn ein Objekt im choices Array den gleichen name Wert wie das Eingabeelement hat. Darüber hinaus kann man im meta Objekt autocomplete auf true setzen, um die Autovervollständigung zu aktivieren. Dadurch werden dem Benutzer die möglichen Einträge angezeigt und können direkt ausgewählt werden, was die Benutzerfreundlichkeit erhöht.
+
+```yaml
+name: chipArray
+type: string
+meta:
+    label: "chipArray"
+    widget: chipArray
+    choices:
+        - name: "name"
+          id: "id"
+        - name: "namee"
+          id: "idd"
+    autocomplete: true
+```
 
 ## object
 
+Dieses Widget erfordert die weitere Angabe von subFields, die außerhalb des meta Objekts spezifiziert werden müssen. Hier werden die Felder angegeben, die in diesem Objekt enthalten sein sollen.
+
 ## objectArray / object[]
 
+Genau das gleiche wie object, nur das hier mehrere Objekte erstellt werden können.
+
 ## tabs
 
-## contentbuilder
+Dieses Widget hat im Prinzip die gleiche Funktion wie dasjenige in der Collection Meta-Konfiguration, ist jedoch etwas anders strukturiert. Ähnlich wie beim object Widget werden subFields verwendet, wobei das label von jedem subField der jeweilige Tab-Name ist. Würde man type auf number setzen, so hätte man in diesem Fall einfach einen Tab mit dem Namen "xyz" und ein number Feld im Tab mit dem gleichen Namen. Sinnvoller ist es natürlich, type auf object zu setzen, um mehrere Felder in einen Tab zu packen.
+
+```yaml
+name: paymentValues
+type: object[]
+meta:
+    label: "Überweisungswerte"
+    widget: tabs
+subFields:
+    - name: paymentValueObj
+      type: object[]
+      meta:
+          label: Überweisungswerte1
+      subFields:
+          - name: paymentValue
+            type: number
+            meta:
+                label: Überweisungswert1
+
+          - name: paymentValuee
+            type: number
+            meta:
+                label: Überweisungswert2
+    - name: paymentValueObj2
+      type: object[]
+      meta:
+          label: Überweisungswerte2
+      subFields:
+          - name: paymentValue
+            type: number
+            meta:
+                label: Überweisungswert1
+
+          - name: paymentValuee
+            type: number
+            meta:
+                label: Überweisungswert2
+```
+
+In diesem Beispiel wird ein object[] Typ mit dem tabs Widget erstellt. Jeder Tab repräsentiert ein Objekt im Array. Innerhalb jedes Tabs können weitere Felder durch SubFields definiert werden. Hier wird beispielhaft ein paymentValueObj mit zwei number Feldern erstellt. Die Benutzer können Werte für diese Felder eingeben und so mehrere paymentValueObj erstellen, die in paymentValues gespeichert werden.
+
+## contentbuilder - DEPRECATED
 
 siehe: [ContentBuilder](./widgets/contentbuilder.md)