Das Beispiel-Plugin „Mitbringliste“ ist ein kleines, kommentiertes Plugin zum Ausprobieren und Kopieren: Mitglieder tragen zu jedem Termin im Kalender ein, was sie mitbringen – Kuchen, Getränke, Salat. Wer den Termin verwaltet, lädt die Liste als CSV oder PDF und erinnert Zusagende, die noch nichts eingetragen haben. Die wichtigsten Erweiterungspunkte kommen dabei je einmal vor. quicktribe-example-plugin.zip herunterladen (Plugin-ID example-plugin, Namespace QuickTribePlugin\ExamplePlugin) – mit Quellen, Tests, Übersetzungen und der gebauten Oberfläche (dist/). Dasselbe Plugin liegt dem Auslieferungspaket unter plugins/example-plugin/ bei – inaktiv und sofort aktivierbar (Variante Docker Compose, siehe Plugins installieren). Wer es nicht braucht, löscht den Ordner.

Was es tut

  • Menüpunkt „Mitbringen“ in der Community: führt auf die Seite „Mitbringliste“ mit den eigenen Einträgen für kommende Termine, einer Einleitung des Teams und dem Hinweis, wie viele Sachen je Termin erlaubt sind.
  • Termin-Ansicht im Kalender: Neben den Angaben zum Termin steht seine Mitbringliste. Mitglieder tragen ein, was sie mitbringen (mit Menge), und entfernen eigene Einträge; wer zugesagt hat, sieht zusätzlich einen Zugangscode des Teams (etwa für Tür oder WLAN). Wer den Termin verwaltet, lädt die Liste als CSV oder PDF und erinnert mit Ohne Eintrag erinnern alle Zusagenden ohne Eintrag. Nach dem Ende des Termins ist die Liste geschlossen.
  • Kalenderliste: Jede Karte zeigt, wie viele Einträge die Liste des Termins hat.
  • Abgesagte Termine: Sagt das Team einen Termin ab (oder wird er abgesagt, weil die Mindestteilnehmerzahl nicht erreicht ist), ruht seine Mitbringliste: Die Einträge bleiben stehen, Neues und „Ohne Eintrag erinnern“ gibt es so lange nicht, im Termin steht ein Hinweis. Findet der Termin doch statt, gilt alles wieder.
  • Benachrichtigungen: Nach einer Zusage kommt die Glocke „Was bringst du mit?“; über jeder Seite der Community erinnert ein Hinweis an eigene Einträge für die nächsten zwei Tage.
  • Zusatzangaben: Im Event-Editor gibt es ein Feld „Hinweis zur Mitbringliste“, im Profil die freiwillige Angabe „Ernährung“, die nur die Person selbst und das Team sehen.
  • Datenschutz: Einträge werden 30 Tage nach dem Ende des Termins gelöscht; der Datenexport enthält sie, eine Kontolöschung entfernt sie.
  • Kursseite: Hat ein Kurs Live-Termine, zeigt seine Seite zu jedem die Zahl der Einträge auf der Mitbringliste.
  • E-Mail-Serien: Der Platzhalter {example-plugin.items} nennt in Serien mit Auslöser „Event-Zusage“, was die Person zum Termin eingetragen hat.
  • Formulare: Der Feldtyp „Ernährung“ fragt in Anmeldeformularen vegetarisch, vegan oder ohne Einschränkung ab.

Was es zeigt

Nicht im Beispiel – beschrieben in den übrigen Kapiteln:
  • Eingaben im Event-Editor (EventInputExtension, Slot calendar.event.editor.fields), siehe Erweiterungen von Kern-Antworten;
  • E-Mails mit eigener Vorlage (mailer(), templates/email/), siehe E-Mails;
  • Dateien: storage(), Uploads, Response::stream und XLSX, siehe Speicher und Response;
  • Lifecycle und die Prüfung von Einstellungen über Felder hinweg (settingsValidator), siehe Lebenszyklus und Einstellungen;
  • Menüpunkte im Benutzermenü und im Plattform-Admin sowie Seiten und Endpunkte ohne Community, siehe Menüpunkte;
  • Erweiterungen und Slots für Mitglieder, Leaderboard, Beiträge und Lektionen, siehe Slots;
  • Eingaben an Beitrag, Kurs und Lektion (InputExtension), der Filter der Rangliste und Landingpage-Bausteine, siehe Filter-Hooks;
  • state(), cache() und limiter(), siehe Einstellungen und Übersetzung, Adressen, Limits, Cache.

Dateien

Auszug aus src/ExamplePlugin.php – alle Erweiterungspunkte stehen in register(), die Arbeit machen kleine Klassen:

Muster zum Übernehmen

  • Sichtbarkeit in jedem Handler: Vor jeder Antwort prüft der Handler, ob der Betrachter das Event sehen darf (events()->viewable()); fremde, gesperrte und unbekannte Events ergeben gleichermaßen 404. CSV, PDF und Erinnerung gibt es nur für Personen, die den Termin verwalten (events()->canManage()).
  • Obergrenze auch bei gleichzeitigen Anfragen: Zählen und Einfügen laufen in db()->transactional(), gezählt wird sperrend (SELECT … FOR UPDATE); bricht die Datenbank eine von zwei gleichzeitigen Transaktionen ab (RetryableException), versucht es der Handler erneut.
  • Oberfläche und Server einig: Ob jemand eintragen, entfernen oder erinnern darf, liefert der Server mit (canAdd, canRemove, canRemind); die Oberfläche zeigt Knöpfe nur danach. Gegen Wettläufe verwerfen Seite und Slot veraltete Antworten über einen Zähler je Ladevorgang.
  • Vorschau-Events (ab Plugin-API 1.3): An einer Vorschau (draft, aus events()->occurrence()) nimmt die Liste keine Einträge an (409, canAdd/canRemind falsch) – zusagen kann dort noch niemand. Die Hooks kommen trotzdem wie bei jedem Event, Einträge eines zurückgestellten Events ziehen mit und verschwinden mit event.deleted.
  • Abgesagte Termine (ab Plugin-API 1.9): „Abgesagt“ ist ein Zustand des einzelnen Termins, den der Kern zurücknehmen kann – Zusagen bleiben bestehen. Das Plugin löscht deshalb nichts und speichert den Zustand nicht selbst: ItemsApi fragt bei jedem Zugriff events()->isCancelled() (Listen: einmal cancelledKeys()), lehnt Eintragen und Erinnern mit 409 ab und liefert cancelled für den Hinweis im Slot; Entfernen bleibt möglich. event.cancelled zieht nur die eigenen offenen Glocken zurück (forget()), event.reinstated hat nichts zu reparieren. Eigene Glocken zu Absage und Rücknahme verschickt das Plugin nicht – der Kern benachrichtigt alle Zusagenden und Wartenden schon per Glocke, Push und E-Mail:
  • Verschobene Termine: Der Kern verschiebt keine Daten der Plugins. event.updated mit scheduleChanged zieht die Einträge eines Einzeltermins auf den neuen Beginn um und löscht bei Serien die Einträge entfallener Termine (occurrenceExists()).
  • Erinnerungen nur an Berechtigte, und so, dass sie ankommen: Die Aufgabe prüft je Person einen Viewer (members()->viewerFor(), canWrite, events()->lockReason()) und ersetzt die ungelesene Glocke „Was bringst du mit?“ mit forget(), bevor sie ohne collapse erinnert:
  • Einzahl und Mehrzahl als eigene Texte statt ICU-Plural, in PHP mit match, in Vue mit einer Bedingung (siehe Übersetzungen).
  • Kurze Beschriftungen im Menü: Menüpunkte stehen neben denen von QuickTribe; „Mitbringen“ ist kurz und verwechselt sich mit keinem Punkt der Plattform.

Ausprobieren

Auf einer Installation (Betreiber und Plattform-Admins):
  1. Im Auslieferungspaket für Docker Compose liegt das Plugin schon unter plugins/example-plugin/. Bei Portainer, Coolify und ohne Docker die ZIP-Datei entpacken und den Ordner example-plugin wie unter Plugins installieren ablegen – mit den Rechten von dort. Fehlt im Ordner das gebaute dist/, nehmen Sie die Fassung aus dem Auslieferungspaket.
  2. Unter Plattform-Admin → Plugins die Mitbringliste (Beispiel-Plugin) aktivieren – oder auf der Konsole php bin/console app:plugin:enable example-plugin.
  3. In einer Community unter Einstellungen → Plugins einschalten – oder php bin/console app:plugin:enable example-plugin --community=<slug>.
  4. Einen kommenden Termin im Kalender öffnen und etwas eintragen. Die Einstellungen der Community öffnet unter Einstellungen → Plugins der Link Einstellungen beim Plugin; die plattformweiten stehen auf seiner Detailseite unter Plattform-Admin → Plugins.
In der Entwicklungsumgebung liegt das Plugin bereits im Quellcode unter plugins/example-plugin/. Die Demo-Daten (php bin/console app:fixtures:load) schalten es plattformweit und in der Community demo ein; die Oberfläche lädt dort ohne Build direkt aus frontend/. Bauen und testen:

Als Vorlage verwenden

  1. Ordner kopieren und umbenennen – der Ordnername ist die neue Plugin-ID (siehe Namensregeln).
  2. In plugin.json id, name, namespace (QuickTribePlugin\<Name>) und entry anpassen, version auf 0.1.0 setzen; in allen PHP-Dateien – auch unter tests/ – den Namespace QuickTribePlugin\ExamplePlugin ersetzen.
  3. In migrations/ die Tabelle umbenennen: plg_<id>__…, dabei wird - in der ID zu _. Den Tabellennamen in den Indexnamen ebenfalls ersetzen.
  4. Im Frontend PLUGIN_ID in frontend/extra.ts setzen und das Literal 'settings.plugin.example-plugin' in SettingsInfo.vue an die neue ID anpassen; in den Tests die Konstanten ID und TABLE und im Playwright-Szenario PLUGIN.
  5. dist/ löschen, nicht benötigte Teile entfernen, neu bauen (npm run build:plugins <id>), php bin/console app:plugin:validate plugins/<id> und die Tests laufen lassen.