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