Loheide-eu-mitarbeiterplatt.../docs/PLUGINS.md
Friederich Loheide 3addc09c38
All checks were successful
CI / PHP 8.3 / mariadb:10.6 (pull_request) Has been skipped
CI / PHP 8.4 / mariadb:10.6 (pull_request) Has been skipped
CI / PHP 8.3 / mariadb:11.4 (pull_request) Has been skipped
CI / PHP 8.4 / mariadb:11.4 (pull_request) Has been skipped
CI / PHP 8.3 / mysql:8.0 (pull_request) Has been skipped
CI / PHP 8.4 / mysql:8.0 (pull_request) Has been skipped
CI / PHP 8.3 / mysql:8.4 (pull_request) Has been skipped
CI / PHP 8.4 / mysql:8.4 (pull_request) Has been skipped
CI / Browser-Tests (pull_request) Successful in 8m33s
CI / Bekannte Sicherheitslücken in Paketen (pull_request) Successful in 9m8s
CI / PHP 8.3 / mysql:8.4-1 (pull_request) Successful in 17m55s
CI / Build-Artefakte aktuell (pull_request) Successful in 9m50s
Frag das Portal durchsucht alles, neue Demo-Inhalte (0.66.0)
- Wissensquellen: Termine, Downloads, Formulare, Stellen, Ideen, Umfragen,
  Personen, eigene IT-Tickets/Geräte (OpenNIT, je Anfrage zwischengespeichert)
- Ranking mit IDF, Abfrage je Begriff, Abkürzungen als ganze Wörter,
  LIKE unabhängig von Groß-/Kleinschreibung (JSON-Spalten), Datum im Prompt
- Demo-Inhalte für einen Träger der Eingliederungshilfe (DemoData),
  mehrseitige PDFs, vorhandene Inhalte je Bereich entfernen

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-07 20:01:00 +00:00

405 lines
22 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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=<key>`). 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 `<AppIcon name="…" />` 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: `<ReadAloud :source="element" />` 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 `<EasyLanguageBar v-model="leicht" :easy="easy" :read-source="…" />`
übergeben. „text“ ist der Ausgangstext für den KI-Vorschlag – nur, was alle Lesenden sehen.
## Meine Aufgaben
Was jetzt Handlung braucht – bestätigen, abstimmen, annehmen, freigeben –
meldet ein Plugin an `App\Tasks\Tasks`. Es erscheint auf der Startseite
(„Meine Aufgaben“) und unter `/aufgaben`:
```php
if (class_exists(\App\Tasks\Tasks::class)) { // ab Inhaus 0.53.0
$this->app->make(\App\Tasks\Tasks::class)->add('gruppen', fn (User $user) => [
['title' => 'Einladung in „Laufgruppe“ annehmen', 'url' => '/gruppen/laufgruppe',
'meta' => 'Gruppen', 'icon' => 'users-round', 'due' => null],
], sort: 40);
}
```
Nur echte Aufgaben, keine Hinweise. `due` (Datum) sortiert nach vorn und
markiert Überfälliges. Offene Punkte aus der Redaktion (`Editorial::meta(todo:)`)
erscheinen automatisch. Ist das Plugin für eine Rolle gesperrt, liefert es nichts.
## Feed der Mitarbeiter-App
In der Oberfläche „Mitarbeiter-App“ steht in der Mitte der Startseite ein Feed.
Plugins steuern Beiträge bei (ab Inhaus 0.54.0):
```php
if (class_exists(\App\Feed\Feed::class)) {
$this->app->make(\App\Feed\Feed::class)->add('gruppen', fn (User $user, ?CarbonImmutable $before, int $limit) =>
Post::query()->sichtbarFür($user)
->when($before, fn ($q) => $q->where('created_at', '<', $before))
->latest()->limit($limit)->get()
->map(fn (Post $post) => [
'id' => 'gruppen-'.$post->id, // eindeutig
'time' => $post->created_at, // Sortierung
'actor' => \App\Feed\Feed::person($post->user),
'action' => 'hat etwas geteilt', // oder 'context' => ['label' => 'Laufgruppe', 'url' => …]
'badge' => null, 'title' => null, 'text' => $post->body,
'image_url' => null, 'images' => [/* bis zu 4 Bildadressen */],
'url' => …, 'stats' => ['likes' => 3, 'comments' => 1],
'cta' => ['label' => 'Ansehen', 'url' => …],
]));
}
```
Je Aufruf höchstens `$limit` Einträge, älter als `$before`, neueste zuerst – der
Feed mischt und blättert selbst. Schnellaktionen über dem Feed ergänzt
`Hooks::filter('feed.actions', fn (array $actions, User $user) => [...$actions, ['label' => …, 'url' => …, 'icon' => …]])`.
## Frag das Portal (Wissensquellen)
„Frag das Portal“ beantwortet Fragen kurz aus den Inhalten, die die fragende
Person sehen darf – mit Quellen (ab Inhaus 0.64.0, braucht den KI-Assistenten).
Mitgeliefert sind Seiten, QM-Dokumente, Glossar, Neuigkeiten, Termine, Downloads,
Formulare, Stellen, Ideenbox, Umfragen, das Personenverzeichnis und die eigenen
IT-Tickets und Geräte (IT-Service). Plugins mit Wissen (z. B. Anleitungen, FAQ)
melden sich als Quelle an:
```php
if (class_exists(\App\Ask\Knowledge::class)) {
$this->app->make(\App\Ask\Knowledge::class)->add('faq', 'Häufige Fragen', function (User $user, array $terms, int $limit) {
$query = Frage::query()->sichtbarFür($user);
\App\Ask\Knowledge::whereAny($query, ['frage', 'antwort'], $terms); // mindestens ein Begriff
return $query->limit($limit)->get()->map(fn (Frage $f) => [
'title' => $f->frage,
'url' => route('faq.show', $f),
'text' => \App\Ask\Knowledge::plain($f->antwort_html), // voller Klartext
'meta' => $f->bereich, // optional
])->all();
});
}
```
Der Schlüssel ist der Plugin-Slug – ist das Plugin für eine Rolle ausgeblendet,
fragt der Kern die Quelle für diese Personen gar nicht erst. Die Begriffe sind
klein geschrieben und grob gekürzt („beantrag“, „urlaub“); `Knowledge::whereAny()`
sucht kurze Begriffe wie „it“ nur als ganzes Wort. Der Kern fragt jede Quelle einmal
mit allen Begriffen und zusätzlich je Begriff – teure Abfragen (z. B. externe
Schnittstellen) also innerhalb der Anfrage zwischenspeichern. Den passenden Ausschnitt
wählt der Kern; liefern Sie nur, was die Person sehen darf.
## 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, wird es automatisch deaktiviert; der
Grund steht auf der Plugins-Seite. Bricht PHP beim Laden mit einem schweren Fehler
ab (z. B. Speicher erschöpft), wird das vermerkt; beim zweiten Mal binnen einer
Stunde wird es deaktiviert. Während eines Updates schaltet nichts ab.
- `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/<owner>/<repo>/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/<slug>/<version>/…` 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/<slug>/<version>/` (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`.
- **Listen:** `ListToolbar` (Filter-Knöpfe mit Anzahl, Suche mit Verzögerung,
Sortierung, Umschalter Kacheln/Liste; eigene Bedienelemente im Slot) und
`useListView(schlüssel)` – merkt die gewählte Ansicht im Browser. Listen-Seiten
sollen diese Leiste nutzen, damit alle Bereiche gleich bedient werden.
- **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 – Kopfzeile, Menü, Seitenkopf-Bereich, Fußzeile – legt das Portal
selbst um jede Plugin-Seite, und er bleibt beim Seitenwechsel stehen. Ein Plugin
kann ihn weder weglassen noch ersetzen; Änderungen am Aussehen gelten sofort,
ohne Plugin-Update. Die Seite meldet dem Rahmen nur, was er zeigen soll:
- `AppLayout` – Titel im Browser-Tab und die **Seitenvorlage** (`width`):
`default` (volle Breite), `medium` (Lesebreite, z. B. Detailseiten ohne
Seitenleiste), `narrow` (Formulare), `app` (füllt die Höhe, ohne Fußzeile –
z. B. ein Messenger). `:header="false"` nur für Seiten, die bewusst ohne
Seitenkopf auskommen.
- `PageHeader` – Pfad, Titel, Beschreibung und Aktionen. Er erscheint nicht an
der Stelle im Template, sondern im festen Kopfbereich des Rahmens, ausgerichtet
an der Seitenvorlage, und folgt der Einstellung „Seitenköpfe“. Zeigt eine Seite
keinen, setzt der Rahmen einen schlichten mit ihrem Titel. Eigene Überschriften
oder Titelbild-Köpfe gehören nicht in Plugins; Titelbilder stehen unter dem
Seitenkopf.
```vue
<script setup>
import { AppLayout, PageHeader, Panel } from '@inhaus/ui';
</script>
<template>
<AppLayout title="MAV-Kalender">
<PageHeader title="MAV-Kalender" />
<Panel title="Nächste Sitzungen">…</Panel>
</AppLayout>
</template>
```
### 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`).