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 überdefinePlugin); er darfasyncsein. - 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 nurvue, 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.globalgilt für Endpunkte ohne Community (/api/plugins/<id>). Auf Seiten ohne Community gibt es nurapi.global. - Der Client setzt CSRF-Kopfzeile und Sitzung selbst.
options:signal(Abbrechen) undidempotencyKey(eigener Schlüssel odertrue= zufällig, für Aktionen, die nicht doppelt laufen dürfen). upload()schicktmultipart/form-dataper POST mit Fortschritt; mehrere Dateien als<feld>[], weitere Felder überfields. Die Grenzen prüft der Server (UploadRule).- Fehler kommen als
ApiProblem(aus@quicktribe/sdk) mitstatus,message,violations(Feldpfad → Meldung, passend fürUiField) undretryAfterSecondsbei429.
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 Propscontext (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).extrabeginnt immer leer – bestehende Werte lädt das Plugin über die eigene Schnittstelle.violationsenthält nur die Meldungen dieses Plugins, ohne das Präfixextra.<pluginId>.. - Editoren für Beitrag, Kurs und Lektion (ab 1.2): gleiche Regeln wie im Event-Editor – der Block geht als
extraim Request mit, die Eingabe nimmt eineInputExtensionentgegen (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 mitpage() (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ährendinstall(); 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 übersdk.urlsmit<a href>(anderer Bereich = neue Seite).
Stores
Ein Plugin darf eigene Pinia-Stores anlegen – in derselben Pinia wie der Kern, deshalb mit der IDplugin.<id>.<name>:
UI-Bausteine
Dieselben Komponenten wie im Kern – gleiche Optik, Themes und Dunkelmodus:v-html) ist in Plugin-Oberflächen verboten (ESLint).
Übersetzungen
Deutsch ist Quelltext und Schlüssel, Englisch steht intranslations/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.tsimportiertplugin.css. Gebaut entsteht genau eine Dateidist/plugin.cssmit den Klassen, die das Plugin benutzt.- Vorlagen für Feldtypen und Bausteine (ab 1.2): Ihre Klassen erzeugt Tailwind nur, wenn
plugin.cssdie Ordner../templates/formsbzw.../templates/blocksals@sourcenennt. Nie das ganze../templates: PDF- und Mail-Vorlagen enthalten Wörter wiefixed, aus denen sonst Klassen entstünden. Der Build undapp:plugin:validatewarnen bei fehlender Angabe. - Alle Klassen erlaubt:
hidden,block,flex,grid-cols-2,fixed,overflow-x-autound 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 indist/plugin.css, verändern aber die Plattform nicht. @referencezeigt immer auftailwind-theme.css, nie auftailwind.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 perinsertRulesetzen – die Sicherheitsrichtlinie in Produktion blockiert das.- Bilder und Schriften bettet der Build als
data:-URI ein; als eigene Datei mit?no-inlineam Import bzw. inurl()(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-ifohne Treffer), bleibt ihre Hülle als leeres, ausgeblendetes Element stehen. In Stapeln mitspace-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:
UiDialogzeigt 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 .karteoder[data-theme=dark] .karteverlangt den Vorfahren innerhalb des Plugins; Klassen der Plattform-Elemente drumherum zählen nicht mehr. Dasselbe gilt für die Tailwind-Variantenin-*und[.x_&]:. Für den Dunkelmodusdark:verwenden, in eigenen Regeln:root[data-theme=dark] .kartebzw.html[data-theme=dark] .karte(Selektoren, die mit:root,:hostoderhtmlbeginnen, beziehen sich auf die Seite).group-*undpeer-*funktionieren weiter. - Eigene Regeln in
plugin.css(etwa.mein-kasten { … }oder eigene Theme-Variablen mit@theme) bekommen denselben Vorsatz; Variablen auf:rootgelten 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),@importvon außen, andere Anweisungen als@layer,@charsetund@namespace, Zeilenumbrüche in Zeichenketten sowieurl(…)ohne Anführungszeichen mit Anführungszeichen, Klammern oder/*darin (dannurl("…")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-tryund@font-feature-valuesgelten immer für die ganze Seite und sind nicht erlaubt. Namen von@keyframes,@counter-styleund die Schriftfamilie in@font-facebeginnen mit der Plugin-ID (<id>-…),@font-palette-valuesmit--<id>-…. Ausnahme: die Tailwind-Animationenspin,ping,pulseundbounce(animate-spin…) in genau der Fassung von Tailwind.@propertynur 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, eigenenode_modulesdes Plugins – und aus<style>in Komponenten; auch?inlineerhält den Geltungsbereich. CSS aus dennode_modulesder Plattform lehntnpm run build:pluginsab („CSS von außerhalb des Plugins“), weil es im Dev-Server ohne Geltungsbereich gälte: Datei ins Plugin übernehmen. - Ältere Builds: Ein
dist/plugin.cssohne Geltungsbereich (gebaut vor dieser Regel) lehntapp:plugin:validateab („… 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
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.