Frontend

Serverseitig gerenderte BXM-Views, kleine Alpine.js-Komponenten und eine mit Vite kompilierte SCSS/JS-Pipeline.

Frontend

Wie es zusammenpasst

Das Frontend ist eine hybride, serverseitig gerenderte + Alpine.js-Anwendung - keine SPA, kein clientseitiger Router:

Alpine.js-Architektur

App.js (entry)
  ├── Registers all Alpine stores + components
  ├── Imports Bootstrap JS + Phosphor icons + Tippy.js
  │
  ├── Stores ($store.*)
  │   ├── theme.js     → dark/light mode, syncs data-bs-theme + localStorage
  │   └── sidebar.js   → collapse/open, mobile overlay, localStorage persistence
  │
  └── Components (x-data)
      ├── auth/        → AuthForm, RegisterForm, ForgotPasswordForm, PasswordResetForm
    ├── security/     → AuditLogForm, PermissionsForm, RolesForm, UserDetailForm, UsersForm
    ├── profile/      → PasskeyOnboarding, PreferencesForm, ProfileForm
    ├── settings/     → SettingsForm, SettingsRegistryForm
    └── ui/           → Drawer, GlobalProgress, GlobalToast, Logo, MessageBox, PasswordMeter, PasswordStrength, Switch

Jede Komponente ist ein eigenständiges Modul, das ein Alpine-x-data-Objekt zurückgibt:

export default () => ( {
    visible: true,
    init() {
        setTimeout( () => this.visible = false, 5000 );
    }
} );

<div x-data="messageBox" x-show="visible" x-transition>
    <!-- alert content -->
</div>

SCSS-Struktur

app.scss
  ├── _variables.scss   Bootstrap variable overrides
  ├── bootstrap          Full Bootstrap 5.3 import
  ├── _base.scss         CSS custom properties (light/dark theme)
  ├── components/        9 component partials
  ├── layouts/            Admin + Auth layout partials
  └── views/              Page-specific styles

Vite-Konfiguration

vite.config.mjs verwendet coldbox-vite-plugins coldbox()-Plugin:

• Einstiegspunkte: resources/assets/scss/app.scss und resources/assets/js/App.js
• refresh: appRefreshPaths — automatischer vollständiger Reload bei Handler-/View-Änderungen
• publicDirectory: "public/includes" — wohin gebaute Assets gelangen
• SCSS-Präprozessor mit silenceDeprecations-Flags für neueres Dart Sass (import, global-builtin, color-functions, if-function)

npm run dev        # Vite dev server with HMR
npm run build      # Production build → public/includes/
npm run lint       # ESLint check on resources/assets/js
npm run lint:fix   # ESLint auto-fix
npm run lint:scss  # Stylelint on resources/assets/scss

Serverseitig gerenderte View-Komponenten

Diese BXM-Partials liegen unter app/views/_components/ und werden mit ColdBoxs view()-Helfer gerendert. Sie sind bewusst präsentationsfokussiert: Werte über den args-Struct durchreichen und Geschäftslogik in Handlern oder Services belassen.

Anwendungsgerüst

Authentifizierungs-Partials

UI-Partials

Alpine-Komponenten und Stores

resources/assets/js/App.js registriert die folgenden Namen global bei Alpine. Verwende sie als x-data="name" oder x-data="name(...)" in BXM-Views. Formular-Komponenten senden Remote-Requests an die passenden Handler-Routen und erwarten das CSRF-Token, das von ihrer View geliefert wird, gesendet über fetchWithCsrf() (siehe CSRF bei mutierenden Requests).

Anwendungsgerüst und Authentifizierung

Admin- und Profil-Formulare

UI-Komponenten und globale APIs

Der Quellcode enthält außerdem Header.js, Sidebar.js, TopBarNotifications.js und Logo.js. Ihre Exporte stehen für lokale Imports zur Verfügung, sind aber derzeit nicht bei App.js registriert; registriere sie mit Alpine.data(), bevor du sie als globale x-data-Komponenten verwendest.

Stores, Hilfsfunktionen und magische Eigenschaften

AlpinePlugins.js installiert Collapse, Focus, Mask und Persist. passkeys.js stellt die browserseitige WebAuthn-Integration bereit. Halte neue wiederverwendbare Browser-APIs hier dokumentiert und füge ihre Registrierung/ihren Import zu App.js hinzu, wenn sie global sind.

CSRF bei mutierenden Requests

Jede Komponenten-Aktion, die einen nicht-GET-Request sendet, geht über fetchWithCsrf() (utils/csrf.js), statt fetch() direkt aufzurufen. Dies ist der eine gekapselte Ort, an dem mutierende Requests gebaut werden, sodass sich das Token-Wiederherstellungsverhalten - und alles, was später hinzugefügt wird (Request-/Response-Hooks, globale Header, Telemetrie) - nur hier ändern muss, statt in jeder Komponente, die zufällig den Status ändert.

Warum sich überhaupt erholt werden muss. Der csrfToken einer Komponente wird einmalig eingebettet, wenn ihre View gerendert wird. Der Server kann ihn ungültig machen, während die Seite noch geöffnet ist, auf zwei Arten, die cbcsrfs eigene Dokumentation nennt: csrfField() (der Mixin hinter jedem versteckten csrf-Eingabefeld) erzwingt bei seiner ersten Verwendung pro Request eine Rotation des Session-Tokens, sodass jede Seite, die es rendert - Settings, die Passkey-erforderlich-Seite, die Auth-Seiten - stillschweigend das Token in jedem anderen geöffneten Tab ungültig macht; und ein Token läuft eine feste Zeit nach seiner Erstellung ab, nicht nach dem Laden der Seite, sodass eine spät im Leben eines Tokens gerenderte Seite eines mit nur noch Sekunden Restlaufzeit ausgeliefert bekommen kann. So oder so kann das eingebettete Token einer Komponente veralten, bevor der Benutzer mit dem Tippen fertig ist.

Der Vertrag:

export async function fetchWithCsrf( component, url, method, buildRequest ) { /* ... */ }
export async function refreshCsrfToken( component ) { /* ... */ }

• component ist die Alpine-Komponenteninstanz (übergib this). Sie muss eine veränderliche csrfToken-Eigenschaft bereitstellen - fetchWithCsrf() liest sie, um den Request zu bauen, und überschreibt sie bei einem Retry wegen abgelaufenem Token mit dem aktuellen Token der Session via refreshCsrfToken().
• buildRequest( csrfToken ) liefert die methodenspezifischen RequestInit-Felder (headers, body, credentials usw.) für das gegebene Token. Sie wird beim Retry erneut aufgerufen, muss also den Body jedes Mal frisch aufbauen, statt einen einmal berechneten Wert einzuschließen - das erlaubt es demselben Helfer, URLSearchParams-, JSON.stringify()- und FormData-Bodys gleichermaßen abzudecken.
• Bei einem 403 ruft fetchWithCsrf() refreshCsrfToken() auf und wiederholt, falls es tatsächlich ein neues Token erhalten hat, den Request einmal mit erneut aufgerufenem buildRequest(). Ein zweiter 403 (z. B. ein echter Autorisierungsfehler oder eine vollständig abgelaufene Session) wird unverändert zurückgegeben - Aufrufer brauchen dafür weiterhin ihre normale Fehlerbehandlung.

const response = await fetchWithCsrf( this, "/permissions", "POST", ( csrf ) => ( {
	headers : { "Content-Type": "application/x-www-form-urlencoded" },
	body    : new URLSearchParams( { permission: this.form.permission, csrf } ),
} ) );

const response = await fetchWithCsrf( this, form.action, "POST", ( csrf ) => {
	const formData = new FormData( form );
	formData.set( "csrf", csrf );
	return { body: formData, credentials: "same-origin", headers: { Accept: "application/json" } };
} );

Nur GET/HEAD-Lesezugriffe überspringen fetchWithCsrf() und rufen fetch() direkt auf - sie tragen kein CSRF-Token und können deshalb keinen 403 dafür bekommen. Eine Handvoll cbSecurity-Modul-Endpunkte (die WebAuthn-Passkey-Zeremonie-Routen) werden ebenfalls mit reinem fetch() aufgerufen: Sie authentifizieren sich über die WebAuthn-Zeremonie selbst, nicht über das CSRF-Token dieser App, und liegen daher außerhalb des Geltungsbereichs dieses Helfers. Jede andere Mutation in resources/assets/js/components/ geht über fetchWithCsrf(); halte neue Formular-Komponenten damit konsistent, wenn sie einen Request hinzufügen, der den Server-Status ändert.

Avatare & Branding-Logo

Benutzer-Avatare und das Branding-Logo der Anwendung werden auf der privaten cbfs-assets-Disk gespeichert (siehe Konfiguration) und von Assets.bx ausgeliefert (siehe Handler & Routing), statt als statische Dateien bereitgestellt zu werden.

• Anzeige läuft über das Partial _components/ui/avatar: Es rendert <img src="/avatars/:userId/:size">, wenn hasAvatar wahr ist, und fällt andernfalls auf ein Initialen-<span> zurück. Es ist in Sidebar, Topbar und die Users-Auflistungstabelle eingebunden (serverseitig projiziertes hasAvatar-Feld) sowie inline auf der Users-Detailseite (x-show/x-cloak-Umschaltung basierend auf user.hasAvatar, da der Avatar dieser Seite in einer Alpine-gesteuerten Zusammenfassungskarte statt in einem statischen Partial sitzt).
• Upload/Entfernen des eigenen Avatars des aktuellen Benutzers liegt auf der Profilseite, verwaltet von profileForm (ProfileForm.js): Ein verstecktes Datei-Eingabefeld liest das gewählte Bild als base64-Data-URI (readFileAsDataUrl()) und sendet es per POST an POST /profile/avatar; DELETE /profile/avatar entfernt ihn. Beide erhöhen einen version-Zähler, der als Cache-Busting-Query-Parameter für die ausgelieferte URL verwendet wird, da sich der Dateipfad selbst zwischen Uploads nicht ändert.
• Das Branding-Logo erhält dieselbe Upload-/Entfernen-Behandlung auf der Settings-Seite, über die logoUploader-Komponente (LogoUploader.js) gegen POST/DELETE /settings/logo. Beim Upload ersetzt es den Textfeld-Wert der Einstellung cbAppLogo durch den ausgelieferten Pfad (/branding/logo/lg), und stellt beim Entfernen den konfigurierten Standard wieder her — das manuelle URL-Textfeld und die Live-<img>-Vorschau funktionieren weiterhin genau wie zuvor für jeden, der cbAppLogo stattdessen auf eine externe URL zeigen lassen möchte.
• Beide Upload-Endpunkte akzeptieren dieselben Formen: Bilder werden serverseitig mit BaseSecureHandler.decodeDataUri() dekodiert und dann von ImageService (app/models/system/ImageService.bx) in sm/lg-JPEG-Varianten (Avatar) oder PNG-Varianten (Logo) skaliert/zugeschnitten.