Asset pubblici

Asset pubblici del core del CMS

Gli asset pubblici del core di WebBlocks CMS si trovano in:

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

Questi percorsi sono destinati al comportamento a runtime e allo stile di proprietà del CMS che devono essere distribuiti con il prodotto stesso.

Gli asset del core del CMS sono asset statici di pacchetto/runtime. Il runtime del CMS e il pacchetto di rilascio non devono richiedere Vite, il plugin Vite di Laravel, Tailwind, npm, Node, public/build, public/hot, file di lock dei pacchetti o direttive Blade @vite. Quando cambiano CSS o JavaScript di proprietà del CMS, aggiornate direttamente i file tracciati sotto public/cms e nel pacchetto packages/webblocks-cms/public/cms.

Lo spazio dei nomi URL /cms/... è riservato a questi asset statici del CMS. Non deve essere riutilizzato come prefisso di rotta, alias o redirect dell'amministrazione del CMS. Lo spazio dei nomi canonico dell'amministrazione del CMS è /webadmin/..., incluso /webadmin/login quando sono attive le rotte di autenticazione del CMS di proprietà del pacchetto.

I percorsi delle pagine pubbliche sono percorsi canonici di Page Translation come /contact o /docs/internal-content-api. Non devono rivendicare /cms/...; quello spazio dei nomi resta riservato ai soli asset statici. La vecchia forma di pagina pubblica /p/... è un redirect/alias legacy e non viene utilizzata per i nuovi URL canonici.

Questa separazione protegge i comuni deployment Nginx con try_files. Una richiesta a /cms/ può corrispondere alla directory fisica public/cms/ prima che Laravel riceva la richiesta, quindi il routing dell'amministrazione del CMS non deve dipendere da /cms. Il design finale del prefisso di amministrazione evita del tutto la collisione e non utilizza un passaggio al front controller public/cms/index.php; quel file deve restare assente sia da public/cms/ nella radice dell'installazione sia dagli asset del pacchetto packages/webblocks-cms/public/cms/.

Convenzione degli handle di sito

Gli handle di sito sono identificatori sicuri per il filesystem utilizzati per le cartelle di asset pubblici circoscritte al sito.

  • Gli handle sono in minuscolo.
  • Gli handle sono sicuri in ASCII ove possibile.
  • Spazi, punti, barre, trattini bassi e punteggiatura ripetuta sono normalizzati in un singolo trattino.
  • Restano solo a-z, 0-9 e -.
  • I trattini ripetuti sono ridotti a uno e i trattini iniziali o finali vengono rimossi.
  • Esempi di normalizzazione:
  • ui.webblocksui.com -> ui-webblocksui-com
  • WebBlocks UI -> webblocks-ui
  • Docs Site -> docs-site

Il trattino è il separatore canonico per gli handle di sito e per le cartelle public/site/{site_handle}/....

Asset a livello di installazione e di override del sito

Gli override pubblici specifici dell'installazione o del sito si trovano sotto l'handle di sito risolto:

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

Questi file sono uno spazio di override per l'installazione corrente e non devono essere utilizzati per il comportamento del core del CMS.

Quando è presente, public/site/{site_handle}/css/site.css viene generato nel <head> pubblico del sito pubblico attualmente risolto.

Quando è presente, public/site/{site_handle}/js/site.js viene generato nel <head> pubblico con defer per il sito pubblico attualmente risolto.

Quando l'esportazione/importazione del sito viene eseguita con l'inclusione dei file attiva, questi due file canonici di override a livello di sito vengono impacchettati se presenti e ripristinati sotto l'handle di sito importato finale. I file site.css o site.js mancanti vengono ignorati senza errori. L'esportazione/importazione non impacchetta alberi arbitrari public/site/{site_handle}/... attraverso questo percorso a livello di sito.

public/storage è distinto da public/site/.... È il collegamento simbolico allo storage pubblico di Laravel creato da storage:link per i file sotto storage/app/public e non deve essere trattato come spazio per gli asset del CMS né come spazio per gli asset di override del sito.

La convenzione canonica di override richiede un segmento con l'handle di sito. I percorsi di override del sito privi di handle non sono canonici e non devono essere utilizzati per nuovi comportamenti a runtime.

Gli stili di supporto per ospiti ed email di proprietà del CMS si trovano ora sotto public/cms/css/guest.css e public/cms/css/email.css.

Gli asset di brand del prodotto di proprietà del CMS, come le favicon predefinite del CMS e i file del marchio di compatibilità, vengono distribuiti dal pacchetto public/cms/brand/ e sono installati, pubblicati o sincronizzati in public/cms/brand/ nella radice dell'installazione. Si tratta di asset di identità del prodotto per la shell del CMS, non del branding della libreria media specifico del sito e non di override in public/site/.... L'insieme canonico del brand di prodotto è logo-mark.svg, logo-mark-dark.svg, logo-mark-on-accent.svg, favicon.svg, favicon-32x32.png, favicon-16x16.png e apple-touch-icon.png. Le schermate di autenticazione del CMS di proprietà del pacchetto e la barra laterale di amministrazione generano il marchio tramite un componente SVG inline che eredita currentColor.

Asset di pagina

I file CSS e JS circoscritti alla pagina possono ora essere referenziati in modo relazionale da page_assets.

  • La V1 accetta solo percorsi locali /site/... come /site/webblocks-ui/pages/playground/page.css o /site/webblocks-ui/pages/playground/page.js
  • I percorsi canonici degli asset di pagina sono:
  • public/site/{site_handle}/pages/{page_slug}/page.css
  • public/site/{site_handle}/pages/{page_slug}/page.js
  • Gli asset CSS di pagina vengono generati nel <head> pubblico
  • Gli asset JS di pagina vengono generati nel <head> pubblico con defer
  • Solo la pagina pubblica proprietaria genera gli asset di pagina configurati
  • Gli asset di pagina non vengono generati nei layout di amministrazione
  • Gli asset di pagina sono memorizzati in page_assets, non in pages.settings
  • Quando l'esportazione/importazione del sito include i file media, anche i file fisici /site/... referenziati vengono impacchettati e ripristinati

Asset pubblici dei plugin

I plugin abilitati possono dichiarare contributi di asset pubblici tramite oggetti di registro PluginPublicAsset. Questi hook sono pensati per asset di plugin espliciti e attribuibili e sono distinti dagli asset del core del CMS, dagli asset di override del sito e dagli asset circoscritti alla pagina.

  • gli handle degli asset di plugin devono avere lo spazio dei nomi con punto dell'handle del plugin, come analytics-tools.public-css
  • il CSS del plugin può essere contribuito al <head> pubblico
  • il JS del plugin può essere contribuito al <head> pubblico con defer, async o type="module" ove dichiarato
  • il JS del plugin può essere contribuito alla fine del body pubblico quando è opportuno un caricamento tardivo
  • gli asset di plugin disabilitati e incompatibili non vengono raccolti né generati
  • gli asset del plugin devono comunque essere pubblicati dal plugin sotto uno spazio dei nomi statico di sua proprietà

L'hook non installa pacchetti di plugin, non pubblica file, non trasmette asset attraverso Laravel, non crea discovery remoto né comportamenti da marketplace.

Il plugin interno/per operatori WebBlocks UI Manager utilizza una convenzione separata per gli artefatti CDN invece dell'hook per gli asset di pagina pubblica. Non è incluso nelle normali installazioni del CMS ed è disponibile solo dopo il caricamento manuale dello ZIP e l'abilitazione esplicita:

  • le destinazioni degli artefatti di rilascio sono versionate sotto public/cdn/webblocks-ui/{version}/...
  • i manifest di rilascio sono metadati locali degli artefatti preparati e includono checksum SHA-256
  • la pubblicazione dry-run convalida percorsi di origine, file dist attesi, checksum, coerenza del manifest, sicurezza dei percorsi di destinazione e idempotenza senza scrivere file
  • la pubblicazione effettiva scrive solo nella destinazione statica locale/di proprietà del progetto configurata, dopo il superamento della convalida
  • i file esistenti con checksum corrispondenti vengono ignorati, mentre le discrepanze di checksum bloccano la pubblicazione
  • il flusso di lavoro non effettua deployment su una CDN di produzione esterna né modifica gli URL di consumo di WebBlocks UI del core del CMS

Convenzione degli asset pubblici

  • Il CSS resta nel <head> pubblico
  • Il JS pubblico con nome resta nel <head> pubblico con defer
  • Le righe JS con nome legacy memorizzate con body_end sono ancora accettate, ma il JS pubblico con nome viene normalizzato in output <head defer>
  • I renderer dei blocchi pubblici non devono emettere script inline
  • Il JS pubblico di proprietà del CMS appartiene a public/cms/js/
  • Il CSS pubblico di proprietà del CMS appartiene a public/cms/css/
  • Gli asset pubblici di proprietà dei plugin devono utilizzare handle e percorsi statici di proprietà del plugin e devono essere registrati tramite gli hook di contributo asset del plugin invece di modificare direttamente il layout pubblico del CMS
  • Il JS di override a livello di sito appartiene a public/site/{site_handle}/js/site.js
  • Il CSS di override a livello di sito appartiene a public/site/{site_handle}/css/site.css
  • La shell della pagina pubblica possiede l'unico punto di montaggio condiviso #wb-overlay-root.wb-overlay-root per i comportamenti basati su modale distribuiti da WebBlocks UI, come i visualizzatori di galleria e la finestra modale di ricerca pubblica
  • I partial pubblici e i contenuti HTML attendibili devono contribuire con i figli di overlay a quella radice canonica invece di generare radici concorrenti come #wb-public-overlay-root, #public-overlay-root o #overlay-root
  • Il livello di dialogo pubblico condiviso non deve essere generato con hidden; WebBlocks UI v2.7.12 riutilizza quel livello per le destinazioni di modale, visualizzatore di galleria e toast e commuta la visibilità solo sul backdrop/modale attivo o sullo stato del toast, non su un wrapper di livello riutilizzato
  • Il core del CMS distribuisce JS pubblico solo quando WebBlocks UI non copre già il comportamento; public-search-modal.js resta di proprietà del CMS, mentre la modalità, il preset, l'accento e il comportamento dei menu a discesa di Header Actions si basano ora sul comportamento data-wb-* distribuito da WebBlocks UI senza un runtime CMS aggiuntivo

Asset di branding del sito

La favicon pubblica e le immagini per la condivisione social vengono ora selezionate dalla libreria media condivisa di ciascun sito.

  • l'output della favicon utilizza il favicon_media_id del sito attualmente risolto quando quell'elemento media ha un URL pubblico
  • l'immagine di riserva per Open Graph utilizza il social_image_media_id del sito attualmente risolto quando disponibile
  • questi sono asset di metadati circoscritti al sito, non asset del brand di prodotto del CMS
  • l'og_image_media_id della traduzione di pagina può sovrascrivere l'immagine social del sito per una singola lingua (locale) quando quell'elemento media ha un URL pubblico
  • gli asset SEO a livello di pagina influiscono solo sui metadati pubblici e non modificano il branding dell'amministrazione del CMS
  • la Project Identity a livello di installazione non influisce sulla favicon pubblica, sui metadati pubblici o sugli asset di condivisione social circoscritti al sito

Asset di WebBlocks UI

Gli asset di WebBlocks UI restano caricati dalla CDN nel layout pubblico del CMS.

I riferimenti CDN predefiniti di proprietà del CMS sono fissati a WebBlocks UI v2.7.12 per il CSS di runtime pubblico e di amministrazione, il CSS delle icone, il JS di runtime e la sorgente di sincronizzazione del manifest delle icone predefinito. L'output del layout in produzione utilizza il formato canonico degli URL con tag di jsDelivr con gli artefatti dist standard webblocks-ui.css, webblocks-icons.css e webblocks-ui.js, mentre l'irrobustimento tramite minificazione è rimandato. Il CSS e il JavaScript destinati al browser non devono utilizzare ripieghi su raw.githubusercontent.com, perché Chrome può bloccare quelle risposte tramite ORB o la gestione dei MIME.

Quegli asset CDN fanno parte del progetto UI e non devono essere modificati o compilati all'interno del repository del CMS. Quando è installato su un sito operatore, WebBlocks UI Manager registra i metadati di rilascio, artefatto, manifest, checksum e esecuzione di pubblicazione come comportamento di proprietà del plugin e può pubblicare i file convalidati in una destinazione CDN statica locale/di proprietà del progetto configurata. Il core del CMS continua a utilizzare gli URL CDN fissati esistenti finché una migrazione esplicita e separata non modifica tale comportamento.

Ambito del JavaScript di amministrazione

Il layout di amministrazione del pacchetto mantiene il JavaScript globale volutamente ridotto: il webblocks-ui.js fissato di WebBlocks UI più l'asset condiviso del core di amministrazione del CMS in public/cms/js/admin/core.js. Il comportamento di amministrazione specifico di una funzionalità deve essere caricato tramite lo stack admin-scripts dalla vista o dal partial che genera i corrispondenti hook DOM.

Esempi di asset di funzionalità circoscritti alla pagina includono i pannelli del selettore di asset, i pulsanti di copia dei media, le righe ordinabili del builder, gli editor del builder inline e strutturati, le finestre modali del page builder, le finestre modali di eliminazione dei blocchi di slot, le finestre modali di origine degli slot di pagina, i controlli degli asset di Edit Page, la modifica degli elementi di Gallery, la modifica del Rich Text e i pulsanti di visibilità della password nell'amministrazione. Questi restano file statici di proprietà del CMS sotto public/cms/js/admin/ con le corrispondenti copie sorgente del pacchetto sotto packages/webblocks-cms/public/cms/js/admin/ ove applicabile. Gli asset di amministrazione del CMS non utilizzano Vite, npm, Tailwind, public/build, file hot o alcuna catena di build frontend.