Öffentliche Assets

Öffentliche Assets des CMS-Kerns

Die öffentlichen Assets des WebBlocks-CMS-Kerns liegen unter:

  • public/cms/css/
  • public/cms/js/
  • public/cms/brand/

Diese Pfade sind für CMS-eigenes Laufzeitverhalten und Styling vorgesehen, das mit dem Produkt selbst ausgeliefert werden soll.

CMS-Kern-Assets sind statische Paket-/Laufzeit-Assets. Die CMS-Laufzeit und das Release-Paket dürfen weder Vite, das Laravel-Vite-Plugin, Tailwind, npm, Node, public/build, public/hot, Paket-Lockfiles noch @vite-Blade-Direktiven erfordern. Wenn sich CMS-eigenes CSS oder JavaScript ändert, aktualisieren Sie die versionierten Dateien unter public/cms und im Paket packages/webblocks-cms/public/cms direkt.

Der URL-Namensraum /cms/... ist für diese statischen CMS-Assets reserviert. Er darf nicht als Präfix, Alias oder Redirect für CMS-Admin-Routen wiederverwendet werden. Der kanonische CMS-Admin-Namensraum ist /webadmin/..., einschließlich /webadmin/login, wenn paketeigene CMS-Auth-Routen aktiv sind.

Öffentliche Seitenpfade sind kanonische Seitenübersetzungspfade wie /contact oder /docs/internal-content-api. Sie dürfen /cms/... nicht beanspruchen; dieser Namensraum bleibt ausschließlich statischen Assets vorbehalten. Die alte öffentliche Seitenform /p/... ist ein Legacy-Redirect/-Alias und wird für neue kanonische URLs nicht verwendet.

Diese Trennung schützt gängige Nginx-Deployments mit try_files. Eine Anfrage an /cms/ kann auf das physische Verzeichnis public/cms/ treffen, bevor Laravel die Anfrage erhält; daher darf das CMS-Admin-Routing nicht von /cms abhängen. Das endgültige Admin-Präfix-Design vermeidet die Kollision vollständig und verwendet keine Front-Controller-Übergabe über public/cms/index.php; diese Datei muss sowohl im Installationsstamm unter public/cms/ als auch in den Paket-Assets unter packages/webblocks-cms/public/cms/ fehlen.

Site-Handle-Konvention

Site-Handles sind dateisystemsichere Bezeichner, die für site-bezogene öffentliche Asset-Ordner verwendet werden.

  • Handles sind kleingeschrieben.
  • Handles sind nach Möglichkeit ASCII-sicher.
  • Leerzeichen, Punkte, Schrägstriche, Unterstriche und wiederholte Satzzeichen werden zu einem einzelnen Bindestrich normalisiert.
  • Nur a-z, 0-9 und - bleiben erhalten.
  • Wiederholte Bindestriche werden zu einem zusammengefasst, führende und abschließende Bindestriche werden entfernt.
  • Beispiel-Normalisierungen:
  • ui.webblocksui.com -> ui-webblocksui-com
  • WebBlocks UI -> webblocks-ui
  • Docs Site -> docs-site

Der Bindestrich ist das kanonische Trennzeichen für Site-Handles und public/site/{site_handle}/...-Ordner.

Installations- und Site-Override-Assets

Installations- oder site-spezifische öffentliche Overrides liegen unter dem aufgelösten Site-Handle:

  • public/site/{site_handle}/css/site.css
  • public/site/{site_handle}/js/site.js

Diese Dateien sind Override-Bereich für die aktuelle Installation und sollten nicht für CMS-Kernverhalten verwendet werden.

Falls vorhanden, wird public/site/{site_handle}/css/site.css im öffentlichen <head> für die aktuell aufgelöste öffentliche Site gerendert.

Falls vorhanden, wird public/site/{site_handle}/js/site.js im öffentlichen <head> mit defer für die aktuell aufgelöste öffentliche Site gerendert.

Wenn der Site-Export/-Import mit aktivierter Dateieinbeziehung läuft, werden diese beiden kanonischen Override-Dateien auf Site-Ebene paketiert, sofern vorhanden, und unter dem endgültigen importierten Site-Handle wiederhergestellt. Fehlende site.css- oder site.js-Dateien werden sauber übersprungen. Export/Import paketiert über diesen Pfad auf Site-Ebene keine beliebigen public/site/{site_handle}/...-Bäume.

public/storage ist von public/site/... getrennt. Es ist der von storage:link erstellte öffentliche Laravel-Storage-Symlink für Dateien unter storage/app/public und sollte weder als CMS-Asset-Bereich noch als Site-Override-Asset-Bereich behandelt werden.

Die kanonische Override-Konvention erfordert ein Site-Handle-Segment. Site-Override-Pfade ohne Handle sind nicht kanonisch und sollten nicht für neues Laufzeitverhalten verwendet werden.

CMS-eigene Gast- und E-Mail-Support-Styles liegen jetzt unter public/cms/css/guest.css und public/cms/css/email.css.

CMS-eigene Produktmarken-Assets wie Standard-CMS-Favicons und Kompatibilitätsmarken-Dateien werden aus dem Paketverzeichnis public/cms/brand/ ausgeliefert und in das Installationsstammverzeichnis public/cms/brand/ installiert, veröffentlicht oder synchronisiert. Es handelt sich um Produktidentitäts-Assets für die CMS-Shell, nicht um site-spezifisches Medienbibliothek-Branding und nicht um public/site/...-Overrides. Das kanonische Produktmarken-Set besteht aus logo-mark.svg, logo-mark-dark.svg, logo-mark-on-accent.svg, favicon.svg, favicon-32x32.png, favicon-16x16.png und apple-touch-icon.png. Paketeigene CMS-Auth-Bildschirme und die Admin-Seitenleiste rendern die Marke über eine Inline-SVG-Komponente, die currentColor erbt.

Seiten-Assets

Seitenbezogene CSS- und JS-Dateien können jetzt relational aus page_assets referenziert werden.

  • V1 akzeptiert nur lokale /site/...-Pfade wie /site/webblocks-ui/pages/playground/page.css oder /site/webblocks-ui/pages/playground/page.js
  • Kanonische Seiten-Asset-Pfade sind:
  • public/site/{site_handle}/pages/{page_slug}/page.css
  • public/site/{site_handle}/pages/{page_slug}/page.js
  • CSS-Seiten-Assets werden im öffentlichen <head> gerendert
  • JS-Seiten-Assets werden im öffentlichen <head> mit defer gerendert
  • Nur die besitzende öffentliche Seite rendert ihre konfigurierten Seiten-Assets
  • Seiten-Assets werden nicht in Admin-Layouts gerendert
  • Seiten-Assets werden in page_assets gespeichert, nicht in pages.settings
  • Wenn der Site-Export/-Import Mediendateien einbezieht, werden referenzierte physische /site/...-Dateien ebenfalls paketiert und wiederhergestellt

Öffentliche Plugin-Assets

Aktivierte Plugins können öffentliche Asset-Beiträge über PluginPublicAsset-Registry-Objekte deklarieren. Diese Hooks sind für explizite, zuordenbare Plugin-Assets vorgesehen und sind getrennt von CMS-Kern-Assets, Site-Override-Assets und seitenbezogenen Assets.

  • Plugin-Asset-Handles müssen mit dem Plugin-Handle punktnamensbereichsbasiert sein, etwa analytics-tools.public-css
  • Plugin-CSS kann in den öffentlichen <head> beigesteuert werden
  • Plugin-JS kann in den öffentlichen <head> mit defer, async oder type="module" beigesteuert werden, sofern deklariert
  • Plugin-JS kann an das Ende des öffentlichen Body beigesteuert werden, wenn spätes Laden angemessen ist
  • Assets deaktivierter und inkompatibler Plugins werden weder gesammelt noch gerendert
  • Plugin-Assets müssen weiterhin vom Plugin unter einem plugin-eigenen statischen Namensraum veröffentlicht werden

Der Hook installiert keine Plugin-Pakete, veröffentlicht keine Dateien, streamt keine Assets durch Laravel, erzeugt keine Remote-Discovery und kein Marketplace-Verhalten.

Das interne/Operator-Plugin WebBlocks UI Manager verwendet eine separate CDN-Artefakt-Konvention anstelle des öffentlichen Seiten-Asset-Hooks. Es ist in gewöhnlichen CMS-Installationen nicht gebündelt und nur nach manuellem ZIP-Upload und expliziter Aktivierung verfügbar:

  • Release-Artefakt-Ziele werden versioniert unter public/cdn/webblocks-ui/{version}/... abgelegt
  • Release-Manifeste sind lokale Metadaten für vorbereitete Artefakte und enthalten SHA-256-Prüfsummen
  • Der Dry-Run-Publish validiert Quellpfade, erwartete Dist-Dateien, Prüfsummen, Manifest-Konsistenz, Zielpfad-Sicherheit und Idempotenz, ohne Dateien zu schreiben
  • Der Apply-Publish schreibt nach bestandener Validierung nur in das konfigurierte lokale/projekteigene statische Ziel
  • Vorhandene Dateien mit übereinstimmenden Prüfsummen werden übersprungen, während Prüfsummen-Abweichungen den Publish blockieren
  • Der Workflow deployt nicht auf ein externes Produktions-CDN und ändert keine WebBlocks-UI-Verbrauchs-URLs des CMS-Kerns

Konvention für öffentliche Assets

  • CSS bleibt im öffentlichen <head>
  • Benanntes öffentliches JS bleibt im öffentlichen <head> mit defer
  • Legacy-Zeilen für benanntes JS, die mit body_end gespeichert sind, werden weiterhin akzeptiert, aber öffentliches benanntes JS wird auf <head defer>-Ausgabe normalisiert
  • Öffentliche Block-Renderer dürfen keine Inline-Skripte ausgeben
  • CMS-eigenes öffentliches JS gehört unter public/cms/js/
  • CMS-eigenes öffentliches CSS gehört unter public/cms/css/
  • Plugin-eigene öffentliche Assets müssen plugin-eigene Handles und statische Pfade verwenden und über die Plugin-Asset-Beitrags-Hooks registriert werden, statt das öffentliche CMS-Layout direkt zu verändern
  • Override-JS auf Site-Ebene gehört unter public/site/{site_handle}/js/site.js
  • Override-CSS auf Site-Ebene gehört unter public/site/{site_handle}/css/site.css
  • Die öffentliche Seiten-Shell besitzt den einzigen gemeinsamen Mount #wb-overlay-root.wb-overlay-root für ausgelieferte modalbasierte WebBlocks-UI-Verhalten wie Galerie-Viewer und das öffentliche Suchmodal
  • Öffentliche Partials und vertrauenswürdiger HTML-Inhalt müssen Overlay-Kinder zu dieser kanonischen Root beisteuern, statt konkurrierende Roots wie #wb-public-overlay-root, #public-overlay-root oder #overlay-root zu rendern
  • Die gemeinsame öffentliche Dialogebene darf nicht mit hidden gerendert werden; WebBlocks UI v2.7.12 verwendet diese Ebene für Modal-, Galerie-Viewer- und Toast-Ziele wieder und schaltet die Sichtbarkeit nur am aktiven Backdrop-/Modal- oder Toast-Zustand um, nicht an einem wiederverwendeten Ebenen-Wrapper
  • Der CMS-Kern liefert öffentliches JS nur aus, wenn WebBlocks UI das Verhalten nicht bereits abdeckt; public-search-modal.js bleibt CMS-eigen, während Header-Actions-Modus, Preset-, Akzent- und Dropdown-Verhalten jetzt auf ausgeliefertem WebBlocks-UI-data-wb-*-Verhalten ohne zusätzliche CMS-Laufzeit basieren

Site-Branding-Assets

Öffentliches Favicon und Social-Sharing-Grafiken werden jetzt auf jeder Site aus der gemeinsamen Medienbibliothek ausgewählt.

  • Die Favicon-Ausgabe verwendet die favicon_media_id der aktuell aufgelösten Site, wenn dieses Medienelement eine öffentliche URL hat
  • Open-Graph-Fallback-Bilder verwenden die social_image_media_id der aktuell aufgelösten Site, sofern verfügbar
  • Dies sind site-bezogene Metadaten-Assets, keine CMS-Produktmarken-Assets
  • Die og_image_media_id einer Seitenübersetzung kann das Site-Social-Bild für eine Sprache (Locale) überschreiben, wenn dieses Medienelement eine öffentliche URL hat
  • SEO-Assets auf Seitenebene wirken sich nur auf öffentliche Metadaten aus und ändern das CMS-Admin-Branding nicht
  • Die Projektidentität auf Installationsebene beeinflusst weder das öffentliche Favicon noch öffentliche Metadaten oder site-bezogene Social-Sharing-Assets

WebBlocks-UI-Assets

WebBlocks-UI-Assets werden im öffentlichen CMS-Layout weiterhin vom CDN geladen.

CMS-eigene Standard-CDN-Referenzen sind für das öffentliche und das Admin-Laufzeit-CSS, das Icons-CSS, das Laufzeit-JS und die Standardquelle für die Icon-Manifest-Synchronisierung auf WebBlocks UI v2.7.12 gepinnt. Die Produktions-Layout-Ausgabe verwendet das kanonische jsDelivr-Tag-URL-Format mit den Standard-Dist-Artefakten webblocks-ui.css, webblocks-icons.css und webblocks-ui.js, während die Minifizierungs-Härtung zurückgestellt ist. Browserseitiges CSS und JavaScript darf keine raw.githubusercontent.com-Fallbacks verwenden, da Chrome diese Antworten über ORB- oder MIME-Behandlung blockieren kann.

Diese CDN-Assets sind Teil des UI-Projekts und dürfen nicht innerhalb des CMS-Repositorys bearbeitet oder kompiliert werden. Auf einer Operator-Site installiert, zeichnet WebBlocks UI Manager Release-, Artefakt-, Manifest-, Prüfsummen- und Publish-Run-Metadaten als plugin-eigenes Verhalten auf und kann validierte Dateien in ein konfiguriertes lokales/projekteigenes statisches CDN-Ziel veröffentlichen. Der CMS-Kern konsumiert weiterhin die bestehenden gepinnten CDN-URLs, bis eine separate explizite Migration dieses Verhalten ändert.

Geltungsbereich des Admin-JavaScripts

Das Paket-Admin-Layout hält globales JavaScript bewusst klein: das gepinnte WebBlocks-UI-webblocks-ui.js plus das gemeinsame CMS-Admin-Kern-Asset unter public/cms/js/admin/core.js. Feature-spezifisches Admin-Verhalten muss über den admin-scripts-Stack von der View oder dem Partial geladen werden, die bzw. das die passenden DOM-Hooks rendert.

Beispiele für seitenbezogene Feature-Assets sind Asset-Picker-Panels, Medien-Kopierschaltflächen, sortierbare Builder-Zeilen, Inline- und strukturierte Builder-Editoren, Page-Builder-Modals, Modals zum Löschen von Slot-Blocks, Modals für Seiten-Slot-Quellen, Asset-Steuerelemente auf der Seite „Edit Page“, Bearbeitung von Galerie-Elementen, Rich-Text-Bearbeitung und Umschalter für die Passwortsichtbarkeit im Admin. Diese bleiben CMS-eigene statische Dateien unter public/cms/js/admin/ mit passenden Paket-Quellkopien unter packages/webblocks-cms/public/cms/js/admin/, wo zutreffend. CMS-Admin-Assets verwenden weder Vite, npm, Tailwind, public/build, Hot-Dateien noch irgendeine Frontend-Build-Kette.