Ressources publiques

Ressources publiques du cœur du CMS

Les ressources publiques du cœur de WebBlocks CMS se trouvent sous :

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

Ces chemins sont destinés au comportement d'exécution et à la mise en forme appartenant au CMS, qui doivent être livrés avec le produit lui-même.

Les ressources du cœur du CMS sont des ressources statiques de paquet/d'exécution. L'exécution du CMS et le paquet de livraison ne doivent pas nécessiter Vite, le plugin Vite de Laravel, Tailwind, npm, Node, public/build, public/hot, des fichiers de verrouillage de paquets ni des directives Blade @vite. Lorsque le CSS ou le JavaScript appartenant au CMS change, mettez directement à jour les fichiers suivis sous public/cms et dans le paquet packages/webblocks-cms/public/cms.

L'espace de noms d'URL /cms/... est réservé à ces ressources statiques du CMS. Il ne doit pas être réutilisé comme préfixe de route, alias ou redirection de l'administration du CMS. L'espace de noms canonique de l'administration du CMS est /webadmin/..., y compris /webadmin/login lorsque les routes d'authentification du CMS appartenant au paquet sont actives.

Les chemins des pages publiques sont des chemins canoniques de Page Translation tels que /contact ou /docs/internal-content-api. Ils ne doivent pas revendiquer /cms/... ; cet espace de noms reste réservé aux seules ressources statiques. L'ancienne forme de page publique /p/... est une redirection/un alias hérité et n'est pas utilisée pour les nouvelles URL canoniques.

Cette séparation protège les déploiements Nginx courants utilisant try_files. Une requête vers /cms/ peut correspondre au répertoire physique public/cms/ avant que Laravel ne reçoive la requête ; le routage de l'administration du CMS ne doit donc pas dépendre de /cms. La conception finale du préfixe d'administration évite entièrement la collision et n'utilise pas de relais vers un contrôleur frontal public/cms/index.php ; ce fichier doit rester absent à la fois de public/cms/ à la racine de l'installation et des ressources du paquet packages/webblocks-cms/public/cms/.

Convention des identifiants de site

Les identifiants de site (site handles) sont des identifiants compatibles avec le système de fichiers, utilisés pour les dossiers de ressources publiques propres à un site.

  • Les identifiants sont en minuscules.
  • Les identifiants sont compatibles ASCII dans la mesure du possible.
  • Les espaces, points, barres obliques, tirets bas et la ponctuation répétée sont normalisés en un seul trait d'union.
  • Seuls a-z, 0-9 et - subsistent.
  • Les traits d'union répétés sont réduits à un seul, et les traits d'union en début ou en fin sont supprimés.
  • Exemples de normalisation :
  • ui.webblocksui.com -> ui-webblocksui-com
  • WebBlocks UI -> webblocks-ui
  • Docs Site -> docs-site

Le trait d'union est le séparateur canonique des identifiants de site et des dossiers public/site/{site_handle}/....

Ressources de niveau installation et de substitution par site

Les substitutions publiques propres à l'installation ou au site se trouvent sous l'identifiant de site résolu :

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

Ces fichiers constituent l'espace de substitution de l'installation courante et ne doivent pas servir au comportement du cœur du CMS.

Lorsqu'il est présent, public/site/{site_handle}/css/site.css est restitué dans le <head> public du site public actuellement résolu.

Lorsqu'il est présent, public/site/{site_handle}/js/site.js est restitué dans le <head> public avec defer pour le site public actuellement résolu.

Lorsque l'export/import de site s'exécute avec l'inclusion des fichiers activée, ces deux fichiers canoniques de substitution au niveau du site sont empaquetés s'ils existent et restaurés sous l'identifiant de site importé final. Les fichiers site.css ou site.js manquants sont ignorés proprement. L'export/import n'empaquette pas d'arborescences public/site/{site_handle}/... arbitraires par cette voie de niveau site.

public/storage est distinct de public/site/.... Il s'agit du lien symbolique de stockage public de Laravel créé par storage:link pour les fichiers situés sous storage/app/public, et il ne doit pas être considéré comme un espace de ressources du CMS ni comme un espace de ressources de substitution de site.

La convention canonique de substitution exige un segment d'identifiant de site. Les chemins de substitution de site sans identifiant ne sont pas canoniques et ne doivent pas être utilisés pour de nouveaux comportements d'exécution.

Les styles de prise en charge des pages invité et des e-mails appartenant au CMS se trouvent désormais sous public/cms/css/guest.css et public/cms/css/email.css.

Les ressources de marque du produit appartenant au CMS, telles que les favicons par défaut du CMS et les fichiers de marque de compatibilité, sont livrées depuis le paquet public/cms/brand/ et sont installées, publiées ou synchronisées dans public/cms/brand/ à la racine de l'installation. Ce sont des ressources d'identité du produit pour l'interface du CMS, et non l'image de marque de la médiathèque propre au site ni des substitutions public/site/.... L'ensemble canonique de marque du produit est logo-mark.svg, logo-mark-dark.svg, logo-mark-on-accent.svg, favicon.svg, favicon-32x32.png, favicon-16x16.png et apple-touch-icon.png. Les écrans d'authentification du CMS appartenant au paquet et la barre latérale d'administration restituent le logo via un composant SVG en ligne qui hérite de currentColor.

Ressources de page

Les fichiers CSS et JS propres à une page peuvent désormais être référencés de manière relationnelle depuis page_assets.

  • La V1 n'accepte que les chemins locaux /site/... tels que /site/webblocks-ui/pages/playground/page.css ou /site/webblocks-ui/pages/playground/page.js
  • Les chemins canoniques des ressources de page sont :
  • public/site/{site_handle}/pages/{page_slug}/page.css
  • public/site/{site_handle}/pages/{page_slug}/page.js
  • Les ressources CSS de page sont restituées dans le <head> public
  • Les ressources JS de page sont restituées dans le <head> public avec defer
  • Seule la page publique propriétaire restitue les ressources de page configurées
  • Les ressources de page ne sont pas restituées dans les layouts d'administration
  • Les ressources de page sont stockées dans page_assets, et non dans pages.settings
  • Lorsque l'export/import du site inclut les fichiers médias, les fichiers physiques /site/... référencés sont eux aussi empaquetés et restaurés

Ressources publiques des plugins

Les plugins activés peuvent déclarer des contributions de ressources publiques via des objets de registre PluginPublicAsset. Ces hooks sont destinés à des ressources de plugin explicites et attribuables, et sont distincts des ressources du cœur du CMS, des ressources de substitution du site et des ressources propres à une page.

  • les identifiants de ressources de plugin doivent être préfixés, séparés par un point, avec l'identifiant du plugin, par exemple analytics-tools.public-css
  • le CSS du plugin peut être apporté au <head> public
  • le JS du plugin peut être apporté au <head> public avec defer, async ou type="module" lorsque cela est déclaré
  • le JS du plugin peut être apporté en fin de corps public lorsqu'un chargement tardif est approprié
  • les ressources des plugins désactivés et incompatibles ne sont ni collectées ni restituées
  • les ressources du plugin doivent toujours être publiées par le plugin sous un espace de noms statique lui appartenant

Le hook n'installe pas de paquets de plugins, ne publie pas de fichiers, ne diffuse pas de ressources via Laravel, ne crée pas de découverte distante et n'introduit pas de comportement de place de marché.

Le plugin interne/opérateur WebBlocks UI Manager utilise une convention d'artefacts CDN distincte plutôt que le hook de ressources de page publique. Il n'est pas fourni dans les installations ordinaires du CMS et n'est disponible qu'après un téléversement manuel du ZIP et une activation explicite :

  • les cibles d'artefacts de version sont versionnées sous public/cdn/webblocks-ui/{version}/...
  • les manifestes de version sont des métadonnées locales des artefacts préparés et incluent des sommes de contrôle SHA-256
  • la publication en mode simulation valide les chemins source, les fichiers dist attendus, les sommes de contrôle, la cohérence du manifeste, la sûreté des chemins cibles et l'idempotence sans écrire de fichiers
  • la publication effective n'écrit que dans la cible statique locale/appartenant au projet configurée, une fois la validation réussie
  • les fichiers existants dont la somme de contrôle correspond sont ignorés, tandis que les écarts de somme de contrôle bloquent la publication
  • le processus ne déploie pas vers un CDN de production externe et ne modifie pas les URL de consommation de WebBlocks UI du cœur du CMS

Convention des ressources publiques

  • Le CSS reste dans le <head> public
  • Le JS public nommé reste dans le <head> public avec defer
  • Les anciennes entrées de JS nommé enregistrées avec body_end restent acceptées, mais le JS public nommé est normalisé en une sortie <head defer>
  • Les moteurs de rendu des blocs publics ne doivent pas émettre de scripts en ligne
  • Le JS public appartenant au CMS relève de public/cms/js/
  • Le CSS public appartenant au CMS relève de public/cms/css/
  • Les ressources publiques appartenant aux plugins doivent utiliser des identifiants et des chemins statiques propres au plugin, et doivent être enregistrées via les hooks de contribution de ressources du plugin plutôt qu'en modifiant directement le layout public du CMS
  • Le JS de substitution au niveau du site relève de public/site/{site_handle}/js/site.js
  • Le CSS de substitution au niveau du site relève de public/site/{site_handle}/css/site.css
  • L'enveloppe de page publique est propriétaire de l'unique point de montage partagé #wb-overlay-root.wb-overlay-root pour les comportements livrés de WebBlocks UI reposant sur des fenêtres modales, tels que les visionneuses de galerie et la fenêtre modale de recherche publique
  • Les partials publics et le contenu HTML de confiance doivent contribuer leurs enfants de superposition à cette racine canonique plutôt que de restituer des racines concurrentes telles que #wb-public-overlay-root, #public-overlay-root ou #overlay-root
  • La couche de dialogue publique partagée ne doit pas être restituée avec hidden ; WebBlocks UI v2.7.12 réutilise cette couche pour les cibles de fenêtre modale, de visionneuse de galerie et de toast, et ne bascule la visibilité que sur l'arrière-plan/la fenêtre modale active ou sur l'état du toast, jamais sur un conteneur de couche réutilisé
  • Le cœur du CMS ne livre du JS public que lorsque WebBlocks UI ne couvre pas déjà le comportement ; public-search-modal.js reste la propriété du CMS, tandis que le mode, le préréglage, l'accent et le comportement de menu déroulant de Header Actions s'appuient désormais sur le comportement data-wb-* livré par WebBlocks UI, sans runtime CMS supplémentaire

Ressources de marque du site

La favicon publique et les visuels de partage sur les réseaux sociaux sont désormais sélectionnés depuis la médiathèque partagée de chaque site.

  • la sortie de la favicon utilise le favicon_media_id du site actuellement résolu lorsque cet élément média possède une URL publique
  • l'image de repli Open Graph utilise le social_image_media_id du site actuellement résolu lorsqu'il est disponible
  • ce sont des ressources de métadonnées propres au site, et non des ressources de marque du produit CMS
  • l'og_image_media_id de la traduction de page peut remplacer l'image sociale du site pour une langue (locale) lorsque cet élément média possède une URL publique
  • les ressources SEO au niveau de la page n'affectent que les métadonnées publiques et ne modifient pas l'image de marque de l'administration du CMS
  • la Project Identity de niveau installation n'affecte ni la favicon publique, ni les métadonnées publiques, ni les ressources de partage social propres au site

Ressources WebBlocks UI

Les ressources WebBlocks UI restent chargées depuis le CDN dans le layout public du CMS.

Les références CDN par défaut appartenant au CMS sont figées sur WebBlocks UI v2.7.12 pour le CSS d'exécution public et d'administration, le CSS des icônes, le JS d'exécution et la source de synchronisation du manifeste d'icônes par défaut. La sortie du layout en production utilise le format canonique d'URL de tag jsDelivr avec les artefacts dist standard webblocks-ui.css, webblocks-icons.css et webblocks-ui.js, tandis que le durcissement par minification est reporté. Le CSS et le JavaScript destinés au navigateur ne doivent pas utiliser de replis vers raw.githubusercontent.com, car Chrome peut bloquer ces réponses via ORB ou le traitement des types MIME.

Ces ressources CDN font partie du projet UI et ne doivent pas être modifiées ni compilées dans le dépôt du CMS. Lorsqu'il est installé sur un site opérateur, WebBlocks UI Manager enregistre les métadonnées de version, d'artefact, de manifeste, de somme de contrôle et d'exécution de publication en tant que comportement appartenant au plugin, et peut publier des fichiers validés vers une cible CDN statique locale/appartenant au projet configurée. Le cœur du CMS continue d'utiliser les URL CDN figées existantes jusqu'à ce qu'une migration explicite et distincte modifie ce comportement.

Périmètre du JavaScript d'administration

Le layout d'administration du paquet garde volontairement un JavaScript global réduit : le webblocks-ui.js figé de WebBlocks UI, plus la ressource partagée du cœur de l'administration du CMS située dans public/cms/js/admin/core.js. Le comportement d'administration propre à une fonctionnalité doit être chargé via la pile admin-scripts par la vue ou le partial qui restitue les hooks DOM correspondants.

Parmi les exemples de ressources de fonctionnalité propres à une page figurent les panneaux du sélecteur de ressources, les boutons de copie de médias, les lignes triables du constructeur, les éditeurs de constructeur en ligne et structurés, les fenêtres modales du constructeur de pages, les fenêtres modales de suppression de blocs de slot, les fenêtres modales de source de slot de page, les contrôles de ressources d'Edit Page, l'édition des éléments de Gallery, l'édition du Rich Text et les bascules de visibilité du mot de passe dans l'administration. Ces fichiers restent des fichiers statiques appartenant au CMS sous public/cms/js/admin/, avec les copies source correspondantes du paquet sous packages/webblocks-cms/public/cms/js/admin/ le cas échéant. Les ressources d'administration du CMS n'utilisent ni Vite, ni npm, ni Tailwind, ni public/build, ni fichiers hot, ni aucune chaîne de compilation frontend.