Frontend

Vues BXM rendues côté serveur, petits composants Alpine.js, et un pipeline SCSS/JS compilé par Vite.

Frontend

Comment tout s'articule

Le frontend est une application hybride rendue côté serveur + Alpine.js - pas de SPA, pas de routeur côté client :

Architecture Alpine.js

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

Chaque composant est un module autonome retournant un objet Alpine x-data :

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

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

Structure SCSS

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

Configuration Vite

vite.config.mjs utilise le plugin coldbox() de coldbox-vite-plugin :

• Points d'entrée : resources/assets/scss/app.scss et resources/assets/js/App.js
• refresh: appRefreshPaths — rechargement complet automatique lors des changements de handler/vue
• publicDirectory: "public/includes" — où atterrissent les assets construits
• Préprocesseur SCSS avec des drapeaux silenceDeprecations pour les versions récentes de 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

Composants de vue rendus côté serveur

Ces partials BXM vivent sous app/views/_components/ et sont rendus avec le helper view() de ColdBox. Ils sont volontairement centrés sur la présentation : faites passer les valeurs par la structure args et gardez la logique métier dans les handlers ou les services.

Coque de l'application

Partials d'authentification

Partials d'interface

Composants et stores Alpine

resources/assets/js/App.js enregistre les noms suivants globalement auprès d'Alpine. Utilisez-les comme x-data="name" ou x-data="name(...)" dans les vues BXM. Les composants de formulaire effectuent des requêtes distantes vers les routes de handler correspondantes et attendent le jeton CSRF fourni par leur vue, envoyé via fetchWithCsrf() (voir CSRF sur les requêtes mutatives).

Coque de l'application et authentification

Formulaires d'administration et de profil

Composants d'interface et API globales

Le code source contient aussi Header.js, Sidebar.js, TopBarNotifications.js, et Logo.js. Leurs exports sont disponibles pour des imports locaux, mais ils ne sont pas actuellement enregistrés par App.js ; enregistrez-les avec Alpine.data() avant de les utiliser comme composants x-data globaux.

Stores, utilitaires, et propriétés magiques

AlpinePlugins.js installe Collapse, Focus, Mask, et Persist. passkeys.js fournit l'intégration WebAuthn côté navigateur. Gardez ici la documentation des nouvelles API navigateur réutilisables et ajoutez leur enregistrement/import à App.js lorsqu'elles sont globales.

CSRF sur les requêtes mutatives

Chaque action de composant qui envoie une requête non-GET passe par fetchWithCsrf() (utils/csrf.js) plutôt que d'appeler fetch() directement. C'est l'unique endroit encapsulé où les requêtes mutatives sont construites, si bien que le comportement de récupération du jeton - et tout ce qui lui sera ajouté plus tard (crochets de requête/réponse, en-têtes globaux, télémétrie) - n'a besoin de changer qu'ici plutôt que dans chaque composant qui mute l'état.

Pourquoi il doit se rétablir. Le csrfToken d'un composant est intégré une seule fois, au rendu de sa vue. Le serveur peut l'invalider pendant que la page est encore ouverte, de deux façons que la documentation de cbcsrf mentionne elle-même : csrfField() (le mixin derrière chaque champ caché csrf) force la rotation du jeton de la session à sa première utilisation par requête, donc toute page qui le rend - Paramètres, la page de passkey requise, les pages d'authentification - invalide silencieusement le jeton présent dans tout autre onglet ouvert ; et un jeton expire un temps fixe après sa création, pas après le chargement de la page, donc une page rendue tard dans la vie d'un jeton peut en recevoir un avec seulement quelques secondes restantes. Dans les deux cas, le jeton intégré d'un composant peut devenir périmé avant que l'utilisateur ait fini de saisir.

Le contrat :

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

• component est l'instance du composant Alpine (passez this). Elle doit exposer une propriété csrfToken mutable - fetchWithCsrf() la lit pour construire la requête et, en cas de nouvelle tentative sur jeton périmé, l'écrase avec le jeton actuel de la session via refreshCsrfToken().
• buildRequest( csrfToken ) retourne les champs RequestInit spécifiques à la méthode (headers, body, credentials, etc.) pour le jeton donné. Elle est rappelée lors de la nouvelle tentative, donc elle doit reconstruire le corps à chaque fois plutôt que de fermer sur une valeur calculée une seule fois - c'est ce qui permet au même helper de couvrir aussi bien les corps URLSearchParams, JSON.stringify(), et FormData.
• Sur un 403, fetchWithCsrf() appelle refreshCsrfToken() et, s'il a obtenu un jeton véritablement nouveau, rejoue la requête une fois avec buildRequest() rappelée. Un second 403 (par ex. un véritable échec d'autorisation, ou une session entièrement expirée) est retourné tel quel - les appelants ont toujours besoin de leur gestion d'erreur normale pour ce cas.

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" } };
} );

Seules les lectures GET/HEAD évitent fetchWithCsrf() et appellent fetch() directement - elles ne portent aucun jeton CSRF et ne peuvent pas renvoyer un 403 pour cette raison. Une poignée de points de terminaison du module cbSecurity (les routes de la cérémonie de passkey WebAuthn) sont également appelées avec un fetch() simple : elles s'authentifient via la cérémonie WebAuthn elle-même, pas via le jeton CSRF de cette application, elles sont donc hors du périmètre de ce helper. Toute autre mutation dans resources/assets/js/components/ passe par fetchWithCsrf() ; gardez les nouveaux composants de formulaire cohérents avec cela lorsqu'ils ajoutent une requête qui change l'état du serveur.

Avatars & logo de marque

Les avatars utilisateur et le logo de marque de l'application sont stockés sur le disque cbfs privé assets (voir Configuration) et diffusés par Assets.bx (voir Handlers & Routage) plutôt que servis comme fichiers statiques.

• L'affichage passe par le partial _components/ui/avatar : il rend <img src="/avatars/:userId/:size"> lorsque hasAvatar est vrai, et se rabat sur un <span> d'initiales sinon. Il est câblé dans la barre latérale, la barre supérieure, et le tableau de liste des Utilisateurs (champ hasAvatar projeté côté serveur), et en ligne dans la page de détail des Utilisateurs (bascule x-show/x-cloak sur user.hasAvatar, car l'avatar de cette page se trouve dans une carte récapitulative pilotée par Alpine plutôt que dans un partial statique).
• Le téléversement/suppression de l'avatar de l'utilisateur courant vit sur la page Profil, géré par profileForm (ProfileForm.js) : un champ de fichier caché lit l'image sélectionnée comme un URI de données en base64 (readFileAsDataUrl()) et l'envoie à POST /profile/avatar ; DELETE /profile/avatar la supprime. Les deux incrémentent un compteur version utilisé comme paramètre de requête anti-cache sur l'URL diffusée, puisque le chemin de fichier lui-même ne change pas entre les téléversements.
• Le logo de marque reçoit le même traitement de téléversement/suppression sur la page Paramètres, via le composant logoUploader (LogoUploader.js) contre POST/DELETE /settings/logo. Il remplace la valeur du champ de saisie texte du paramètre cbAppLogo par le chemin diffusé (/branding/logo/lg) au téléversement, et restaure la valeur par défaut configurée à la suppression — le champ de saisie texte d'URL manuelle et l'aperçu <img> en direct continuent de fonctionner exactement comme avant pour quiconque souhaite pointer cbAppLogo vers une URL externe à la place.
• Les deux points de terminaison de téléversement acceptent les mêmes formats : les images sont décodées côté serveur avec BaseSecureHandler.decodeDataUri(), puis redimensionnées/recadrées en variantes JPEG sm/lg (avatar) ou PNG (logo) par ImageService (app/models/system/ImageService.bx).