# Plugins entwickeln Inhaus lässt sich wie WordPress über Plugins erweitern. Auch die mitgelieferten Funktionen „Neuigkeiten“ und „Termine“ sind Plugins (`plugins-core/news`, `plugins-core/events`) – sie sind die beste Vorlage. ## Aufbau ``` mein-plugin/ plugin.json Manifest (Pflicht) src/Plugin.php Einstiegsklasse, erbt von App\Plugins\Plugin src/… weiterer PHP-Code (PSR-4 unter „namespace“) src/Filament/Resources/ Admin-Seiten (werden automatisch gefunden) src/Filament/Pages/ database/migrations/ laufen bei Aktivierung und nach Updates routes/web.php Routen (Middleware „web“ ist gesetzt) resources/views/ Blade-Views, Namespace = Kürzel: view('mein-plugin::seite') vendor/ eigene Abhängigkeiten – bitte gescoped (Strauss/PHP-Scoper) ``` ### plugin.json ```json { "slug": "mein-plugin", "name": "Mein Plugin", "version": "1.0.0", "description": "Wofür das Plugin da ist.", "author": "Firma GmbH", "namespace": "Firma\\MeinPlugin\\", "class": "Firma\\MeinPlugin\\Plugin", "requires": { "core": ">=0.3.0", "php": ">=8.3", "plugins": ["news"] } } ``` - `slug`: Kleinbuchstaben, Ziffern, Bindestriche; eindeutig. Kürzel mitgelieferter Plugins sind vergeben. - `namespace`: darf nicht mit `App\` beginnen. - `requires.core` / `requires.php`: Versionsbedingungen (`>=`, `<`, `^`, `~`, exakt). - `requires.plugins`: Plugins, die aktiv sein müssen. ### Einstiegsklasse ```php namespace Firma\MeinPlugin; use App\Dashboard\Widgets; use App\Plugins\Hooks; use App\Plugins\Plugin as BasePlugin; use App\Support\Abilities; use App\Support\Navigation; class Plugin extends BasePlugin { public function register(): void { // Menüpunkt im Portal $this->app->make(Navigation::class)->add('mein-plugin', 'Mein Bereich', '/mein-bereich', active: 'mein-plugin.*', sort: 40, icon: 'sparkles'); // Rechte, die im Rollen-Formular erscheinen $this->app->make(Abilities::class)->define('mein-plugin.manage', 'Mein Bereich verwalten', 'Mein Plugin'); } public function boot(): void { Hooks::on('news.post.published', fn ($post) => /* … */ null); Hooks::filter('navigation.items', fn (array $items) => $items); } public function activate(): void {} // nach „Aktivieren“ (Migrationen sind schon gelaufen) public function deactivate(): void {} // vor „Deaktivieren“ public function uninstall(): void {} // bei „Mit Daten löschen“ (Tabellen entfernt der Kern) } ``` ## Rechte und Sichtbarkeit - Globale Rechte: `$abilities->define('schluessel', 'Bezeichnung', 'Gruppe')`, prüfen mit `$user->can('schluessel')`. - Objekt-Rechte: `define(..., resource: 'mein_typ')` plus `$abilities->resourceType('mein_typ', 'Bezeichnung', fn () => [id => 'Name'])`; prüfen mit `$user->can('schluessel', ['mein_typ', $id])` oder einem Modell mit `permissionResource()`. - Zielgruppen: `App\Support\Permissions\Audiences::constrain($query, 'mein_typ', 'tabelle.id', $user)` und im Admin-Formular `App\Filament\Components\AudienceSection::make('mein_typ')`. - Hierarchische Objekttypen (z. B. Seiten, Download-Ordner – Vorlage: `plugins-core/downloads`): `resourceType(..., descendants: fn (array $ids) => [...])`. Rechte mit „inkl. Unterobjekten“ gelten dann auch für alle Nachfahren; ändert sich der Baum, `App\Support\Permissions\Permissions::flush()` aufrufen. - Admin-Seiten: Policies registrieren (`Gate::policy(Model::class, Policy::class)`) bzw. `canAccess()` an Filament-Seiten. ## Pagebuilder-Blöcke Eigene Blöcke erscheinen im Pagebuilder mit Formular und Absicherung – aus der Feldbeschreibung erzeugt: ```php use App\Pagebuilder\{Blocks, BlockType, Field}; $this->app->make(Blocks::class)->add(BlockType::make('mein-plugin.liste', 'Meine Liste', 'list-checks', 'dynamic', 'mein-plugin::Liste') ->fields([ Field::text('title', 'Überschrift', 150), Field::number('count', 'Anzahl', 1, 20, 5), Field::select('layout', 'Darstellung', ['list' => 'Liste', 'cards' => 'Kacheln'], 'list'), ]) ->resolveUsing(fn (array $data, ?User $user, array $context) => ['items' => /* für $user sichtbare Einträge */ []])); ``` - Feldtypen: `text`, `textarea`, `html`, `select`, `toggle`, `number`, `url`, `image`, `people`, `table`, `icon`, `repeater`, `ids`. Unbekannte Felder und Blöcke verwirft der Kern beim Speichern; HTML und Adressen werden bereinigt. - `resolveUsing` liefert die Daten zur Anzeige (bei jedem Aufruf, je Person). `null` blendet den Block aus; Fehler blenden nur diesen Block aus. - Container-Blöcke: `->container(min, max, titled: true, label: 'Tab')`. - Die Vue-Komponente erhält `block` (`data`, `items`, `props`) – Kinder werden mit `inject('pagebuilder:list')` gerendert. `inject('pagebuilder:editing')` ist im Editor wahr. ## Startseite und Profil - Kacheln: `app(App\Dashboard\Widgets::class)->add($key, 'mein-plugin::Kachel', 'aside', sort: 20, props: fn (User $user) => [...], label: 'Name im Admin')`. Bereiche: `top`, `hero`, `feed`, `main`, `aside`. Admins sortieren und blenden Kacheln unter „Startseite“ aus. - Abschnitt in „Profil bearbeiten“: `app(App\Profile\ProfileSections::class)->add($key, 'mein-plugin::Abschnitt', $sort, fn (User $user) => [...])` (Komponente unter `resources/js/profile/`, speichert über eigene Routen). - Optionale mitgelieferte Plugins: `"enabled_by_default": false` in `plugin.json`. - Umbenannte mitgelieferte Plugins: `"replaces": ["alter-slug"]` – der Updater löscht nie, der alte Ordner bleibt liegen und wird so ignoriert. ## Redaktion, Navigation und Benachrichtigungen - Arbeitslisten im Bereich „Redaktion“: `app(App\Editorial\Editorial::class)->add($key, $label, 'mein-plugin::Liste', $sort, $sichtbar, $props)`. Jeder Bereich hat eine eigene Seite (`/redaktion?bereich=`). Ab 0.42.0 zusätzlich `->meta($key, icon: 'lucide-name', todo: fn (User $u) => ['count' => 3, 'label' => 'warten auf Freigabe'], create: fn (User $u) => ['label' => 'Neu', 'href' => '/…'])` – „todo“ erscheint als Zahl in der Leiste und in der Übersicht. Für ältere Portale mit `method_exists($editorial, 'meta')` absichern. - Eigene Menüpunkt-Arten für den Menü-Editor (Admin → Menü), z. B. „Seite“: `app(Navigation::class)->source('typ', 'Bezeichnung', fn () => [id => 'Name'], fn (string $id, array $item, Request $request, ?User $user) => ['label' => …, 'href' => …, 'active' => …, 'children' => [...]] ?: null)`. - Symbole: `App\Support\Icons` (alle Lucide-Symbole lokal; kuratierte Auswahl in `resources/icons/icons.json`, nach Änderungen `npm run icons`), im Portal `` aus `@/components/AppIcon.vue`. - Seitenköpfe im Portal: `@/components/PageHeader.vue` (Titel, Beschreibung, Pfad `breadcrumbs`, Symbol `icon`, Slot „actions“). Die Gestaltung wählt das Portal global (Erscheinungsbild → Seitenköpfe); das Symbol stammt ohne `icon` vom passenden Menüpunkt. Rückwege als `breadcrumbs` angeben, nicht als eigenen Link über dem Kopf – im Kopfband steht der Kopf ganz oben. - Menü-Symbol: `add(…, icon: 'calendar-days')` – ein Lucide-Name; ohne Angabe ein neutrales Symbol. Dynamische Punkte können `'icon'` mitliefern. - Dynamische Menüpunkte: `app(Navigation::class)->provider('mein-plugin', fn (Request $request, ?User $user) => [...])`; feste Menüpunkte können mit `visible: fn (User $user) => …` je Person ausgeblendet werden. - Benachrichtigungen (Glocke im Portal): `$user->notify(new App\Notifications\PortalNotification($titel, $text, $url))`. - Symbol in der Kopfzeile (neben der Glocke): `app(App\Layout\HeaderItems::class)->add('mein-plugin', 'mein-plugin::Symbol', fn (User $user) => ['anzahl' => 3] /* oder null */, sort: 10)`, Komponente unter `resources/js/header/Symbol.vue` (ab 0.39.0). - Wochenüberblick per E-Mail: `app(App\Digest\Digest::class)->add('mein-plugin', 'Überschrift', $sort, fn (User $user, CarbonImmutable $seit) => [['title' => …, 'url' => …, 'meta' => …, 'text' => …]])` – Schlüssel = Plugin-Kürzel (Rollen-Ausschluss gilt), nur Sichtbares liefern, leere Liste = Abschnitt entfällt. - Barrierefreiheit: `` liest Text mit der Sprachausgabe des Geräts vor. Leichte Sprache als zweite Fassung eigener Inhalte: `app(App\Accessibility\EasyLanguage::class)->register('typ', fn (int $id, User $user) => ['can_view' => …, 'can_edit' => …, 'title' => …, 'text' => fn () => '…'])` (Kürzel nur aus Buchstaben), in der Ansicht `easy` aus `EasyLanguage::props('typ', $id, $user, $darfBearbeiten)` an `` übergeben. „text“ ist der Ausgangstext für den KI-Vorschlag – nur, was alle Lesenden sehen. ## Anmeldeverfahren - Eigene Verfahren: Klasse von `App\Identity\IdentityDriver` ableiten und mit `app(App\Identity\IdentityDrivers::class)->add('mein-typ', MeinDriver::class)` anmelden. Vorlagen: `plugins-core/oidc` (Weiterleitung), `plugins-core/ldap` (eigenes Formular), `plugins-core/saml` (POST-Rückkehr, Metadaten). - Der Treiber liefert Formularfelder (`connectionSchema()`), `start()` und `authenticate()` → `App\Identity\ExternalUser`. Konto, Profil, Rollen und Foto übernimmt der Kern; `App\Identity\AttributeProfile` hilft beim Auslesen der Attribute. ## REST-API Eigene Endpunkte in `routes/api.php` erscheinen unter `/api/v1` (nur mit gültigem Token, Rollen-Ausschluss des Plugins gilt). Details und alle Endpunkte des Kerns: docs/API.md. ## Installation und Betrieb - Als ZIP unter **Administration → Plugins** hochladen (ein gemeinsamer Ordner im Archiv ist erlaubt), dann aktivieren. - Kunden-Plugins liegen in `plugins/` und werden von Aktualisierungen nie verändert. - Wirft ein Plugin beim Laden einen Fehler – oder bringt es den PHP-Prozess zum Absturz –, wird es automatisch deaktiviert; der Grund steht auf der Plugins-Seite. - `INHAUS_DISALLOW_FILE_MODS=true` in der `.env` verbietet Hochladen, Aktualisieren und Löschen. ### Updates über `update_url` Mit `"update_url"` in `plugin.json` prüft Inhaus täglich (und auf Knopfdruck unter „Plugins“), ob es eine neue Fassung gibt. Die Adresse muss mit `https://` beginnen und liefert eines dieser Formate: - **Releases von Forgejo, Gitea oder GitHub** – z. B. `https://git.example.org/api/v1/repos///releases/latest`: Version aus `tag_name` (ein führendes „v“ entfällt), Download = erstes ZIP unter den Anhängen, Neuerungen aus dem Release-Text. Das Repository muss ohne Anmeldung lesbar sein. - **Eigenes JSON:** ```json { "version": "1.2.0", "download_url": "https://…/mein-plugin-1.2.0.zip", "sha256": "…", "changelog": "…", "requires": { "core": ">=0.24" } } ``` `sha256` ist optional, wird aber geprüft, wenn angegeben. `requires.core` verhindert Updates, die eine neuere Inhaus-Version brauchen. Das Update ersetzt die Dateien des Plugins; Aktivierung, Einstellungen und Daten bleiben, neue Migrationen laufen sofort. ## Eigene Oberflächen mit dem Plugin-SDK Mitgelieferte Plugins werden mit dem Kern gebaut. Kunden-Plugins bringen ihre Vue-Komponenten **vorkompiliert** mit (`dist/`). Vue, Inertia und die Portal-Bausteine liefert das Portal über eine Import Map. Alle Plugins nutzen also dieselbe Vue-Instanz, dieselben Farben und dasselbe Erscheinungsbild. Auf dem Kundenserver wird dafür weder Node noch ein Build gebraucht. ### Neues Plugin anlegen ```bash php artisan inhaus:make-plugin mav-kalender --name="MAV-Kalender" --author="MAV" cd plugins/mav-kalender npm install npm run build # erzeugt dist/ – danach unter Administration → Plugins aktivieren npm run dev # baut bei jeder Änderung neu (Seite neu laden) npm run package # baut und erzeugt mav-kalender-1.0.0.zip zum Hochladen ``` Mit `--path=…` legen Sie das Plugin außerhalb des Portals an, etwa als eigenes Repository. Dann laden Sie das ZIP unter „Plugins“ hoch. Das Gerüst enthält: - `plugin.json` und die Einstiegsklasse mit einem Menüpunkt und einer Startseiten-Kachel; - einen Controller mit Route; - eine Seite `resources/js/pages/Index.vue` und eine Kachel `resources/js/widgets/Hello.vue`; - `resources/css/style.css`; - `inhaus-sdk/`: die Build-Voreinstellung und die Design-Tokens, kopiert aus dem Portal. ### Komponenten-Arten Name in PHP: immer `slug::Name`. Die Datei ergibt sich aus Art und Name: | Art | Datei | Angemeldet über | |---|---|---| | Seite | `resources/js/pages/Name.vue` | `Inertia::render('slug::Name', [...])` | | Startseiten-Kachel | `resources/js/widgets/Name.vue` | `Widgets::add($key, 'slug::Name', …)` | | Pagebuilder-Block | `resources/js/blocks/Name.vue` | `BlockType::make(…, 'slug::Name')` | | Abschnitt „Profil bearbeiten“ | `resources/js/profile/Name.vue` | `ProfileSections::add(…)` | | Bereich im öffentlichen Profil | `resources/js/profile-panels/Name.vue` | `ProfilePanels::add(…)` | | Redaktions-Liste | `resources/js/editorial/Name.vue` | `Editorial::add(…)` | | Symbol in der Kopfzeile | `resources/js/header/Name.vue` | `HeaderItems::add(…)` (ab 0.39.0) | Welche Dateien es gibt, verzeichnet `dist/inhaus.json`. Das Portal liest diese Datei und liefert Dateien unter `/plugin-assets///…` aus – ausschließlich aus `dist/` aktiver Kunden-Plugins und nur bestimmte Dateitypen (JS, CSS, Bilder, Schriften). Die Version steht in der Adresse, Browser speichern die Dateien deshalb dauerhaft zwischen. Nach einer Änderung also die Version in `plugin.json` erhöhen. Ab 0.45.0 kopiert das Portal diese Dateien beim ersten Aufruf nach `public/plugin-assets///` (gleiche Adresse) – dann liefert sie der Webserver ohne PHP aus. Ist `public/` nicht beschreibbar, bleibt es bei der Auslieferung über PHP. Beim Deaktivieren, Löschen oder erneuten Hochladen wird die Kopie entfernt; `INHAUS_PLUGIN_ASSETS_PATH` setzt ein anderes Ziel. `RichTextEditor` aus `@inhaus/ui` lädt ab 0.45.0 erst nach, wenn er angezeigt wird – Props, `v-model` und Template-Refs funktionieren unverändert. ### Was Plugins importieren dürfen - `vue` – die Vue-Instanz des Portals (`ref`, `computed`, `onMounted` …). - `@inertiajs/vue3` – `router`, `usePage`, `useForm`, `Link`, `Head` … - `@inhaus/ui` – die Bausteine des Portals: - **Layout und Rahmen:** `AppLayout`, `PageHeader`, `Panel`, `EmptyState`. - **Formulare:** `FormField`, `NativeSelect`, `TreeSelect` (durchsuchbarer Baum), `PersonPicker` (Person suchen), `RichTextEditor`, `Button`, `Badge`, `Input`, `Textarea`, `Label`, `Checkbox`, `Switch`. - **Darstellung:** `Skeleton`, `Separator`, `PersonAvatar`, `AppIcon` (alle Lucide-Symbole des Portals), `FileIcon`. - **Mehrteilige Bausteine:** `Dialog…`, `DropdownMenu…`, `Tabs…`, `Tooltip…`, `Accordion…`. - **Hilfsfunktionen:** `http` / `HttpError` (JSON-Aufrufe mit CSRF), `formatDate`, `formatShortDate`, `formatTime`, `formatRelative`, `formatMonthYear`, `colorFor`, `toast`. Diese Liste ist die öffentliche Schnittstelle (`resources/js/sdk/ui.js`): Was dort steht, bleibt innerhalb einer Hauptversion erhalten. Andere Pakete (etwa Lucide) bündelt der Build ins Plugin. Den Rahmen einer Seite – Kopfzeile, Menü, Fußzeile – legt das Portal selbst um jede Plugin-Seite. Ein Plugin kann ihn weder weglassen noch ersetzen, und Änderungen am Rahmen gelten sofort, ohne Plugin-Update. `AppLayout` setzt in Plugins nur noch den Titel im Browser-Tab (und zeichnet den Rahmen nur dort, wo eine Seite außerhalb des Portals gezeigt wird). Überschriften gehören in `PageHeader` – so folgen auch Plugin-Seiten der Einstellung „Seitenköpfe“, und Detailseiten zeigen Titelbilder unter dem Seitenkopf, nicht als eigenen Kopf: ```vue ``` ### Styling Tailwind steht mit den Design-Tokens des Portals zur Verfügung (`bg-card`, `text-brand-text`, `rounded-xl` …), jedoch mit dem Präfix **`ih:`**: `ih:grid ih:gap-6 ih:lg:grid-cols-2`. Das Präfix verhindert, dass die Klassen eines Plugins die des Portals überschreiben. Farben, Ecken und die Schrift folgen damit automatisch dem Erscheinungsbild. Die Portal-Bausteine selbst bringen ihr Styling mit. ### Kacheln ohne eigene Oberfläche Wer keinen Build möchte, füllt die allgemeinen Kacheln des Kerns mit Inhalt: - `core::Quote` – Spruch/Zitat: `title`, `text`, `source`, `note`, `link` (`{label, url}`). Beispiel: das Plugin „Monatsspruch“ (eigenes Repository `inhaus-plugin-monatsspruch`).