Recursos públicos

Recursos públicos del núcleo del CMS

Los recursos públicos del núcleo de WebBlocks CMS se encuentran en:

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

Estas rutas están destinadas al comportamiento en ejecución y al estilo propiedad del CMS que deben distribuirse con el propio producto.

Los recursos del núcleo del CMS son recursos estáticos de paquete/tiempo de ejecución. El tiempo de ejecución del CMS y el paquete de publicación no deben requerir Vite, el plugin Vite de Laravel, Tailwind, npm, Node, public/build, public/hot, archivos de bloqueo de paquetes ni directivas Blade @vite. Cuando cambie el CSS o el JavaScript propiedad del CMS, actualice directamente los archivos versionados en public/cms y en el paquete packages/webblocks-cms/public/cms.

El espacio de nombres de URL /cms/... está reservado a estos recursos estáticos del CMS. No debe reutilizarse como prefijo de ruta, alias o redirección de la administración del CMS. El espacio de nombres canónico de la administración del CMS es /webadmin/..., incluido /webadmin/login cuando están activas las rutas de autenticación del CMS propiedad del paquete.

Las rutas de páginas públicas son rutas canónicas de Page Translation, como /contact o /docs/internal-content-api. No deben reclamar /cms/...; ese espacio de nombres sigue siendo exclusivamente de recursos estáticos. La antigua forma de página pública /p/... es una redirección/alias heredado y no se utiliza para nuevas URL canónicas.

Esta separación protege los despliegues habituales de Nginx con try_files. Una petición a /cms/ puede coincidir con el directorio físico public/cms/ antes de que Laravel reciba la petición, por lo que el enrutamiento de la administración del CMS no debe depender de /cms. El diseño final del prefijo de administración evita por completo la colisión y no utiliza una transferencia al controlador frontal public/cms/index.php; ese archivo debe seguir ausente tanto de public/cms/ en la raíz de la instalación como de los recursos del paquete packages/webblocks-cms/public/cms/.

Convención de identificadores de sitio

Los identificadores de sitio (site handles) son identificadores seguros para el sistema de archivos que se utilizan para las carpetas de recursos públicos limitadas a un sitio.

  • Los identificadores van en minúsculas.
  • Los identificadores son seguros en ASCII siempre que sea posible.
  • Los espacios, puntos, barras, guiones bajos y la puntuación repetida se normalizan a un único guion.
  • Solo permanecen a-z, 0-9 y -.
  • Los guiones repetidos se reducen a uno, y los guiones iniciales o finales se eliminan.
  • Ejemplos de normalización:
  • ui.webblocksui.com -> ui-webblocksui-com
  • WebBlocks UI -> webblocks-ui
  • Docs Site -> docs-site

El guion es el separador canónico de los identificadores de sitio y de las carpetas public/site/{site_handle}/....

Recursos de nivel de instalación y de sustitución por sitio

Las sustituciones públicas específicas de la instalación o del sitio se encuentran bajo el identificador de sitio resuelto:

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

Estos archivos son espacio de sustitución para la instalación actual y no deben utilizarse para el comportamiento del núcleo del CMS.

Cuando está presente, public/site/{site_handle}/css/site.css se renderiza en el <head> público del sitio público actualmente resuelto.

Cuando está presente, public/site/{site_handle}/js/site.js se renderiza en el <head> público con defer para el sitio público actualmente resuelto.

Cuando la exportación/importación de sitios se ejecuta con la inclusión de archivos activada, estos dos archivos canónicos de sustitución a nivel de sitio se empaquetan si existen y se restauran bajo el identificador de sitio importado final. Los archivos site.css o site.js ausentes se omiten de forma limpia. La exportación/importación no empaqueta árboles arbitrarios public/site/{site_handle}/... a través de esta vía de nivel de sitio.

public/storage es independiente de public/site/.... Es el enlace simbólico de almacenamiento público de Laravel creado por storage:link para los archivos ubicados en storage/app/public, y no debe tratarse como espacio de recursos del CMS ni como espacio de recursos de sustitución del sitio.

La convención canónica de sustitución exige un segmento con el identificador de sitio. Las rutas de sustitución de sitio sin identificador no son canónicas y no deben utilizarse para nuevos comportamientos en ejecución.

Los estilos de apoyo para invitados y correo electrónico propiedad del CMS se encuentran ahora en public/cms/css/guest.css y public/cms/css/email.css.

Los recursos de marca del producto propiedad del CMS, como los favicons predeterminados del CMS y los archivos de marca de compatibilidad, se distribuyen desde el paquete public/cms/brand/ y se instalan, publican o sincronizan en public/cms/brand/ de la raíz de la instalación. Se trata de recursos de identidad del producto para el shell del CMS, no de la marca de la biblioteca de medios específica del sitio ni de sustituciones en public/site/.... El conjunto canónico de marca del producto es logo-mark.svg, logo-mark-dark.svg, logo-mark-on-accent.svg, favicon.svg, favicon-32x32.png, favicon-16x16.png y apple-touch-icon.png. Las pantallas de autenticación del CMS propiedad del paquete y la barra lateral de administración renderizan la marca mediante un componente SVG en línea que hereda currentColor.

Recursos de página

Los archivos CSS y JS limitados a una página pueden ahora referenciarse de forma relacional desde page_assets.

  • La V1 acepta únicamente rutas locales /site/..., como /site/webblocks-ui/pages/playground/page.css o /site/webblocks-ui/pages/playground/page.js
  • Las rutas canónicas de recursos de página son:
  • public/site/{site_handle}/pages/{page_slug}/page.css
  • public/site/{site_handle}/pages/{page_slug}/page.js
  • Los recursos CSS de página se renderizan en el <head> público
  • Los recursos JS de página se renderizan en el <head> público con defer
  • Solo la página pública propietaria renderiza los recursos de página configurados
  • Los recursos de página no se renderizan en los layouts de administración
  • Los recursos de página se almacenan en page_assets, no en pages.settings
  • Cuando la exportación/importación del sitio incluye archivos de medios, los archivos físicos /site/... referenciados también se empaquetan y restauran

Recursos públicos de plugins

Los plugins habilitados pueden declarar aportaciones de recursos públicos mediante objetos de registro PluginPublicAsset. Estos hooks están pensados para recursos de plugin explícitos y atribuibles, y son independientes de los recursos del núcleo del CMS, de los recursos de sustitución del sitio y de los recursos limitados a una página.

  • los identificadores de recursos de plugin deben llevar el espacio de nombres con puntos del identificador del plugin, como analytics-tools.public-css
  • el CSS del plugin puede aportarse al <head> público
  • el JS del plugin puede aportarse al <head> público con defer, async o type="module" cuando así se declare
  • el JS del plugin puede aportarse al final del cuerpo público cuando convenga una carga tardía
  • los recursos de plugins deshabilitados o incompatibles no se recopilan ni se renderizan
  • los recursos del plugin deben seguir publicándose por el propio plugin bajo un espacio de nombres estático de su propiedad

El hook no instala paquetes de plugins, no publica archivos, no transmite recursos a través de Laravel, no crea descubrimiento remoto ni comportamiento de mercado.

El plugin interno/de operador WebBlocks UI Manager utiliza una convención de artefactos de CDN independiente en lugar del hook de recursos de página pública. No se incluye en las instalaciones normales del CMS y solo está disponible tras una carga manual del ZIP y su habilitación explícita:

  • los destinos de artefactos de publicación se versionan en public/cdn/webblocks-ui/{version}/...
  • los manifiestos de publicación son metadatos locales de los artefactos preparados e incluyen sumas de comprobación SHA-256
  • la publicación en modo de prueba valida las rutas de origen, los archivos dist esperados, las sumas de comprobación, la coherencia del manifiesto, la seguridad de las rutas de destino y la idempotencia sin escribir archivos
  • la publicación efectiva escribe únicamente en el destino estático local/propiedad del proyecto configurado, una vez superada la validación
  • los archivos existentes con sumas de comprobación coincidentes se omiten, mientras que las discrepancias de suma de comprobación bloquean la publicación
  • el flujo de trabajo no despliega en una CDN de producción externa ni cambia las URL de consumo de WebBlocks UI del núcleo del CMS

Convención de recursos públicos

  • El CSS permanece en el <head> público
  • El JS público con nombre permanece en el <head> público con defer
  • Las filas heredadas de JS con nombre almacenadas con body_end se siguen aceptando, pero el JS público con nombre se normaliza a una salida <head defer>
  • Los renderizadores de bloques públicos no deben emitir scripts en línea
  • El JS público propiedad del CMS pertenece a public/cms/js/
  • El CSS público propiedad del CMS pertenece a public/cms/css/
  • Los recursos públicos propiedad de plugins deben usar identificadores y rutas estáticas propias del plugin, y deben registrarse mediante los hooks de aportación de recursos del plugin en lugar de modificar directamente el layout público del CMS
  • El JS de sustitución a nivel de sitio pertenece a public/site/{site_handle}/js/site.js
  • El CSS de sustitución a nivel de sitio pertenece a public/site/{site_handle}/css/site.css
  • El shell de página pública es propietario del único punto de montaje compartido #wb-overlay-root.wb-overlay-root para los comportamientos basados en modales de WebBlocks UI distribuidos, como los visores de galería y el modal de búsqueda pública
  • Los partials públicos y el contenido HTML de confianza deben aportar sus hijos de superposición a esa raíz canónica en lugar de renderizar raíces competidoras como #wb-public-overlay-root, #public-overlay-root o #overlay-root
  • La capa de diálogo pública compartida no debe renderizarse con hidden; WebBlocks UI v2.7.12 reutiliza esa capa para los destinos de modal, visor de galería y toast, y solo alterna la visibilidad en el fondo/modal activo o en el estado del toast, no en un contenedor de capa reutilizado
  • El núcleo del CMS solo distribuye JS público cuando WebBlocks UI no cubre ya el comportamiento; public-search-modal.js sigue siendo propiedad del CMS, mientras que el modo, el preajuste, el acento y el comportamiento desplegable de Header Actions se apoyan ahora en el comportamiento data-wb-* distribuido de WebBlocks UI sin un runtime adicional del CMS

Recursos de marca del sitio

El favicon público y la ilustración para compartir en redes sociales se seleccionan ahora desde la biblioteca de medios compartida de cada sitio.

  • la salida del favicon utiliza el favicon_media_id del sitio resuelto actual cuando ese elemento de medios tiene una URL pública
  • la imagen de reserva de Open Graph utiliza el social_image_media_id del sitio resuelto actual cuando está disponible
  • estos son recursos de metadatos limitados al sitio, no recursos de marca del producto CMS
  • el og_image_media_id de la traducción de página puede sustituir la imagen social del sitio para un idioma (locale) cuando ese elemento de medios tiene una URL pública
  • los recursos SEO a nivel de página solo afectan a los metadatos públicos y no modifican la marca de la administración del CMS
  • la Project Identity de nivel de instalación no afecta al favicon público, a los metadatos públicos ni a los recursos de compartición social limitados al sitio

Recursos de WebBlocks UI

Los recursos de WebBlocks UI se siguen cargando desde la CDN en el layout público del CMS.

Las referencias de CDN predeterminadas propiedad del CMS están fijadas a WebBlocks UI v2.7.12 para el CSS de ejecución público y de administración, el CSS de iconos, el JS de ejecución y la fuente de sincronización del manifiesto de iconos predeterminado. La salida del layout en producción utiliza el formato canónico de URL de etiqueta de jsDelivr con los artefactos dist estándar webblocks-ui.css, webblocks-icons.css y webblocks-ui.js, mientras se aplaza el endurecimiento mediante minificación. El CSS y el JavaScript destinados al navegador no deben usar reservas en raw.githubusercontent.com, porque Chrome puede bloquear esas respuestas mediante ORB o el tratamiento de MIME.

Esos recursos de CDN forman parte del proyecto UI y no deben editarse ni compilarse dentro del repositorio del CMS. Cuando está instalado en un sitio de operador, WebBlocks UI Manager registra los metadatos de publicación, artefacto, manifiesto, suma de comprobación y ejecución de publicación como comportamiento propiedad del plugin, y puede publicar archivos validados en un destino de CDN estático local/propiedad del proyecto configurado. El núcleo del CMS sigue consumiendo las URL de CDN fijadas existentes hasta que una migración explícita e independiente cambie ese comportamiento.

Alcance del JavaScript de administración

El layout de administración del paquete mantiene el JavaScript global intencionadamente reducido: el webblocks-ui.js fijado de WebBlocks UI más el recurso compartido del núcleo de administración del CMS en public/cms/js/admin/core.js. El comportamiento de administración específico de una funcionalidad debe cargarse a través de la pila admin-scripts por la vista o el partial que renderiza los hooks del DOM correspondientes.

Entre los ejemplos de recursos de funcionalidad limitados a una página se incluyen los paneles del selector de recursos, los botones de copia de medios, las filas ordenables del constructor, los editores del constructor en línea y estructurados, los modales del constructor de páginas, los modales de eliminación de bloques de slot, los modales de origen de slot de página, los controles de recursos de Edit Page, la edición de elementos de Gallery, la edición de Rich Text y los conmutadores de visibilidad de contraseña en la administración. Estos siguen siendo archivos estáticos propiedad del CMS en public/cms/js/admin/, con las copias de origen correspondientes del paquete en packages/webblocks-cms/public/cms/js/admin/ cuando proceda. Los recursos de administración del CMS no utilizan Vite, npm, Tailwind, public/build, archivos hot ni ninguna cadena de compilación de frontend.