302 lines
11 KiB
Markdown
302 lines
11 KiB
Markdown
# 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 meta/meta.yml
|
|
|
|
# "imageFilter" definieren Filter, die Bilder bearbeiten, wie
|
|
# z.B. Verkleinerung.
|
|
# Mögliche Angaben werden im seperaten Kapitel behandelt.
|
|
imageFilter: !include ../_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: -1
|
|
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}:
|
|
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 views/simpleList.yml
|
|
- !include views/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 views/simpleList.yml
|
|
- !include views/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 views/simpleList.yml
|
|
- !include views/table.yml
|
|
filter:
|
|
type: news
|
|
|
|
```
|
|
|
|
### views Liste
|
|
|
|
#### simpleList
|
|
|
|
#### table |