Die Oberfläche eines Plugins ist ein ES-Modul aus frontend/index.ts, geschrieben mit Vue 3 (<script setup>) und TypeScript. Es läuft in der Seite von QuickTribe – mit derselben Vue-, Pinia- und Router-Instanz – und hängt sich an festgelegten Stellen (Slots) ein oder bringt eigene Seiten mit.

Einstieg

  • Der Standard-Export ist install(sdk) (gern über definePlugin); er darf async sein.
  • Slot-Komponenten und Seiten nur nachgeladen registrieren (defineAsyncComponent(() => import(…)) bzw. component: () => import(…)). Der Einstieg selbst bleibt höchstens 15 KB groß (gzip) – er lädt auf jeder Seite, auf der das Plugin wirkt.
  • Der Kern lädt das Skript nur, wenn das Plugin auf der Seite wirkt: in einer Community nur, wenn es dort eingeschaltet ist; auf Seiten ohne Community (Startseite, Konto, Plattform-Admin, globale Plugin-Seiten) für alle plattformweit aktiven Plugins – auch solche, die nur je Community gelten.

Erlaubte Importe

Zur Laufzeit importiert ein Plugin nur vue, pinia, vue-router, @quicktribe/sdk und eigene Dateien. Eine Import-Map im Kopf jeder Seite lenkt diese vier Namen auf die Module des Kerns; das Plugin bündelt nie eine eigene Vue-Kopie. Typen kommen per import type aus @quicktribe/sdk/types. ESLint und npm run build:plugins lehnen andere Importe ab (etwa Pfade aus dem Kern wie @shared/…).

Das SDK

install() bekommt das SDK als Parameter, Komponenten holen es mit usePluginSdk().

API-Client

  • Pfade beginnen mit / und sind relativ zu /api/plugins/<id>/c/<slug>; sdk.api.global gilt für Endpunkte ohne Community (/api/plugins/<id>). Auf Seiten ohne Community gibt es nur api.global.
  • Der Client setzt CSRF-Kopfzeile und Sitzung selbst. options: signal (Abbrechen) und idempotencyKey (eigener Schlüssel oder true = zufällig, für Aktionen, die nicht doppelt laufen dürfen).
  • upload() schickt multipart/form-data per POST mit Fortschritt; mehrere Dateien als <feld>[], weitere Felder über fields. Die Grenzen prüft der Server (UploadRule).
  • Fehler kommen als ApiProblem (aus @quicktribe/sdk) mit status, message, violations (Feldpfad → Meldung, passend für UiField) und retryAfterSeconds bei 429.
Typen der eigenen Endpunkte schreibst du von Hand in frontend/api-types.ts – passend zu den PHP-Klassen, die der Handler zurückgibt (am besten readonly-Klassen mit \JsonSerializable). Kern- und Slot-Typen kommen ausschließlich aus dem SDK:

Slots

Slots sind feste Stellen in der Oberfläche von QuickTribe. Eine Slot-Komponente bekommt die Props context (nur lesen) und pluginId:
  • Event-Editor: Was die Komponente unter context.extra[pluginId] ablegt, schickt der Editor beim Speichern mit (siehe Eingaben im Event-Editor). extra beginnt immer leer – bestehende Werte lädt das Plugin über die eigene Schnittstelle. violations enthält nur die Meldungen dieses Plugins, ohne das Präfix extra.<pluginId>..
  • Editoren für Beitrag, Kurs und Lektion (ab 1.2): gleiche Regeln wie im Event-Editor – der Block geht als extra im Request mit, die Eingabe nimmt eine InputExtension entgegen (siehe Eingaben). Deklarierte Zusatzfelder zeigt der Editor selbst; der Slot ist für eigene Bedienelemente. Kurse und Lektionen bearbeitet nur die Kursverwaltung.
  • Twig-Seiten: Formular-Ausfüllseiten und öffentliche Landingpages laufen ohne Plugin-JavaScript; dort wirken nur Feldtypen und Bausteine aus Twig-Vorlagen des Plugins (mit dessen dist/plugin.css).
  • Die Slots in Event-Ansicht und Event-Liste erscheinen nur bei Terminen, die der Betrachter sehen darf; Slots eines in der Community ausgeschalteten Plugins erscheinen nie.
  • Später registrierte Slots erscheinen nachträglich. Unbekannte Slot-Namen (etwa aus einer neueren Version) ignoriert das SDK mit einer Warnung in der Konsole.
  • Wirft eine Komponente beim Aufbauen oder Zeichnen einen Fehler, blendet der Kern sie aus (auch in Produktion), meldet den Fehler an den Server, und das Plugin verschwindet aus allen Slots der Seite. Die Seite selbst läuft weiter.

Seiten

Seiten registriert das Plugin in PHP mit page() (siehe Seiten); ihren Inhalt liefert sdk.registerRoutes(). Die Routen sind relativ zur Basis der Seite – /c/<slug>/plugins/<id> bzw. ohne Community /plugins/<id> –, also path: '/' für die Startseite des Plugins und path: '/offers/:id' für /c/<slug>/plugins/<id>/offers/<id>. Der Kern rendert dabei Kopf, Navigation und Fuß der Plattform.
  • registerRoutes() wirkt nur auf der Seite dieses Plugins und nur während install(); auf anderen Seiten wird es ignoriert.
  • Passt keine Route, zeigt die Seite eine 404-Ansicht.
  • Links innerhalb des Plugins mit RouterLink; Links auf andere Bereiche über sdk.urls mit <a href> (anderer Bereich = neue Seite).

Stores

Ein Plugin darf eigene Pinia-Stores anlegen – in derselben Pinia wie der Kern, deshalb mit der ID plugin.<id>.<name>:
Stores, die eine Liste laden und lokal ändern, verwerfen veraltete Antworten (z. B. mit einem Zähler je Ladevorgang), damit eine spät eintreffende Liste keine eben gespeicherte Änderung überschreibt.

UI-Bausteine

Dieselben Komponenten wie im Kern – gleiche Optik, Themes und Dunkelmodus:
Rohes HTML (v-html) ist in Plugin-Oberflächen verboten (ESLint).

Übersetzungen

Deutsch ist Quelltext und Schlüssel, Englisch steht in translations/messages.en.json – derselben Datei, die auch PHP und die E-Mail-Vorlagen nutzen. Die Oberfläche übernimmt sie mit sdk.addMessages('en', en); sdk.t('Hallo {name}!', { name }) übersetzt mit Platzhaltern. ICU-Plurale ({count, plural, …}) kennt die Oberfläche nicht – ein solcher Text wirft einen Fehler, und das Plugin verschwindet aus allen Slots der Seite. Einzahl und Mehrzahl stehen deshalb als eigene Texte, die Auswahl trifft der Code (siehe Übersetzungen). Jedes Plugin hat eine eigene Übersetzungs-Instanz, die des Kerns bleibt unberührt. npm run build:plugins warnt, npm run i18n:check scheitert, wenn ein t('…')-Text ohne englische Übersetzung ist.

Stile mit Tailwind

frontend/plugin.css bindet die Utilities von Tailwind gegen das Theme der Plattform ein – mit deren Farben, Tokens (bg-primary, text-ink, rounded-card …), Breakpoints und Dunkelmodus, aber ohne deren eigene Klassen:
  • index.ts importiert plugin.css. Gebaut entsteht genau eine Datei dist/plugin.css mit den Klassen, die das Plugin benutzt.
  • Vorlagen für Feldtypen und Bausteine (ab 1.2): Ihre Klassen erzeugt Tailwind nur, wenn plugin.css die Ordner ../templates/forms bzw. ../templates/blocks als @source nennt. Nie das ganze ../templates: PDF- und Mail-Vorlagen enthalten Wörter wie fixed, aus denen sonst Klassen entstünden. Der Build und app:plugin:validate warnen bei fehlender Angabe.
  • Alle Klassen erlaubt: hidden, block, flex, grid-cols-2, fixed, overflow-x-auto und jede andere Klasse wirken nur in der Oberfläche des Plugins (siehe Geltungsbereich) – auch in den Vorlagen für Feldtypen und Bausteine. Tailwind liest weiterhin jedes passende Wort, auch in Code und Texten; solche Klassen landen in dist/plugin.css, verändern aber die Plattform nicht.
  • @reference zeigt immer auf tailwind-theme.css, nie auf tailwind.css (sonst enthielte die Datei alle Klassen des Kerns).
  • <style scoped> in Komponenten geht; zur Laufzeit darf ein Plugin aber nie <style>-Elemente einfügen oder Regeln per insertRule setzen – die Sicherheitsrichtlinie in Produktion blockiert das.
  • Bilder und Schriften bettet der Build als data:-URI ein; als eigene Datei mit ?no-inline am Import bzw. in url() (der Build warnt bei eingebetteten Dateien über 4 KB).

Geltungsbereich: Plugin-Stile wirken nur im Plugin

Die Plattform stellt jede Komponente eines Plugins (Slot oder Seite) in ein eigenes Element <div data-plugin="<id>">, ebenso jeden Landingpage-Baustein und jeden Feldtyp eines Plugins auf den Twig-Seiten (ab 1.2). Beim Bauen bekommt jeder Selektor in dist/plugin.css den Vorsatz :where([data-plugin="<id>"]) – eine Klasse wie hidden, flex oder w-full wirkt damit nur in der Oberfläche des Plugins, auch wenn das Wort zufällig in einem Variablennamen steht: Selektoren treffen nur das Plugin-DOM, seitenweite At-Regeln lehnt die Prüfung ab (siehe unten). Im Plugin selbst gilt Tailwind wie gewohnt: hidden md:flex, dark:, print:, group-hover:, peer-* und Zustände der UI-Bausteine verhalten sich wie in der Plattform. In der Entwicklungsumgebung schreibt der Vite-Dev-Server dieselben Selektoren um.
  • Leere Slot-Komponenten: Rendert eine Komponente nichts (etwa v-if ohne Treffer), bleibt ihre Hülle als leeres, ausgeblendetes Element stehen. In Stapeln mit space-y-* der Plattform kann eine solche Hülle als letztes Element unter dem letzten sichtbaren Eintrag einen zusätzlichen Abstand bewirken. Wer häufig nichts anzeigt, gibt lieber einen knappen Hinweis aus oder registriert den Slot nur, wenn es etwas zu zeigen gibt.
  • Dialoge: UiDialog zeigt seinen Inhalt am Ende der Seite an, außerhalb des Plugin-Elements – Inhalt und Aktionen bekommen das Element dort erneut, Plugin-Klassen wirken also auch im Dialog.
  • Eigenes <Teleport>: Was ein Plugin selbst an eine andere Stelle der Seite teleportiert, liegt außerhalb seines Elements und bekommt seine Stile nicht. Den teleportierten Inhalt deshalb selbst einhüllen: <Teleport to="body"><div :data-plugin="sdk.id">…</div></Teleport>.
  • Vorfahren außerhalb des Plugins greifen nicht: Ein Selektor wie .kompakt .karte oder [data-theme=dark] .karte verlangt den Vorfahren innerhalb des Plugins; Klassen der Plattform-Elemente drumherum zählen nicht mehr. Dasselbe gilt für die Tailwind-Varianten in-* und [.x_&]:. Für den Dunkelmodus dark: verwenden, in eigenen Regeln :root[data-theme=dark] .karte bzw. html[data-theme=dark] .karte (Selektoren, die mit :root, :host oder html beginnen, beziehen sich auf die Seite). group-* und peer-* funktionieren weiter.
  • Eigene Regeln in plugin.css (etwa .mein-kasten { … } oder eigene Theme-Variablen mit @theme) bekommen denselben Vorsatz; Variablen auf :root gelten nur im Plugin. In verschachtelten Regeln steht & am Element selbst (&:hover, .x &, :is(& > *)), nicht nur in :has(&) oder :not(&) – solche Selektoren träfen Vorfahren außerhalb und lehnt der Build ab.
  • Nicht erlaubt und vom Build abgelehnt: @scope (auch verschachtelt), @import von außen, andere Anweisungen als @layer, @charset und @namespace, Zeilenumbrüche in Zeichenketten sowie url(…) ohne Anführungszeichen mit Anführungszeichen, Klammern oder /* darin (dann url("…") schreiben). Unter der Hülle selbst (:root { & ~ * {…} } bzw. :root { ~ * {…} }) kein + oder ~ nach & – das träfe Elemente neben dem Plugin.
  • Seitenweite At-Regeln: @page, @view-transition, @position-try und @font-feature-values gelten immer für die ganze Seite und sind nicht erlaubt. Namen von @keyframes, @counter-style und die Schriftfamilie in @font-face beginnen mit der Plugin-ID (<id>-…), @font-palette-values mit --<id>-…. Ausnahme: die Tailwind-Animationen spin, ping, pulse und bounce (animate-spin …) in genau der Fassung von Tailwind. @property nur für --<id>-* oder für Tailwind-Variablen --tw-* in der Fassung, die Tailwind selbst erzeugt – eine abweichende Fassung (etwa ein anderer Startwert von --tw-border-style) änderte auch Elemente der Plattform.
  • Woher CSS kommen darf: aus Dateien im Plugin-Verzeichnis – frontend/, andere Ordner des Plugins, eigene node_modules des Plugins – und aus <style> in Komponenten; auch ?inline erhält den Geltungsbereich. CSS aus den node_modules der Plattform lehnt npm run build:plugins ab („CSS von außerhalb des Plugins“), weil es im Dev-Server ohne Geltungsbereich gälte: Datei ins Plugin übernehmen.
  • Ältere Builds: Ein dist/plugin.css ohne Geltungsbereich (gebaut vor dieser Regel) lehnt app:plugin:validate ab („… mit einem älteren build-plugins gebaut, neu bauen“); die Plattform lädt es nicht, das Plugin läuft dann ohne seine Stile, und die Plugin-Verwaltung zeigt Stile nicht geladen – neu bauen. Abhilfe: mit dem aktuellen Stand neu bauen (npm run build:plugins <id>) und einspielen.

Bauen

Ergebnis in plugins/<id>/dist/: plugin.js (Einstieg), chunks/ (nachgeladene Teile), plugin.css und ggf. assets/. Der Build prüft anschließend:
  • keine eigene Vue- oder Router-Kopie, nur die vier erlaubten Importe und eigene Chunks;
  • Einstieg höchstens 15 KB (gzip);
  • keine Source-Maps, Dateinamen nur aus A–Z a–z 0–9 _ . / -, nur Endungen, die der Webserver ausliefert (js, css, woff2, png, webp, svg, json);
  • CSS nur mit dem Geltungsbereich des Plugins;
  • Warnungen bei eingefügten Styles, großen eingebetteten Dateien und fehlenden englischen Texten.
app:plugin:validate prüft dist/ noch einmal nach denselben Regeln. In der Entwicklungsumgebung ist kein Build nötig – dort lädt die Seite frontend/index.ts direkt vom Vite-Dev-Server. In Produktion liefert der Webserver die Dateien unter /plugin-assets/<id>/<hash>/… aus; der Hash ändert sich mit jedem neuen Build, Browser speichern die Dateien deshalb dauerhaft zwischen.