tibi-docs/docs/projektkonfig/collections.md

# 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" eingebunden werden.

## Grundlegender Aufbau

Eine solche Datei (z.B. democol.yml) hat folgenden Aufbau:

```yaml
# Der Name der Kollektion wird in der Rest-API-URL verwendet, z.B.
# /_/demo/democol
name: democol

# Enthält die Kollektion Felder vom Typ "file", so werden die
# hochgeladenen Dateien unter dem Ordner abgelegt, der mit
# "uploadPath" bestimmt wird.
uploadPath: ../media/democol

# Wie auch in der Top-Level-Konfig "config.yml" ist auch hier ein
# "meta" Objekt möglich und nötig für die Konfiguration der
# Admin-UI.
# Mögliche Angaben werden im seperaten Kapitel behandelt.
meta: !include democol/meta.yml

# "imageFilter" definieren Filter, die Bilder bearbeiten, wie
# z.B. Verkleinerung.
# Mögliche Angaben werden im seperaten Kapitel behandelt.
imageFilter: !include democol/imageFilter.yml

# Projektionen der Daten werden via GET-Parameter "projection=..."
# referenziert.
# "projections" is ein Objekt, dass die Namen der Projektionen
# als Key führt.
projections:
    # "list" = Name der Projektion
    list:
        # "select" definiert als Keys die Felder, die beim Abruf
        # dieser Projektion in den Ausgabe-Daten enthalten sind.
        # Felder werden über die Punkt-Notation referenziert.
        select:
            title: 1
            date: 1
            # refenziert das "subField" "author" unterhalb von "meta"
            meta.author: 1
    details:
        # Alternativ kann "select" auch Auschlussregeln definieren.
        # Eine Mischung von Inkludieren und Auschluss ist NICHT
        # möglich.
        select:
            comment: 0
    full:
        # Ein leeres "select" Objekt beschränkt die Ausgabe der
        # Daten nicht und ist Standard, wenn der "projection="
        # Parameter nicht verwendet wurde.
        select:

# Allgeine Zugriffsregeln auf Kollektions-Ebene werden mit dem
# "permissions" Objekt festgelegt.
permissions:
    # Unter "public" werden die Zugriffsrechte für die Öffentlichkeit
    # definiert.
    public:
        # "methods" führt die HTTP-Methoden auf, die erlaubt sind
        methods:
            # "get: true" bedeutet hier, dass jeder die Daten lesen darf
            get: true
            # "post", also Einträge erstellen, "put" = Bearbeiten und
            # "delete" = löschen darf die Öffentlichkeit nicht.
            post: false
            put: false
            delete: false
        # Ist "validProjections" definiert, sind auch nur genau die
        # aufgelisteten Projektionen erlaubt, welche zwingend mit dem
        # GET-Parameter "projection=..." ausgewählt werden müssen.
        validProjections:
            - list
            - details

    # Der Key "user" steht für ALLE Benutzer die dem Projekt
    # zugeordnet sind.
    # D.h. eine feinere Abstufung auf Benutzerebene ist mit dem
    # Key "user" allein nicht möglich.
    # Für eine feinere Abstufung können nachgelagerte Hooks
    # dienen oder die Verwendung von zugeordneten benutzerdefinierten
    # "permissions" (siehe meta Objekt).
    user:
        methods:
            get: true
            post: false
            put: false
            delete: false
        # Fehlt "validProjections", sind automatisch alle Projektionen
        # erlaubt, wobei hier auch der GET-Parameter "projection="
        # weggelassen werden darf und somit alle Felder in der Ausgabe
        # zu finden sind.

    # Folgende Brechtigung wird angewandt, wenn der Zugriff über
    # den GET-Parameter "token=" oder die Header-Anweisung "token: "
    # angefragt wird.
    # "token" ist dabei die Markierung, dass es sich um einen Token
    # handelt und "${TOKEN}" ist der benutzerdefinierte Token selbst.
    # Dieser wird hier über eine Umgebungsvariable "TOKEN" injiziert,
    # die in "config.yml.env" definiert werden kann mit "TOKEN=...".
    token:${TOKEN}:
        methods:
            get: true
            post: true
            put: true
            delete: true

    # Alle Berechtigungs-Namen, die nicht "public", "user" oder "token:..."
    # heißen, sind benutzerdefinierte Berechtigungen, die Benutzern
    # zugeordnet werden können.
    # Eine mögliche Auflistung um Vorschläge in der Admin-UI anzubieten,
    # werden im Top-Level meta-Objekt der "config.yml" unter "permissions"
    # definiert.
    pages:
        methods:
            get: true
            post: true
            put: true
            delete: true

# "hooks" definieren die Algorithmen, die Daten und Abläufe zu bestimmten
# HTTP-Methoden und Schritten der API manipulieren können.
hooks:
    # Hooks für die Methode "get"
    get:
        # "read"-Schritt wird ausgeführt, bevor die Daten von der Datenbank
        # gelesen werden.
        read:
            # "type" ist derzeit immer "javascript"
            type: javascript
            # "file" zeigt auf die Datei mit dem Javascript-Code relativ zum
            # Ordner der "config.yml" Datei.
            file: hooks/democol/get_read.js
        # "return"-Schritt wird ausgeführt, bevor die gelesenen Daten über
        # HTTP übertragen werden.
        return:
            type: javascript
            file: hooks/democol/get_return.js

    # Hooks für die Methode "post"
    post:
        # "bind" wird ausgeführt, bevor die übertragenen Daten in eine
        # Objekt-Struktur umgewandelt werden.
        # Der tibi-server erwarten nach diesem Schritt gültige JSON-Daten,
        # d.h. sollte es möglich gemacht werden, dass andere Daten übertragen
        # werden, sind diese in diesem Hook abzufangen und zu verarbeiten.
        bind:
            type: javascript
            file: hooks/democol/post_bind.js
        # "validate" wird ausgeführt, bevor die Daten validiert werden.
        validate:
            type: javascript
            file: hooks/democol/post_validate.js
        # "create" wird ausgeführt, bevor das Objekt/Dokument in der Datenbank
        # angelegt wird.
        create:
            type: javascript
            file: hooks/democol/post_create.js
        # "return" wird ausgeführt, bevor die Serverantwort über HTTP
        # übertragen wird.
        return:
            type: javascript
            file: hooks/democol/post_return.js

    # Hooks für die Methode "put"
    put:
        bind:
            type: javascript
            file: hooks/democol/put_bind.js
        validate:
            type: javascript
            file: hooks/democol/put_validate.js
        # "bind" und "validate" habe die gleiche Bedeutung wie Hooks der
        # Methode "post".
        # "update" wird ausgeführt bevor das Objekt in der Datenbank
        # aktualisiert wird.
        update:
            type: javascript
            file: hooks/democol/put_create.js
        # "return" wird auch hier vor der Serverantwort ausgeführt.
        return:
            type: javascript
            file: hooks/democol/put_return.js

    # Hooks für die Methode "delete"
    delete:
        # Der "delete"-Hook wird vor dem eigentlichen Löschen ausgeführt
        delete:
            type: javascript
            file: hooks/democol/delete_delete.js
        # "return"-Hook kann ebenso hier die Serverantwort manipulieren
        return:
            type: javascript
            file: hooks/democol/delete_return.js

# "fields" stellen die Eigentliche Struktur der Kollektion dar.
# "fields" ist als Array angelegt um eine Standard-Sortierung
# in der Admin-UI vorzugeben.
fields:
    # Das Einbinden von Feldern über extra Dateien bietet sich nur
    # an, wenn das jeweilige Feld mehrfach von dieser oder anderen
    # Kollektionen verwendet wird.
    # Auf die möglichen Definitionen wird im Kapitel "fields"
    # eingegangen.
    - !include fields/title.yml
    - !include fields/date.yml
    - !include fields/type.yml

```

## imageFilter Objekt

TODO


## meta Objekt

Wie bereits an anderer Stelle beschrieben, dient das meta-Objekt zur Definition von Merkmalen, die in der Admin-UI Verwendung finden. Zum Anlegen der Struktur in der Datenbank und Definition der API haben diese Angaben keine Relevanz.

Folgende Angaben sind möglich:

```yaml
# Ein Label für die Admin-UI wird mehrsprachig folgendermaßen definiert
label:
    de: Demo-Kolletion
    en: Demo-Collection

# Jede Kolletion kann ein eigenes Icon aus mdijs bekommen.
muiIcon: web

# Die Standardsortierung bei ersten Aufruf der Kollektion.
defaultSort:
    # Nach welchem Feld soll sortiert werden?
    field: updatedTime
    # ASC für aufsteigend oder DESC für absteigend
    order: DESC

# Ist ein Javascript Message-Object-Empfänger implementiert, der empfangene
# Daten als Vorschau rendern kann, so ist dieser hier zu definieren.
# Implementierungshinweise zu einem Solchen gibt es später.
previewUrl: https://demo.testversion.online/preview

# Aus den definierten "imageFilter"-Angaben kann ein Filter für die
# Ausgabe der Thunbnails in der Admin-Ansicht ausgewählt werden.
defaultImageFilter: s

# Jede Kollektion kann über media-Querys mit mehreren Ansichten veknüpft werden.
# Mögliche Ansichten und die dazugehörigen CSS-Queries sind hier zu defineren.
views:
    # Natürlich können die Angaben auch ausgelagert und mehrfach verwendet werden.
    # Die möglichen Angaben werden im Kapitel "views" gezeigt.
    - !include simpleList.yml
    - !include table.yml

# Wird eine Kollektion als eine Gesamtliste schnell unübersichtlich, hild die 
# Definition von "subNavigation".
# Die meisten Angaben sind aus obiger Beschreibung den meta-Objektes bekannt.
# Es wird hier nur auf die zusätzlichen Angaben eingegangen.
subNavigation:
    - # Jede Unternavigation braucht einen eindeutigen Namen um diese später
      # in z.B. Javascript-Code wieder erkennen zu können.
      name: pages
      label:
          de: Seiten
          en: Pages
      muiIcon: page-layout-body
      defaultSort:
          field: titel
          order: ASC
      views:
          - !include simpleList.yml
          - !include table.yml
      # Um mehr Übersicht zu bekommen können zum Einen andere "views" und "defaultSort"
      # genutzt werden. Es kann aber auch eine Einschränkung der Daten über eine 
      # Vorfilterung via "filter" geben. "filter" ist ein Objekt mit MongoDB-Filterangaben.
      # siehe: https://www.mongodb.com/docs/compass/current/query/filter/
      filter:
          type: page
          
    - name: news
      label:
          de: Neuigkeiten
          en: News
      muiIcon: newspaper
      defaultSort:
          field: date
          order: DESC
      views:
          - !include simpleList.yml
          - !include table.yml
      filter:
          type: news

```

### views Liste

#### simpleList

#### table