# 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

# Standardsprache für Text-Index in der Datenbank
defaultLanguage: de

# 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

# Neben der Definition der Indexe innerhalbd des Feld-Objektes selbst,
# ist die Index-Definition global für die Kollektion auch hier möglich.
# Diese Definition ist z.B. für zusammengesetzte Index-Typen notwendig.
# Außerdem sind hier feinere Einstellungen für den Index möglich.
# Mehr dazu im "indexes" Kapitel
indexes: 
    - !include democol/textindex.yml
```

## 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:

```yaml
# Der Key des Objektes definiert den Namen des Filters.
# Jeder Filter ist eine Liste von Bildmanipulationen, die
# nacheinander angewandt werden.
# Die manipulierten Bilder werden gecachet. Ein nachträgliches
# Anpassen der Filter erfordert also das Löschen der gecachten
# Dateien welche sich jeweils neben den original Bilddateien
# im "uploadPath" der Kollektion befinden.
s:
    - fit: true
      height: 300
      width: 300
      resampling: lanczos
      quality: 60
m:
    - fit: true
      height: 600
      width: 600
      resampling: lanczos
      quality: 60
l:
    - fit: true
      height: 1200
      width: 1200
      resampling: lanczos
      quality: 60

```

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 |


## indexes Liste

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

# Standardmäßig werden im Formular zu Eingabe der Daten alle Felder von "fields"
# untereinander angeordnet.
# Um diese Anordnung in Tabs zu strukturieren, ist die Verwendung von "tablist"
# vorgesehen.
# Die Definition befindet sich in einem gesonderten Kapitel
tablist: !include democol/tablist.yml

```

### views Liste

"views" werden für die Darstellung der Kollektion-Daten in der Admin-UI benötigt. Die Auswahl des passenden View erfolgt über CSS Media-Queries.

Optionale Unternavigationen können eigene "views" haben.

Folgende Views gibt es derzeit:

#### simpleList

```yaml
# "type" legt den Typ des Views fest.
type: simpleList
# Die Auswahl erfolgt über folgende "mediaQuery".
# (hier also bis maximal 599px Fensterbreite)
mediaQuery: "(max-width:599px)"

# 3 Blöcke können in der simpleList verwendet werden.
# Haupttext "primaryText" und optional 2 weitere Angaben über
# "secondaryText" und "tertiaryText".
# Die Angabe des jeweiligen Feldes erfolgt als String oder
# Objekt mit der "source"-Eigenschaft.
# Das Feld selbst wird in Punkt-Notation angegeben.
# Die Darstellung selbst ist abhängig von der Feld-Konfiguration
# selbst, die unter fields in der Kollektions-Konfiguration
# stattfindet.
primaryText: title
secondaryText:
    source: date
tertiaryText: meta.author

```

#### table

```yaml
type: table
# Dieser View wird ab einer Fensterbreite von 600px angezeigt.
mediaQuery: "(min-width:600px)"
# Da es sich um eine Tabelle handelt, benötigt es eine Auflistung
# der Spalten unter "columns
columns:
    # Jede Spalte zeigt auf ein Feld.
    # Entweder wird hier nur der String des Feldes in Punk-Notation
    # angegeben oder ein Objekt mit weiteren Möglichkeiten
    - # "source" definiert das Feld via Punkt-Notation.
      source: updateTime
      # Mit "label" kann das Label aus der Feld-Konfiguration
      # überschrieben werden.
      label: 
        de: letztes Update
        en: last update
      # Ebenso kann der "type" der Feldkonfiguration überschrieben
      # werden oder gesetzt werden, wie in diesem Fall, da "updateTime"
      # ein Standardfeld der Kollektion ist und nicht in der "fields"-Liste
      # konfiguriert wird.
      type: date
    - source: title
      # Mit "filter: true" wird festegelegt, dass über diese Spalte
      # die Daten filterbar sind.
      filter: true
    - source: date
      filter: true
    - source: type
      filter: true
```

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

```yaml
# Hier wird der initial zu öffnende Tab festgelegt.
# Ist dieser nicht festgelegt, wird automatisch der erste Tab
# aus der "tabs" Liste gewaählt.
activeTab: general
# "tabs" ist die eigentliche Liste
tabs:
    - # Jeder Tab braucht einen Namen, über den er refereziert
      # werden kann.
      name: general
      # Die übliche Labelangabe kann auch hier mehrpsrachig erfolgen.
      label:
          de: Allgemein
          en: General
      # Welche Felder dieser Tab anzeigen soll, wird über "subFields"
      # beschrieben.
      subFields:
          - source: title
          - source: date
    - name: meta
      label:
          de: Metaangaben
          en: Meta data
      subFields:
          - source: meta.author

```