robin/tibi-starter
1
0
Fork 0
generated from cms/tibi-docs
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Robin Grenzdörfer
2023-12-26 20:24:42 +01:00
commit 66d0377a00
657 changed files with 21841 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/md/projektkonfig/api-ordner.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 47 KiB

6
docs/md/projektkonfig/assets.md Normal file
View File

@@ -0,0 +1,6 @@
# assets
Folgende Angaben sind in der `assets`-Sektion der [config.yml](./config.yml.md) geführt als Liste möglich:
!!!include(../api/assets/demoassets.yml)!!!

17
docs/md/projektkonfig/collections.md Normal file
View File

@@ -0,0 +1,17 @@
# collections
Die Konfiguration einer Kollektion sollte zur besseren Übersicht innerhalb einer gesonderten Datei im Unterorder **api/collections/** erfolgen und via `!include` in die [config.yml](./config.yml.md) eingebunden werden.
## Grundlegender Aufbau
Eine solche Datei hat folgenden Aufbau:
!!!include(../api/collections/democol.yml)!!!
### siehe
- [fields](./collections/fields.md)
- [indexes](./collections/indexes.md)
- [hooks](./collections/hooks.md)
- [imageFilter](./collections/imageFilter.md)
- [meta](./collections/meta.md)

BIN
docs/md/projektkonfig/collections/dependsOn.webm Normal file
View File

Binary file not shown.

237
docs/md/projektkonfig/collections/fields.md Normal file
View File

@@ -0,0 +1,237 @@
# 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
<video width="100%" controls muted autoplay loop>
<source src="validator.webm" type="video/webm">
</video>
Wie im Beispiel von **fields/date.yml** unter `validator` zu sehen ist, wird dort ein Datum nach dem aktuellen erwartet. Wie der Validator sich auf die UI auswirkt, ist im obigen Video zu sehen.
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. |
Da der `eval` Code serverseitig immer ausgeführt wird und ein Fehlschlag zwangsläufig zum Abbruch der Serveraktion führt, ist es wichtig, dass der Validator berücksichtigt wird.
Optional kann der Code auch zusätzlich über eine Lauffähigkeit ohne Fehler (z.B. keine Verwendung nicht vorhandender Kontext-Variablen oder Verwendung von `try ... catch`) im _tibi-admin_ verfügen. Das hat den Vorteil, dass eine Vorab-Validierung stattfindet, bevor der Datensatz an der Server gesendet wird.
Sollte der `eval` Code im _tibi-admin_ nicht lauffähig sein (nicht abgefangene Exception), wird der Validator clientseitig ingoriert und nur die serverseitige Prüfung beeinflusst die Aktion.
#### siehe
- [Server Javascript Kontext](./../../server-javascript-kontext/allgemeines.md)
## dependsOn
<video width="100%" controls muted autoplay loop>
<source src="dependsOn.webm" type="video/webm">
</video>
Obige Darstellung wie im Video wird beispielsweise durch folgende Feld-Konfiguration erreicht:
```yaml
# in einer Kollektions-Konfiguration
fields:
- name: type
type: string
meta:
label:
de: Typ
en: Type
widget: select
choices:
- name:
de: Standardseite
en: Standard page
id: page
- name:
de: News
en: News
id: news
- name: title
type: string
meta:
label:
de: Titel
en: Title
- name: date
type: date
meta:
label:
de: Titel
en: title
widget: date
defaultValue:
eval: new Date()
dependsOn:
eval: $parent?.type == "news"
```
`meta.dependsOn` kann als Objekt mit `eval`-Attribut für Javascript oder als `string` mit dem Feldnamen (Punktschreibweise, z.B. `"additionalData.author"`) angegeben werden.
Wird der Feldname verwendet wird nur geprüft, ob das Feld belegt ist. TODO
Die `eval` Variante verwendet als Javascript-Kontext Variablen die auf folgenden Seite beschrieben werden:
- [Admin Javascript Kontext](./../../admin-javascript-kontext/allgemeines.md)
- [collection.meta..eval](./../../admin-javascript-kontext/collection.meta..eval.md)
- [field.meta..eval](./../../admin-javascript-kontext/field.meta..eval.md)
Die Rückgabe des Javascript-Codes beeinflusst die Einblendung des betroffenen Feldes in folgender Weise:
| Rückgabe | Bedeutung |
| -------- | -------------------------- |
| `true` | Das Feld wird angezeigt |
| `false` | Das Feld wird ausgeblendet |
## defaultValue
Für die Vorlegung neu anzulegender Datensätze kann in `field.meta.defaultValue` direkt der Standardwert hinterlegt werden, oder über `field.meta.defaultValue.eval` ein Javascript-Code angegeben werden, der den Wert ermittelt. Die Rückgabe des Javascript-Codes, sowie auch die direkte Vergabe des Wertes muss dem Datentyp des Feldes entsprechen.
Der Javascript-Kontext ist der gleiche wie bei `field.meta.dependsOn.eval`.
## containerProps
Um Felder auf breiten Bildschirmen eine schmalere Breite zu geben, wird das containerProps Attribut empfohlen. Es hat ein class Attribut, welches klassen ins HTML injiziert. Es gibt außerdem noch das Layout attribut mit breakBefore und breakAfter, welche dafür sorgen, dass vorher bzw. nachher keine weiteren HTML Elemente platz finden. Hier ist des weiteren das size Objekt drin, welches 3 attribute hat. Die attribute sollten col-1 bis col-12 beeinhalten, diese klassen werden ins html injiziert, können also dem zufolge auch misbraucht werden. Die klassen bei den attributen werden bei unterschiedlichen Bildschirmbreiten aktiv.
```yaml
containerProps:
#optional class prop
layout:
breakBefore: false
breakAfter: false
size:
default: "col-8"
small: "col-12"
large: "col-4"
```
## inputProps
Wenn man das Input element direkt bearbeiten möchte (Bspw. readonly oder ähnliches), so kann man diese hier als Objekt übergeben:
## hide
möchte man, dass ein bestimmtes Feld nicht im TibiAdmin sichtbar ist, so muss man die property hide auf true setzen.
```yaml
inputProps: { readonly: true, placeholder: { de: "Wert wird automatisch gesetzt", en: "Value is set automatically" } }
```
## direction
Für type Object[] gibt es im Meta objekt das direction attribut, dies kann entweder:
- `horizontal`: flex-direction: row
oder
- `vertical`: flex-direction: column
annehmen.
## metaElements
Möchte man bestimmte Elemente über das Zahnrad greifbar machen (bei type: Object[]), so kann man dies über dieses Attribut tun. Es ist entweder über eine Liste, oder über tablist möglich.
!!!include(../api/collections/fields/info.yml)!!!
## folding
Das folding Objekt ist ebenfalls ein Teil im Meta object und dient dazu, type ObjectArray einen Wert in den Header im HTML einzuschreiben (von den einzelnen Objekten). Es wird vorallem dazu genutzt, die Rows bzw. Columns der Website rein zu rendern, um praktisch ein direktes Prview zu haben. Ebenfalls gibt es das force attribut, welches dafür sorgt, dass die objekte IMMER geöffnet sind und man sie nicht schließen kann. Sinnvoll für Rows. die Generelle struktur verdeutlicht folgendes Code Beispiel:
```yaml
folding:
force: false
previewUnfolded:
raw: true
eval: |
//js
(() => {
return $this?.title ? "<h2 style=\"\">" + $this.title + "</h2>" : ""
})()
//!js
previewFolded:
eval: |
//js
(async () => {
const { getRenderedElement, Row } = await import($projectBase + "_/assets/dist/admin.mjs")
const container = getRenderedElement(Row, {
props: {
row: Object.assign({}, $this),
contentId: $?.id,
apiBaseURL: $projectBase,
},
addCss: [
$projectBase + "_/assets/dist/index.css",
$projectBase + "_/assets/dist/admin.css",
],
})
let style = "max-width: 1220px;"
container.style = style
return container
})()
//!js
```
Hierbei ist raw dafür da, das ganze als HTML direkt zu rendern, wenn es true ist. Der prefiewFolded bereich rendert letzten endes die Seite selbst, für diese Funktionallität ist mehreres notwendig.
- `Row und Column Komponenten`: Dies sind letzenendes jene komponenten die gerendert werden, daher muss man sie natürlich auch bereits programmiert haben.
- `admin.ts file`: Dieses file wird im src Folder platziert und durch ES-Build über den oben genutzen Pfad verfügbar gemacht. Hier ist ein Beispiel:
```ts
import Row from "./components/Row.svelte"
import Col from "./components/Col.svelte"
function getRenderedElement(component, options?: { props: { [key: string]: any }; addCss?: string[] }) {
const el = document.createElement("div")
el.attachShadow({ mode: "open" })
const target = document.createElement("body")
el.shadowRoot.appendChild(target)
options?.addCss?.forEach((css) => {
const link = document.createElement("link")
link.rel = "stylesheet"
link.href = css
link.type = "text/css"
el.shadowRoot.appendChild(link)
})
new component({
target: target,
props: options?.props,
})
return el
}
export { getRenderedElement, Row, Col }
```
Das props Attribut nimmt ein Objekt entgegen, welches als keys die namen hat, wie in der svelte Komponente über export exportiert wurde. Die Komponenten werden in eine Shadow Dom geladen, um sie seperat vom restlichen code halten zu können.

43
docs/md/projektkonfig/collections/fields/datentypen.md Normal file
View File

@@ -0,0 +1,43 @@
# Datentypen
Via `type` wird der Datentyp des Feldes definiert. Diese Angaben sind für den Tibi Server relevant. 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.

BIN
docs/md/projektkonfig/collections/fields/defaultArray.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 46 KiB

BIN
docs/md/projektkonfig/collections/fields/foreign.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 53 KiB

97
docs/md/projektkonfig/collections/fields/widgets.md Normal file
View File

@@ -0,0 +1,97 @@
# Widgets
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.
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.
## Texteingabefeld-Widgets: string / text / input
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.
!!!include(../api/collections/fields/title.yml)!!!
## Numerische Eingabefeld-Widgets: number / int / integer / float / double
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.
!!!include(../api/collections/fields/age.yml)!!!
## Auswahl-Widgets: boolean / bool / check / switch / checkbox
Diese verschiedenen Bezeichnungen repräsentieren dasselbe Widget. Dieses Widget wird in Form einer Auswahlbox (Checkbox) dargestellt und wird für den Datentyp Boolean verwendet.
!!!include(../api/collections/fields/isEmployed.yml)!!!
## Auswahl-Widgets für mehrere Optionen: select / selectArray
Diese beiden Widgets sind im Prinzip das Gleiche, nur mit unterschiedlichen Namen. Intern wird die Unterscheidung zwischen Mehrfachauswahl und einfacher Auswahl 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 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.
!!!include(../api/collections/fields/gender.yml)!!!
## Bezug zu anderen Datenbankeinträgen: foreignKey
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.
!!!include(../api/collections/fields/image.yml)!!!
!!!include(../api/collections/medialib.yml)!!!
Setzt man defaultCollectionViews auf true, so könnte das ergebnis wie folgt aussehen:
![defaultCollectionViews auf ture](foreign.png)
## Datums-Widgets: date / dateTime
Diese beiden Widgets können für den Typ "date" verwendet werden. date erzeugt ein Widget (nur das Datum), während dateTime ein Widget erzeugt (Datum und Uhrzeit).
!!!include(../api/collections/fields/date.yml)!!!
## 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.
!!!include(../api/collections/fields/description.yml)!!!
## Datei-Upload-Widgets: file / image / mediaLibraryFile
Diese verschiedenen Bezeichnungen stehen alle für das gleiche Widget. Es wird für den Datentyp File verwendet.
!!!include(../api/collections/fields/profilePic.yml)!!!
## 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.
!!!include(../api/collections/fields/skills.yml)!!!
## 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.
!!!include(../api/collections/fields/tags.yml)!!!
## 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.
!!!include(../api/collections/fields/info.yml)!!!
## objectArray / object[]
Genau das gleiche wie object, nur das hier mehrere Objekte erstellt werden können.
## grid
Für Datentyp object[], dient als übersichtliche object[] alternative, speziell für pagebuilder entwickelt.
!!!include(../api/collections/fields/employmentDetails.yml)!!!
## jsonField
Wird für Daten genutzt, wo man die Struktur nicht absehen kann.
!!!include(../api/collections/fields/additionalData.yml)!!!
## tabs
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.
!!!include(../api/collections/fields/emplymentDetails.yml)!!!
# useDefaultArray
Wenn ein belibiger Datentyp in einem Array gefordert ist, so kann man jedes beliebige Widget dafür nutzten, indem man useDefaultArray: true benutzt. Damit kann jedes widget in das defaultArray widget gepackt werden. Wird Object[] in kombination mit useDefaultArray verwendet, so wird die einfache Objektdarstellung in diese darstellung implementiert.
![useDefaultArray auf true](defaultArray.png)
!!!include(../api/collections/fieldLists/useDefaultArray.yml)!!!
## contentbuilder - DEPRECATED
siehe: [ContentBuilder](./widgets/contentbuilder.md)

BIN
docs/md/projektkonfig/collections/fields/widgets/contentbuilder-medialib.webm Normal file
View File

Binary file not shown.

BIN
docs/md/projektkonfig/collections/fields/widgets/contentbuilder-module.webm Normal file
View File

Binary file not shown.

35
docs/md/projektkonfig/collections/fields/widgets/contentbuilder.md Normal file
View File

@@ -0,0 +1,35 @@
# contentbuilder
> Der ContentBuilder ist ein Drittanbieter-Produkt und steht nicht in jeder Lizenz zur Verfügung. Bitte kontaktieren Sie uns, wenn Sie Interesse an diesem Widget haben.
Für die Gestaltung von HTML-Inhalten ist der ContentBuilder eine einfache und intuitive Lösung. Es sind Layout-Hilfmittel wie Spalten und Zeilen ebenso verfügbar, wie die Möglichkeit Dateien (Bilder, Video, Downloads) direkt in den HTML-Code einzubinden.
Wie der ContentBuilder an einem Feld konfiguriert wird verdeutlicht folgendes Beispiel:
!!!include(../api/collections/fields/content.yml)!!!
## Mediathek Kollektion
<video width="100%" controls autoplay muted loop>
<source src="contentbuilder-medialib.webm" type="video/webm">
</video>
Wie aus der obigen Definition unterhalb von z.B. "imageSelect" zu lesen, bedarf es einer eigenen Kollektion für Bilder und andere Dateien. Diese Kollektion könnte wie folgt aussehen:
> Die Bedeutung der hier nicht beschriebenen Eigenschaften ist unter [collections](./../../../collections.md) zu finden.
!!!include(../api/collections/medialib.yml)!!!
## Module (customTags)
Die Einbindung des konfigurierten Beispiel-Moduls aus obiger Definition erfolgt im ContentBuilder wie im folgenden Video zu sehen ist:
<video width="100%" controls autoplay muted loop>
<source src="contentbuilder-module.webm" type="video/webm">
</video>
Wie oben schon erwähnt, sind die `placeholder` frei wählbar. Eine HTML5-Schreibweise bietet sich aber sowohl für das Styling, als auch für die spätere Einbindung in ein Frontend an.
In unserem Beispiel hier wurden zusättzlich zum eigentlichen Modul-Tag noch Attribute (`title` und `description`) definiert. Diese können dann im Frontend das eigentliche Modul beeinflussen.
Im Frontend könnte ein Modul dann später als "Custom Element" implementiert werden oder es wird ein HTML-Parser verwendet, der die Tags durch eigene Komponenten ersetzt, wie er im Anhang [TODO] zu finden ist.

104
docs/md/projektkonfig/collections/hooks.md Normal file
View File

@@ -0,0 +1,104 @@
# hooks
Hooks in Tibi sind spezielle Funktionen, die bestimmte Teile der HTTP-Anfragen und -Antworten manipulieren können. Sie erlauben Ihnen, den Datenfluss und die Abläufe zu bestimmten Zeitpunkten im Lebenszyklus einer HTTP-Anfrage zu beeinflussen.
Jeder Hook ist einer bestimmten HTTP-Methode (z.B. GET, POST, PUT, DELETE) und einem bestimmten Schritt in diesem Prozess zugeordnet. Die verfügbaren Schritte variieren je nach Methode und können beinhalten:
- read (GET)
- return (GET, POST, PUT, DELETE)
- bind (POST, PUT)
- validate (POST, PUT)
- create (POST)
- update (PUT)
- delete (DELETE)
Jeder dieser Schritte wird an einem spezifischen Punkt während der Verarbeitung einer HTTP-Anfrage oder -Antwort ausgeführt. Die genaue Reihenfolge und das Verhalten der Hooks ist in der jeweiligen Methode definiert.
## Hook Implementierung
Jeder Hook ist in einer separaten JavaScript-Datei implementiert, die im hooks-Ordner Ihres Projekts gespeichert ist. Der Pfad zu dieser Datei wird in der jeweiligen collection yml Datei angegeben.
Ein Hook ist eine Funktion, die eine context-Variable zur Verfügung hat, welche Informationen und Methoden für die aktuelle Anfrage bereitstellt. Der Rückgabewert dieser Funktion wird verwendet, um die Verarbeitung der Anfrage oder Antwort zu beeinflussen.
Zwei spezielle Typen, `HookResponse` und `HookException`, werden in Hooks verwendet, um Daten zu manipulieren und Fehler zu signalisieren.
### HookResponse
Die HookResponse ist das Objekt, das von einem Hook zurückgegeben wird. Es kann verwendet werden, um Daten zu manipulieren, die in die Datenbank geschrieben oder an den Benutzer zurückgegeben werden.
Es beinhaltet:
- `data`: Daten, die in die Datenbank geschrieben werden. Sie können diese Daten im Hook ändern, bevor sie in die Datenbank geschrieben werden.
- `results`: Daten, die an den Benutzer zurückgegeben werden. Sie können diese Daten im Hook ändern, bevor sie an den Benutzer zurückgegeben werden.
### HookException
Eine HookException ist ein Fehler, der in einem Hook geworfen werden kann. Sie können eine HookException verwenden, um einen Fehler zu signalisieren und die Verarbeitung der Anfrage oder Antwort zu stoppen.
Eine HookException kann folgende Eigenschaften haben:
- `status`:
HTTP-Statuscode des Fehlers.
- `html`:
HTML-Nachricht des Fehlers.
- `message`:
Textnachricht des Fehlers.
- `bytes`:
Binäre Daten des Fehlers.
- `json`:
JSON-Daten des Fehlers.
- `file`:
Dateipfad der Fehlermeldung.
- `log`:
Wenn true, wird der Fehler im Serverprotokoll aufgezeichnet.
### Hook Beispiel
Hier ist ein Beispiel für einen Hook, der die GET-Methode bearbeitet:
```js
;(function () {
/** @type {HookResponse}*/ // @ts-ignore
let hookResponse
let request = context.request()
if (request.query("rateIt")) {
let orderNumber
orderNumber = Number(request.query("orderNumber"))
if (isNaN(orderNumber))
throw {
status: 400,
message: "Invalid order number.",
}
/** @type {Order} */ // @ts-ignore
let order = context.db.find("order", {
filter: {
sequence: orderNumber,
},
})[0]
if (!order)
throw {
status: 400,
message: "No entry with this order number.",
}
if (order.deliveryAddress.postcode != request.query("postalcode"))
throw {
status: 403,
message: "Error",
}
hookResponse = {
filter: {
orderId: order.id,
},
}
return hookResponse
}
})()
```
In diesem Beispiel wird zuerst die Anfrage analysiert und eine Bedingung überprüft. Wenn die Bedingung erfüllt ist, wird ein bestimmtes Element in der Datenbank gesucht. Wenn das Element gefunden wird und bestimmte Kriterien erfüllt, wird ein HookResponse-Objekt erstellt und zurückgegeben. Wenn während des Prozesses Fehler auftreten, werden entsprechende HookException-Objekte geworfen.

30
docs/md/projektkonfig/collections/imageFilter.md Normal file
View File

@@ -0,0 +1,30 @@
# imageFilter Objekt
Die Bildmanipulation von hochgeladen Bildern zu einer Kollektion kann über das `imageFilter` Objekt definiert werden.
Der Filter wird angewandt, wenn an die Bild-URL der Parameter `filter=...` angehangen wird.
Der Prozess selbst erfolgt beim ersten Abruf des Bildes und wird zwischengespeichert.
Eine beispielhafte Konfiguration, die die Bilder nur verkleinert sieht so aus:
!!!include(../api/collections/democol/imageFilter.yml)!!!
Folgende Attribute können Filter-Eintrage haben, wobei `fit` und `fill` exklusiv sind:
| Attribut | Typ | Beschreibung |
| --- | --- | --- |
| `fit` | boolean | passt das Bild in ein Rechteck ein |
| `fill` | boolean | streckt/staucht das Bild, so dass es das Rechteck komplett ausfüllt |
| `height` | number | Höhe des Rechtecks |
| `width` | number | Breite des Rechtecks |
| `blur` | number | Verwischungsgrad |
| `brightness` | number | Helligkeit |
| `contrast` | number | Konrast |
| `gamma` | number | Gamma-Wert |
| `saturation` | number | Sättigung |
| `sharpen` | number | Schärfe |
| `invert` | boolean | Farben invertieren |
| `grayscale` | boolean | Schwarz-Weiß |
| `resampling` | "lanczos"<br>"nearestNeighbor"<br>"linear"<br>"catmullRom" | Resampling-Algorithmus |
| `quality` | number | Ausgabequalität 0..100 |

30
docs/md/projektkonfig/collections/indexes.md Normal file
View File

@@ -0,0 +1,30 @@
# indexes Liste
Die indexes-Anweisung in der Konfigurationsdatei einer Sammlung (collection.yml) ist ein Array von Indexdefinitionen. Indizes werden in Datenbanken verwendet, um die Suchleistung zu optimieren. Indem Sie die richtigen Indizes definieren, können Sie die Effizienz Ihrer Anwendung verbessern. Es ist NICHT MÖGLICH einen gesetzten Index über die yml Datei wieder zu entfernen, hierfür muss man direkt in die Datenbank gehen.
Jede Indexdefinition ist ein Objekt mit bestimmten Eigenschaften:
- `name`:
Ein eindeutiger Name für den Index. Es ist optional, wird jedoch empfohlen, um den Index später leicht identifizieren zu können.
- `key`:
Bestimmt, auf welche Felder der Index angewendet werden soll. Dies kann ein einfacher String sein, wenn der Index nur ein Feld umfasst, oder ein Array von Strings, wenn der Index mehrere Felder umfasst.
Zum Beispiel key: ["$text:$**"] definiert einen Volltextindex über alle Felder. Der spezielle Operator $text wird verwendet, um einen Volltextindex zu erstellen, und der Operator $\*\* bezeichnet alle Felder in der Sammlung.
Eine andere mögliche Indexdefinition könnte so aussehen: key: ["file.type"]. Dies würde einen Index auf dem Feld type innerhalb des Unterobjekts file erstellen.
- `unique`:
Wenn auf true gesetzt, erzwingt dies, dass der Index eindeutige Werte enthält. Wenn Sie versuchen, einen Eintrag mit einem bereits indizierten Wert hinzuzufügen, wird ein Fehler ausgelöst und der Vorgang abgebrochen.
- `background`:
Wenn auf true gesetzt, erstellt die Datenbank den Index im Hintergrund, um die Leistungsauswirkungen auf andere Operationen zu minimieren.
- `defaultLanguage`:
Wird verwendet, um die Sprache für Textindizes festzulegen. Dies ist wichtig für die Volltextsuche, da verschiedene Sprachen unterschiedliche Tokenisierungs- und Stemmungsregeln haben.
Ein Beispiel für die Verwendung von Indizes in der Sammlungskonfigurationsdatei könnte so aussehen:
!!!include(../api/collections/democol/textindex.yml)!!!
In diesem Beispiel wird ein Textindex namens textindex erstellt, der alle Felder der Sammlung abdeckt. Der Index wird im Hintergrund erstellt und verwendet Deutsch als Standardtextsprache.

87
docs/md/projektkonfig/collections/meta.md Normal file
View File

@@ -0,0 +1,87 @@
# meta Objekt
Wie bereits an anderer Stelle beschrieben, dient das `meta` Objekt zur Definition von Merkmalen, die im _tibi-admin_ finden. Zum Anlegen der Struktur in der Datenbank und Definition der API haben diese Angaben keine Relevanz.
Folgende Angaben sind möglich:
!!!include(../api/collections/democol/meta.yml)!!!
## views Liste
`views` werden für die Darstellung der Kollektion-Daten im _tibi-admin_ benötigt. Die Auswahl des passenden View erfolgt über CSS Media-Queries.
Optionale Unternavigationen können eigene `views` haben.
Möchte man, dass in der view selection Navbar vor den View namen bestimme Icons angezeigt werden, so kann man diese einfach per muiIcon im jeweiligen View Objekt angeben.
Folgende möglche Einträge für `views` gibt es derzeit:
### simpleList
!!!include(../api/collections/democol/simpleList.yml)!!!
### table
!!!include(../api/collections/democol/table.yml)!!!
### cardList
!!!include(../api/collections/democol/cardList.yml)!!!
## quickEdit
```yml
# wenn keine fields gesetzt sind, werden alle Felder der Kollektion angezeigt
quickEdit:
enabled: true # Standardmäßig ist die Schnellbearbeitung aktiviert
fields:
- title
- age
- date
```
### dashboardSimpleList
Fürs dashboard type: table
```yml
type: dashboardSimpleList
mediaQuery: "(max-width: 600px)"
primaryText: email
secondaryText: subject
```
### dashboardTable
Fürs dashboard type: table
```yml
type: dashboardTable
mediaQuery: "(min-width: 600px)"
columns:
- subject
- file
- file
- subject
- file
```
## tablist
Wird die `tablist` verwendet, ist sicher zu stellen, dass alle Felder in der Definition aufgenommen werden. Werden Felder nicht in die `tablist` aufgenommen, sind diese weiterhin in einer Gesamtliste unterhalb der Tabs und bringen das Layout durcheinander.
backup:
active: true
collectionName: backups
## multiupload
Der mutliupload kann bei jedem view type verwendet werden. Über $file kann man in eval auf das aktuelle file Objekt zugreifen. Hier ist eine Beispielscollection, welchen diesen verwendet.
!!!include(../api/collections/medialib.yml)!!!
## backups
im meta Objekt einer collection können backups für diese collection konfiguriert werden. Die backups werden in der Datenbank gespeichert und können über das tibi-admin in der selben collection angewandt werden. Wird ein collectoneintrag gelöscht, kann man diesen über den gelöschte einträge checkbox wiederherstellen.
folgende collection ist ein beispiel für eine backup collection
!!!include(../api/collections/backups.yml)!!!

BIN
docs/md/projektkonfig/collections/validator.webm Normal file
View File

Binary file not shown.

17
docs/md/projektkonfig/config.yml.md Normal file
View File

@@ -0,0 +1,17 @@
# config.yml
Die Datei **config.yml** ist der Einstieg in die API-Konfiguration eines Projekts. Die Datei kann sich an einem beliebigen Ort befinden. Die einzige Bedingung ist, dass sie durch den tibi-server lesbar ist.
Es hat sich jedoch als günstig erwiesen bei Webprojekten die Datei und alle anderen Datein, die zur API-Konfiguration gehören, im ordner [api/](./ordnerstruktur.md) unterhalb des eigentlichen Webprojektes anzuordnen. Die Quellen des Frontends und der API können somit in ein Mono-Repo eingecheckt werden.
## Aufbau
!!!include(../api/config.yml)!!!
### siehe
- [dashboard](./dashboard.md)
- [collections](./collections.md)
- [jobs](./jobs.md)
- [assets](./assets.md)

511
docs/md/projektkonfig/dashboard.md Normal file
View File

@@ -0,0 +1,511 @@
# dashboard
# Übersicht
Die bereitgestellte Konfiguration ist eine Spezifikation für ein Dashboard-Layout und seine Komponenten. Dieses Layout bestimmt die Anzeige und Interaktion von verschiedenen Datenvisualisierungen, vor allem in Form von Diagrammen (Graphen). Die Konfiguration ist in zwei Hauptabschnitte unterteilt: "majorItems" und "minorItems". Die "majorItems" sind größere, prominentere Darstellungen von Daten, während die "minorItems" kleinere, weniger prominente Datenelemente repräsentieren. Jedes Element innerhalb dieser Abschnitte ist ein einzelnes Modul oder eine Komponente auf dem Dashboard und kann verschiedene Arten von Datenvisualisierungen darstellen, einschließlich Linien-, Balken-, Kreis- (donut) und Flächendiagramme. Generell ist zu sagen, dass bei jeder string angabe auch I18n verwendet werden kann und bei nahezu jeder String angabe ist ebenfalls die eval angabe möglich. Sollten Nutzer keinen Zugriff auf die Daten haben dürfen, so wird das bestimmte Diagramm nicht gerendert und stattdessen ein Placeholder mit Zugriff verweigert angezeigt.
# Elementbeschreibungen
## type
Der Typ des Dashboard-Elements ist ein entscheidendes Attribut.
- ˋgraphˋ:
Wenn der Typ "graph" ist, wird das Element als Diagramm dargestellt. Dies ermöglicht eine Vielzahl von Visualisierungen wie Linien-, Balken-, Kuchen-, Donut- oder Flächendiagramme, abhängig vom graphType.
- ˋswiperˋ:
Der Typ "swiper" erstellt ein Karussell-ähnliches Element, das eine Reihe von anderen Elementen enthält, die durchgeblättert werden können. Jedes Element innerhalb des "swiper"-Typs wird genauso konfiguriert wie ein normales Dashboard-Element, was bedeutet, dass sie jeweils ihren eigenen type, title, etc. haben können.
- ˋreferenceˋ:
Die "reference"-Typ Elemente sind Verweise auf Collections.
- ˋcomparisonˋ:
Außerdem gibt es den type "comparison", wobei man ein timespan auswählt und dieser timespan und der timespan davor mit einander auf einen bestimmten Wert verglichen werden.
- ˋtableˋ:
Desweiteren gibt es einen type "table" wobei über das additionalApiParams Objekt mit dem limit attribut gesetzt wird wie viele Einträge von der ausgewählten collection Angezeigt werden sollen. Per Default sind es 5
- ˋsectionTitleˋ
Der "sectionTitle" type ist wie der name schon sagt, ein Titel für einen Abschnitt vom dashboard
## title
Der Titel eines Elements ist ein Objekt, das einen eval, value, contentBefore und contentAfter haben kann. value repräsentiert den Hauptteil des Titels, während contentBefore und contentAfter optionale Textstücke sind, die vor bzw. nach dem Haupttitel platziert werden. Eval kann als ersatz für value verwendet werden. Auch ist eine normale String angabe möchglich. Diese wird hier, sowie überall anders auch in die genutzte sprache konvertiert, daher ist die angabe über das {de:”xyz”, en:”xyz”} sinnvoll.
## subTitle
Dies ist ein Untertitel für das Dashboard-Element.
## additionalApiParams
Dies ist ein Objekt und kann folgende Parameter haben:
```ts
interface APIParams {
offset?: number
limit?: number
sort?: string
filter?: {
[key: string]: any
}
projection?: string
count?: 1
}
```
Sollte es komntextabhängig bereits automatisch genertierte Filter Objekt attirbute geben, so werden, wenn man welche angibt, seine eigenen über Object.assign zu diesen hinzu gefügt.
## subNavigation
Das Attrbiut bei type: reference dient dazu, den Link zu einer bestimmten subKategorie zu machen. Nimmt den index der gewüpnschten subNavigation als Wert.
## graphType
Das Attribut graphType bestimmt die spezifische Art der Datenvisualisierung für ein Element vom Typ "graph". Die möglichen Werte sind "line" (Linien-Diagramm), "bar" (Balkendiagramm), "donut" (Kreisdiagramm), “pie” (Kuchendiagramm) und "area" (Flächendiagramm).
## xAxis und yAxis
Diese Attribute definieren die Daten, die auf den Achsen des Diagramms angezeigt werden. xAxis immer "timeline", was bedeutet, dass die Daten über die Zeit dargestellt werden. yAxis kann “sum” oder “amount” sein. Sum summiert die Werte des angegebenen feldes im time interval, wohingegen amount die Menge des angegebenen Feldes im time interval aufsummiert und angibt. Möchte man die menge von den Kollektionen angeben, so ist kein weiterer schritt nötig. Möchte man angeben, wie oft ein feld in den kollektionen vor kommt, so hat man 2 möglichkeiten. Wenn das feld einmal pro kollektion vor kommt, so gibt man einfach über den field parameter den pfad dorthin an also bspw. wenn im root einfach nur xyz oder xyz.yxz.... Wenn das feld aber in einer object[] struktur ist, so gibt man den pfad dorthin an (über path) und dann ausgehend von dem objekt wird die field angabe genutzt. Bei sum ist das prinzip das selbe.
## containerProps
Um Felder auf breiten Bildschirmen eine schmalere Breite zu geben, wird das containerProps Attribut empfohlen. Es hat ein class Attribut, welches klassen ins HTML injiziert. Es gibt außerdem noch das Layout attribut mit breakBefore und breakAfter, welche dafür sorgen, dass vorher bzw. nachher keine weiteren HTML Elemente platz finden. Hier ist des weiteren das size Objekt drin, welches 3 attribute hat. Die attribute sollten col-1 bis col-12 beeinhalten, diese klassen werden ins html injiziert, können also dem zufolge auch misbraucht werden. Die klassen bei den attributen werden bei unterschiedlichen Bildschirmbreiten aktiv.
```yaml
containerProps:
#optional class prop
layout:
breakBefore: false
breakAfter: false
size:
default: "col-8"
small: "col-12"
large: "col-4"
```
## graphs
Ein Array von Objekten, wobei jedes Objekt ein einzelnes Diagramm darstellt, das innerhalb des Dashboard-Elements dargestellt wird. Bei meherer Angabe werden auch mehrere graphen im selben chart angezeigt, für unterschiedliche y Achsen im selben Chart ist multipleYAxes auf true zu setzen, hier ist dann auch die YAxisTitle vorgenommen. Jedes dieser Diagrammobjekte hat mehrere Attribute, darunter field,path, dateTimeField, collection und graphName. field gibt an, welches Datenfeld aus der Sammlung zur Erzeugung des Diagramms verwendet werden soll. Path gibt den weg zum feld an, wenn das feld direkt im objekt liegt, so ist “this” oder garkeine angabe valide. dateTimeField bestimmt das Feld, das die Zeitskala für das Diagramm liefert. collection ist der Name der Datenkollektion, aus der die Daten bezogen werden. Schließlich definiert graphName den Namen des Diagramms.
## style
Ein Objekt, das CSS-Stilinformationen für das Dashboard-Element enthält. Es ist für die reference elemente gedacht.
## collection
Dieses Feld bezieht sich auf die Datenquelle oder Sammlung, auf die das Dashboard-Element zugreifen wird.
## timeInterval
Dieses Feld definiert den Zeitraum, der im Diagramm angezeigt wird. Die möglichen Werte können "day", "month", "year" sein, je nachdem, welche Granularität für die Datenvisualisierung gewünscht wird.
## timespan
Der Zeitraum für die Vergleichsdaten. Es kann "QTD" für das aktuelle Quartal und das Quartal davor sein, "MTD" für den aktuellen Monat und den Monat davor sein oder YTD für das aktuelle Jahr und das Jahr davor sein. Immer nur bis zum heutigem Tag dieser Zeitspanne, also bspw. vom 1.1.2023 bis zum 28.5.2023 wäre YTD wobei das vergleichs Jahr dann vom 1.1.2022 bis zum 28.5.2022 wäre:
```js
switch (input) {
case "YTD": // Year to date
begin = new Date(date.getFullYear(), 0, 1)
end = currentDate
lastBegin = new Date(date.getFullYear() - 1, 0, 1)
lastEnd = new Date(date.getFullYear() - 1, date.getMonth(), date.getDate())
break
case "QTD": // Quarter to date
let quarterStartMonth = Math.floor(date.getMonth() / 3) * 3
begin = new Date(date.getFullYear(), quarterStartMonth, 1)
end = currentDate
lastBegin = new Date(date.getFullYear(), quarterStartMonth - 3, 1)
lastEnd = new Date(date.getFullYear(), date.getMonth() - 3, date.getDate())
break
case "MTD": // Month to date
begin = new Date(date.getFullYear(), date.getMonth(), 1)
end = currentDate
lastBegin = new Date(date.getFullYear(), date.getMonth() - 1, 1)
lastEnd = new Date(date.getFullYear(), date.getMonth() - 1, date.getDate())
break
}
```
## until
Dieses Feld definiert den Endpunkt des Zeitintervalls für die Datenvisualisierung. Mögliche Werte sind "lastWeek", “lastMonth”, “lastYear” und "allTime", welches jedoch default ist. Zum Beispiel, wenn until auf "lastMonth" gesetzt ist, wird das Diagramm maximal Daten bis zum letzten Monat anzeigen. Außerdem sind alle Optionen darunter für den Nutzer auswählbar. Um dies zu unterbinden, muss das filter attribut auf false gesetzt werden.
## defaultUntil
Dieses Attribut setzt den default Filter. Es ist anzumerken, dass mit jedem Filter change eine Neue Request einhergeht, und immer mit dem aktuellem Filter requested wird, dieser sollte also ggf. für perfomance per default niedrig gesetzt werden.
## filter
Wird filter auf false gesetzt, so ist der Filter nicht länger sichtbar.
## multipleYAxes
Dieses Boolean-Feld gibt an, ob das Diagramm mehrere Y-Achsen haben soll. Wenn auf true gesetzt, hat jedes Diagramm im graphs Array eine eigene Y-Achse haben. Hierfür ist dann eine Achsenbeschriftung sinnvoll. Diese wird dann mit yAxisTitle im jeweiligen Graphs objekt angegeben.
## graphBaseColor
Dies definiert die Basisfarbe des Diagramms. Die Farbe muss in einem gültigen CSS-Farbformat angegeben werden.
## value
Im Kontext des title-Feldes repräsentiert value den Hauptteil des Titels. In Bezug auf Diagramme, insbesondere bei Donut- und Kuchendiagrammen, repräsentiert value den numerischen Wert, der im Diagramm dargestellt wird. Hier sind mögliche werte: “total”, welches die Summe vom ausgewählten feld bis zu until ausgibt, “amount”, welches das gleiche macht, nur nicht summiert sondern zählt und “count” wobei die Einträge selbst gezählt werden.
## valueType
Wird bei "comparison" verwendet, um den vergleich relativ oder absolut vorzunehmen. Valide angaben sind: "relative" und "absolute".
## path
Dieses Feld kann verwendet werden, um den genauen Pfad zu der spezifischen Datenstruktur zu definieren, welches in der Sammlung für die Datenvisualisierung als referenz Array für den field parameter verwendet wird. Dies ist also sinvoll, wenn das Feld in einem Object[] ist, andernfalls ist bei field die angabe über xyz.yxz.zyx erwünscht. Ist das feld im root oder über den field parameter erreichbar, so kann man path leeer lassen oder "this" angeben.
## dateTimeField
Dies ist das Feld, das den Zeitstempel in der Datensammlung repräsentiert. Es wird verwendet, um die Zeitskala für das Diagramm zu liefern. Hier ist das erwünschte Datumsfeld in der collection auszuwählen.
## limit
gibt an wie viele Elemente maximal returned werden sollen.
## newPageRef
boolean, wenn explizit auf false, dann wird bei type reference kein Neue Seite hinzufügen button angezeigt.
# Code Beispiel
```yaml
dashboard:
majorItems: # Liste der Hauptelemente des Dashboards
- type: sectionTitle
title: "Overview" #i18n or eval
- type: swiper
containerProps:
class: "random-class"
layout:
breakBefore: false # no html elements before
breakAfter: false #no html elmenets after
size: #different classes depending on innerWidth
default: "col-8"
small: "col-12"
large: "col-4"
elements:
- type: comparison
collection: contact_form
timespan: "QTD" #QTD & MTD with last quarter, month or year
value: total
valueType: absolute #oder relative (prozentual)
path: paymentValues
additionalApiParams: #Nimmt APIParams entgegen und fügt sie zusätzlich ein, filter Objekt Parameter wird ggf. zum automatisch generierten Assigned, also vorsicht!
limit: 3
dateTimeField: Date
field: paymentValue
title: toller titel #string or eval
subTitle: { de: "YTD Vergleich zum Vorjahr", en: "YTD comparison with last year" }
- type: comparison
collection: contact_form
timespan: "QTD" #QTD & MTD with last quarter, month or year
value: total
valueType: absolute #oder relative (prozentual)
dateTimeField: Date
field: paymentValue
title: toller titel #i18n or eval
subTitle: { de: "YTD Vergleich zum Vorjahr", en: "YTD comparison with last year" }
- type: swiper
css:
graph:
wrapper:
eval: |
`
background-color: green ;
`
containerProps:
class: "random-class"
layout:
breakBefore: false # no html elements before
breakAfter: true #no html elmenets after
size: #different classes depending on innerWidth
default: "col-8"
small: "col-12"
large: "col-4"
elements:
- type: comparison
collection: contact_form
timespan: "QTD" #QTD & MTD with last quarter, month or year
value: total
valueType: relative #oder relative (prozentual)
path: paymentValues
dateTimeField: Date
field: paymentValue
title: toller titel #string or eval
subTitle: { de: "YTD Vergleich zum Vorjahr", en: "YTD comparison with last year" }
- type: comparison
collection: contact_form
timespan: "QTD" #QTD & MTD with last quarter, month or year
value: total
valueType: relative #oder relative (prozentual)
dateTimeField: Date
field: paymentValue
title: toller titel #string or eval
subTitle: { de: "YTD Vergleich zum Vorjahr", en: "YTD comparison with last year" }
- type: sectionTitle
title: "Details"
- type: graph # Art des Elements, hier ein Graph
css:
graph:
wrapper:
eval: |
`
background-color: yellow ;
`
title: # Titel des Graphen
#eval anstelle von value möglich
value: total #o. amount Haupttitel des Graphen
contentAfter: "€" # Nach dem Haupttitel hinzugefügte Inhalte
contentBefore: "xyz" # Vor dem Haupttitel hinzugefügte Inhalte
timeInterval: "day" # Zeitintervall der Daten im Graphen
until: "lastMonth" # Ende des Zeitintervalls (Ab dem aktuellen Datum)
graphType: "line" # Art des Graphen, hier ein Liniendiagramm
graphBaseColor: "#ff0000" # Basisfarbe des Graphen
subTitle: { de: "Umsatz", en: "sales volume" } # Untertitel des Graphen, mehrsprachig
xAxis: timeline # Art der x-Achse, hier eine Zeitachse
class: "random-class" #Class added
additionalApiParams:
limit: 2
containerProps:
#optional class prop
layout:
breakBefore: false
breakAfter: false
size:
default: "col-8"
small: "col-12"
large: "col-4"
graphs: # Liste der Graphen in diesem Element
- yAxis: sum # Art der y-Achse, hier eine Summe
field: paymentValue # Feld der Daten für den Graphen
dateTimeField: Date # Feld für den Zeitstempel der Daten
yAxisTitle: Graph titel # Titel der y-Achse
collection: contact_form # Sammlung, aus der die Daten stammen
graphName: { de: "Umsatz", en: "sales volume" } # Name des Graphen, mehrsprachig
- graphName: { de: "Umsatz anderes feldes", en: "Sum of other values" }
path: paymentValues # Pfad zu den Daten im Feld
yAxis: sum
dateTimeField: Date
field: paymentValue
collection: contact_form
- type: graph
title:
value: total
contentAfter: "€"
contentBefore: "xyz"
timeInterval: "day"
until: "lastMonth"
graphType: "line"
graphBaseColor: "#ff0000"
subTitle: { de: "Umsatz", en: "sales volume" }
xAxis: timeline
multipleYAxes: true # Option für mehrere y-Achsen
containerProps:
#optional class prop
layout:
breakBefore: false
breakAfter: false
size:
default: "col-8"
small: "col-12"
large: "col-4"
graphs:
- yAxis: sum
yAxisTitle: Summe nr 1
graphType: "bar" # Art des Graphen, hier ein Balkendiagramm
field: paymentValue
dateTimeField: Date
collection: contact_form
graphName: { de: "Umsatz", en: "sales volume" }
- graphName: { de: "Umsatz anderes feldes", en: "Sum of other values" }
path: paymentValues
yAxisTitle: Summe nr 2
yAxis: sum
graphType: "line"
dateTimeField: Date
field: paymentValue
collection: contact_form
- type: swiper # Art des Elements, hier ein Swiper
containerProps:
#optional class prop
layout:
breakBefore: false
breakAfter: false
size:
default: "col-8"
small: "col-12"
large: "col-4"
elements: # Liste der Elemente in diesem Swiper
- type: graph
title:
value: total
contentAfter: "€"
contentBefore: "xyz"
until: "lastMonth"
graphType: "donut" # Art des Graphen, hier ein Donut-Diagramm
value: total # Summe aller werte in spezifiziertem Feld, welche dann im Diagramm dargestellt werden
graphBaseColor: "#ff0000"
subTitle: { de: "Umsatz", en: "sales volume" }
graphs:
- field: paymentValue
dateTimeField: Date
collection: contact_form
graphName: { de: "Umsatz", en: "sales volume" }
- graphName: { de: "Umsatz anderes feldes", en: "Sum of other values" }
path: paymentValues
dateTimeField: Date
field: paymentValue
collection: contact_form
- type: graph
title:
value: total
contentAfter: "€"
contentBefore: "xyz"
until: "lastMonth"
graphType: "pie" # Art des Graphen, hier ein Kuchendiagramm
value: total
graphBaseColor: "#ff0000"
subTitle: { de: "Umsatz", en: "sales volume" }
graphs:
- field: paymentValue
dateTimeField: Date
collection: contact_form
graphName: { de: "Umsatz", en: "sales volume" }
- graphName: { de: "Umsatz anderes feldes", en: "Sum of other values" }
path: paymentValues
dateTimeField: Date
field: paymentValue
collection: contact_form
- containerProps:
#optional class prop
layout:
breakBefore: false
breakAfter: false
size:
default: "col-8"
small: "col-12"
large: "col-4"
type: graph
title:
value: total
contentAfter: "€"
subTitle: { de: "Umsatz", en: "sales volume" }
xAxis: timeline
timeInterval: "day"
graphType: "area" # Art des Graphen, hier ein Flächendiagramm
graphs:
- field: paymentValue
dateTimeField: Date
yAxis: sum
collection: contact_form
path: "this" # Pfad zu den Daten im Feld, hier das aktuelle Objekt, keine Angabe hat den gleichen Wert
graphName: { de: "Umsatz", en: "sales volume" }
- type: swiper
containerProps:
#optional class prop
layout:
breakBefore: false
breakAfter: true
size:
default: "col-8"
small: "col-12"
large: "col-4"
elements:
- class: col-6
type: graph
subTitle: { de: "Produktmenge", en: "Amount of products" }
xAxis: timeline
timeInterval: "day"
filter: false #deaktiviert die Filter möglichkeit für den Nutzer beim diagramm, normalerweise aktiviert. Hierbei sind alle kombinationen x >= until möglich
dateTimeField: Date
until: "lastMonth"
graphType: "bar"
graphs:
- graphName: { de: "Menge", en: "Amount" }
yAxis: amount # Art der y-Achse, hier die Anzahl von allen Feldern im spezifiziertem intervall
dateTimeField: Date
collection: contact_form
- class: col-8
type: graph
filter: false
title:
value: total
contentAfter: "€"
subTitle: { de: "Umsatz", en: "sales volume" }
xAxis: timeline
timeInterval: "day"
dateTimeField: Date
graphType: "line"
until: "lastMonth"
graphs:
- field: paymentValue
yAxis: sum # Art der y-Achse, hier eine Summe
collection: contact_form # Sammlung, aus der die Daten stammen
dateTimeField: Date # Feld für den Zeitstempel der Daten
path: "this" # Pfad zu den Daten im Feld, hier das aktuelle Objekt
graphName: { de: "Umsatz", en: "sales volume" } # Name des Graphen, mehrsprachig
- type: table #shows entries from specified collection
containerProps:
#optional class prop
layout:
breakBefore: false
breakAfter: true
size:
default: "col-8"
small: "col-12"
large: "col-7"
collection: contact_form
title: Konaktformular Titel
subTitle: subtitel oder so
additionalApiParams:
limit: 3
- collection: content # Sammlung, aus der die Daten für das nächste Element stammen
type: reference # Art des Elements, hier ein Referenz-Element
style: # Stil des Elements
upper: rgba(3, 50, 59, 0.7) # Farbe des oberen Teils
lower: rgba(3, 50, 59) # Farbe des unteren Teils
- collection: content # Wiederholung der vorherigen Elemente
type: reference
style:
upper: rgba(3, 50, 59, 0.7)
lower: rgba(3, 50, 59)
- collection: contact_form
subNavigation: 1
type: reference
style:
upper: rgba(3, 50, 59, 0.7)
lower: rgba(3, 50, 59)
minorItems: # Liste der Nebenelemente des Dashboards
- collection: contact_form # Referenz auf collections
subNavigation: 0
- collection: contact_form # Wiederholung der vorherigen Nebenelemente
subNavigation: 0
- collection: contact_form
subNavigation: 0
- collection: contact_form
subNavigation: 0
- collection: contact_form
subNavigation: 0
- collection: contact_form
newPageRef: false
```
![Resultierende Dashboard](dashboard.png)

BIN
docs/md/projektkonfig/dashboard.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 109 KiB

11
docs/md/projektkonfig/jobs.md Normal file
View File

@@ -0,0 +1,11 @@
# jobs
In dem ein oder anderen Projekt werden sicherlich Jobs im Hintergrund benötigt, die zu bestimmten Zeiten oder Intervallweise ausgeführt werden müssen (z.B. Datenbereinigung). Diese Jobs können innerhalb der [config.yml](./config.yml.md) definiert werden.
Wie in allen YAML-Definitionen können auch die Jobs via `!include` ausgelagert werden.
Der Aufbau eines Jobs ausgelagert in einer Datei sieht beispielsweise folgendermaßen aus:
!!!include(../api/jobs/demojob.yml)!!!
Die Möglichkeiten innerhalb der Javascript-Datei werden im Kapitel [Javascript Kontext](./../server-javascript-kontext/allgemeines.md) beschrieben.

65
docs/md/projektkonfig/ordnerstruktur.md Normal file
View File

@@ -0,0 +1,65 @@
# Ordnerstruktur
Als Konvention für neue Projekte hat sich folgende Ordnerstruktur etabliert:
![Ordnerstruktur](api-ordner.png)
Die Aufteilung der YAML-Konfiguration ist durch den YAML-Tag `!include` möglich. Genaueres dazu wird auf den nachfolgenden Seiten beschrieben.
## /api
Der Einstiegsordner in die Konfiguration ist frei wählbar. "/api" innerhalb des Projektrepositories hat sich jedoch bewährt.
Die Einstiegsdatei in die Gesamt-Konfiguration liegt hier und heißt [config.yml](./config.yml.md). In dieser können Umgebungsvariablen erstetzt werden, welche in [config.yml.env](./config.yml.md) definiert sind.
Ebenso sind alle nachfolgenden Unterordner beliebig zu benennen. Da aber ein JSON-Schema und VSCode-Konfiguration zur Validierung der YAML Dateien existiert, ist folgende Struktur hilfreich.
### JSON-Schema
Das JSON-Schema ist in die package.json einzubinden via:
```json
...
"devDependencies": {
...,
"tibi-types": "https://gitbase.de/cms/tibi-types.git"
},
...
```
Die im Projekt liegende VSCode-Konfig sollte dementsprechend ergänzt werden:
```json
...
"yaml.schemas": {
"node_modules/tibi-types/schemas/api-config/config.json": "api/config.y*ml",
"node_modules/tibi-types/schemas/api-config/collection.json": "api/collections/*.y*ml",
"node_modules/tibi-types/schemas/api-config/field.json": "api/collections/fields/*.y*ml",
"node_modules/tibi-types/schemas/api-config/fieldArray.json": "api/collections/fieldLists/*.y*ml"
},
"yaml.customTags": ["!include scalar"],
...
```
Sollte Yarn2 verwendet werden ist die Verlinkung von **node_modules** nötig. Dazu ist folgendes in der **.yarnrc.yml** einzutragen:
```yaml
...
nodeLinker: node-modules
```
## /api/collections
Bei Aufteilung der Kollektionskonfigurationen in einzelne Dateien, sollten diese in diesem Ordner gespeichert werden. Für jede Kollektion sollte eine eigene Datei verwendet werden, hier im Beispiel [api/collections/democol.yml](./collections.md).
### /api/collections/fields
Sollten Feldkonfigurationen wieder verwendet werden, können diese im [api/collections/fields/](./collections/fields.md) Unterordner gepeichert werden. Diese sind pro Feldkonfiguration als einzelne Datei aufzuführen.
### /api/hooks
Jede Javascript-Datei, die einen Hook bedient sollte im Unterordner benannt nach der Kollektion im Ordner [api/hooks/](./collections/hooks.md) sein. Der Name der Datei sollte sich nach den Hook richten. Z.B. **get_return.js** ist zustängig für den GET-Hook nach dem Lesen der Daten, bevor diese zurück gegeben werden. Mehr dazu unter [Hooks](./collections/hooks.md).
### /api/templates
Ist es nötig im Projekt Templates zu rendern (z.B. für den Email-Versand), sind diese im Ordner **templates** gut aufgehoben.