DfCustomCodeManager — Guía completa

DfCustomCodeManager aporta una respuesta sencilla a un problema universal en las tiendas Shopware: dónde poner, cómo versionar y cómo proteger el CSS y el JavaScript personalizado que siempre terminas añadiendo a un tema. El plugin ofrece un editor de código integrado en la administración, un sistema de contenedores que agrupan fragmentos SCSS o JavaScript, y sobre todo una inyección directa en la compilación del tema a través de los eventos nativos de Shopware. La consecuencia: ningún archivo adicional servido, ninguna petición HTTP extra para el visitante, y tus fragmentos SCSS heredan automáticamente las variables y mixins del tema activo. Esta guía cubre la instalación, la configuración, la creación de contenedores y fragmentos, la compilación del tema, el historial de versiones, el modo seguro, la biblioteca de plantillas, la importación/exportación y la resolución de problemas.

Instalación

1. Descarga el archivo DfCustomCodeManager-1.0.0.zip desde tu cuenta DataFirefly.
2. Instálalo vía Administración → Extensiones → Mis extensiones → Subir extensión, o descomprime la carpeta DfCustomCodeManager en custom/plugins/.
3. Ejecuta instalación y activación:

   bin/console plugin:refresh
   bin/console plugin:install --activate DfCustomCodeManager
   bin/console cache:clear

4. En la instalación, el plugin crea sus 4 tablas (df_ccm_container, df_ccm_container_sales_channel, df_ccm_snippet, df_ccm_snippet_version) y registra sus subscribers en los eventos de compilación del tema.
5. Recompila el tema para que recoja el plugin:

   bin/console theme:compile

Dónde encontrar el plugin en la administración

Tras la activación, aparece una entrada Custom Code Manager en el menú Catálogos de la administración (icono naranja, posición 100). Es la pantalla central: lista de contenedores, búsqueda, filtros, y las acciones globales Importar, Exportar, Plantillas y Compilar el tema. Toda la configuración de bajo nivel (modo seguro, minificar, banner) se hace desde Extensiones → Mis extensiones → DfCustomCodeManager → ⋯ → Configurar.

Configuración del plugin

La tarjeta de configuración del plugin Shopware expone tres interruptores simples pero esenciales:

• Modo seguro (DfCustomCodeManager.config.safeMode): desactivado por defecto. Cuando se activa, todos los contenedores se ignoran en la próxima compilación, como si estuvieran todos inactivos. Es la red de seguridad descrita más abajo.
• Minificar JS (DfCustomCodeManager.config.minifyJs): minificación básica del JavaScript inyectado. Útil en producción, dejarlo desactivado en desarrollo para poder leer tus fragmentos en el bundle compilado.
• Añadir banner (DfCustomCodeManager.config.addBanner): añade un comentario /* DataFirefly Custom Code Manager */ al inicio del código inyectado. Práctico para identificar rápidamente tus fragmentos en el bundle compilado.

El modelo mental: contenedores y fragmentos

El plugin se organiza en dos niveles:

• Un contenedor es una agrupación lógica: Promo verano 2026, GTM analítica, Modo oscuro opt-in, A/B test botón CTA… Cada contenedor tiene un nombre, una descripción, una prioridad, un interruptor activo/inactivo y un alcance por canal de venta.
• Un fragmento es una unidad de código dentro de un contenedor. Tipo SCSS o JavaScript, nombre, código, prioridad, interruptor activo/inactivo, notas Markdown, y un interruptor para activar o no la inyección de variables del tema.

Un contenedor puede contener varios fragmentos de tipos mezclados. Es útil para agrupar lógicamente los fragmentos que van juntos: por ejemplo un contenedor Modo oscuro opt-in con un fragmento SCSS para los estilos y un fragmento JavaScript para el toggle de clase en html.

Crear tu primer contenedor

1. Desde Catálogos → Custom Code Manager, haz clic en Nuevo contenedor arriba a la derecha.
2. Dale un nombre evocador (ej. Promo verano 2026 — sticky header & badge).
3. Define la prioridad (déjala en 0 por defecto, súbela si quieres que este contenedor se inyecte más tarde en el bundle y por tanto sobrescriba otros estilos).
4. (Opcional) Activa Limitar a canales de venta específicos y selecciona uno o varios canales. Si la opción está desactivada, el contenedor se aplica a todos los canales.
5. Rellena una descripción (notas internas, contexto, ticket asociado) — nunca se inyectará en el bundle.
6. Guarda. Ya estás listo para añadir fragmentos.

Añadir un fragmento SCSS o JavaScript

En la tarjeta Fragmentos de código de la página contenedor, dos botones: Añadir SCSS y Añadir JavaScript. Cada fragmento añadido aparece como una tarjeta con:

• Un badge SCSS (info) o JS (warning).
• Un campo nombre (visible solo en modo edición).
• Un interruptor activo/inactivo.
• Un botón Validar sintaxis (✓).
• Un botón Historial (reloj) — disponible desde el primer guardado.
• Un botón Duplicar.
• Un botón Eliminar.
• Un editor de código con resaltado sintáctico adaptado al tipo.
• Una zona Notas Markdown para documentar qué hace el fragmento.

Compilar el tema

Un fragmento guardado aún no es visible en el storefront hasta que el tema haya sido recompilado. Dos formas de hacerlo:

• Desde la administración, el botón Compilar el tema (arriba a la derecha de la lista, o en la página contenedor). Una notificación confirma el final de la operación.
• Desde la línea de comandos:

  bin/console theme:compile

En la compilación, el plugin escucha tres eventos Shopware e inyecta tus fragmentos en ellos:

• ThemeCompilerEnrichScssVariablesEvent — captura el mapa de variables SCSS del tema activo. Es lo que permite a tus fragmentos SCSS usar $sw-color-brand-primary, $font-family-base, etc.
• ThemeCompilerConcatenatedStylesEvent — añade tu SCSS compilado al final de la hoja de estilos principal.
• ThemeCompilerConcatenatedScriptsEvent — añade tu JavaScript al final del bundle scripts principal.

Resultado: cero peticiones HTTP adicionales servidas al visitante, tu código pasa por toda la cadena de optimización Shopware (concatenación, minificación, fingerprinting de caché).

Herencia de variables y mixins del tema

Por defecto, cada fragmento SCSS se beneficia de un preámbulo automático que contiene todas las variables y mixins expuestos por el tema activo y sus plugins de tema. Puedes por tanto escribir en un fragmento:

.header {
    background: $sw-color-brand-primary;
    font-family: $font-family-base;
    transition: $transition-base;
}

…sin importar nada manualmente, exactamente como en un archivo SCSS del tema. Si por alguna razón particular (conflicto de variable, fragmento autocontenido) quieres desactivar esta herencia en un fragmento concreto, desmarca el interruptor Variables del tema disponibles en el pie de la tarjeta de fragmento.

Alcance multicanal

En la tarjeta Alcance y canales del contenedor, activa Limitar a canales de venta específicos y selecciona los canales relevantes. El contenedor solo se inyectará entonces en las compilaciones de tema para esos canales. Muy útil para:

• Un banner promocional reservado a una tienda de marca secundaria.
• Un script de tracking específico para un mercado.
• Un A/B test en un solo canal para medir el impacto.

Prioridad de carga

La prioridad es un entero (por defecto 0) que controla el orden de inyección en el bundle compilado: cuanto mayor sea el valor, más tarde se inyecta el código, y por tanto más puede sobrescribir lo que le precede. La prioridad existe en dos niveles:

• A nivel contenedor: orden entre contenedores.
• A nivel fragmento: orden entre fragmentos dentro de un mismo contenedor.

El orden final es: (prioridad contenedor, prioridad fragmento) ascendente. Consejo simple: deja todo en 0 por defecto, usa la prioridad solo cuando realmente necesites sobrescribir algo.

Historial de versiones

En cada guardado de un fragmento, el plugin crea automáticamente una versión en la tabla df_ccm_snippet_version. Se conservan las 5 últimas versiones por fragmento (la más antigua se elimina cuando se alcanza el umbral). Para consultar y restaurar una versión:

1. En la tarjeta de fragmento, haz clic en el icono Historial (reloj).
2. Se abre un modal con la lista de versiones: fecha, autor, comentario y vista previa.
3. Haz clic en Restaurar a la derecha de la versión deseada — el código del fragmento se reemplaza inmediatamente por el de esa versión. Se crea una nueva versión para registrar la restauración.
4. Guarda el contenedor y recompila para ver el efecto.

Modo seguro: la red de seguridad de emergencia

El modo seguro es un interruptor global en la configuración del plugin. Activado, hace que todos los contenedores se ignoren en la próxima compilación, sin modificar ningún dato. Uso típico:

1. Un fragmento mal probado rompe algo en producción a las 22h.
2. Ve a Extensiones → Mis extensiones → DfCustomCodeManager → ⋯ → Configurar.
3. Activa el interruptor Modo seguro y guarda.
4. Recompila el tema: bin/console theme:compile.
5. El storefront vuelve a su estado nativo (sin ningún fragmento inyectado). Ahora puedes identificar y corregir el fragmento defectuoso con calma.
6. Una vez corregido, desactiva el modo seguro y recompila de nuevo.

Biblioteca de plantillas

El botón Plantillas (desde la lista de contenedores) abre una biblioteca de 8 contenedores instalables en un clic:

• Sticky header — header que se transforma al desplazarse (clase is-sticky añadida por encima de un umbral).
• Volver arriba — botón volver arriba, visible a partir de cierto punto de scroll.
• Skin banner cookies — re-skinning del banner cookies nativo para alinearlo con tu identidad gráfica.
• Badge producto — Nuevo — badge «Nuevo» en productos creados recientemente.
• Barra envío gratuito — barra de progreso de envío gratuito en la parte superior de la página.
• Botones redondeados — botones redondeados en toda la tienda.
• Evento GTM DOM-ready — dispara un evento personalizado cuando el DOM está listo, para arrancar tus data layers.
• Fade-in al scroll — aparición progresiva de los elementos al hacer scroll.

Hacer clic en Instalar crea el contenedor y sus fragmentos en la base de datos. Solo queda recompilar el tema para verlos en línea. Los contenedores creados a partir de una plantilla son contenedores como los demás: puedes editarlos, ampliarlos, desactivarlos, eliminarlos.

Importación / Exportación JSON

Para migrar fragmentos entre entornos (dev, staging, producción) o entre tiendas:

1. Exportación — selecciona uno o varios contenedores en la lista (casillas), luego haz clic en Exportar. Se descarga un archivo JSON, que contiene todos los contenedores seleccionados con sus fragmentos, su prioridad, sus notas — y el número de versión del formato (EXPORT_VERSION = 1) para la retrocompatibilidad.
2. Importación — en el entorno de destino, haz clic en Importar y selecciona el archivo JSON. Los contenedores y fragmentos se recrean idénticamente.

Validación sintáctica

El botón ✓ Validar sintaxis en cada tarjeta de fragmento lanza una validación del lado servidor sin guardar nada. Según el tipo:

• SCSS — el plugin lanza una compilación en blanco vía scssphp/scssphp inyectando el preámbulo de variables del tema. Si la compilación pasa, el fragmento es válido. En caso contrario, los errores se reportan en una zona de error en la tarjeta (número de línea, mensaje).
• JavaScript — el plugin limpia el código de cadenas y comentarios, luego verifica el equilibrio de llaves {}, paréntesis () y corchetes []. Este check no reemplaza un parser ECMAScript real, pero atrapa el 90% de los errores de copiar-pegar (llave olvidada, cadena mal cerrada). Para ir más lejos, valida tu JavaScript en una herramienta dedicada antes de pegar.

Arquitectura técnica

Para los desarrolladores que quieren entender o extender el plugin:

• Namespace PHP raíz: DataFirefly (sub-namespace: CustomCodeManager, clases bajo src/).
• Plugin class: DfCustomCodeManager (extiende ShopwareCoreFrameworkPlugin).
• Prefijo SystemConfig: DfCustomCodeManager.config.*.
• Tablas: df_ccm_container, df_ccm_container_sales_channel, df_ccm_snippet, df_ccm_snippet_version.
• Migrations: Migration1779580800CreateCcmContainerTable, Migration1779580801CreateCcmSnippetTable, Migration1779580802CreateCcmSnippetVersionTable.
• Services: CodeCompiler (orquestación + caché), SnippetExporter (importación/exportación JSON), SnippetValidator (validación sintáctica), VersionTracker (snapshot + restore + trim).
• Subscribers: ThemeCompilerSubscriber (los 3 events de compilación), SnippetWrittenSubscriber (snapshot automático al escribir).
• Rutas API privadas bajo /api/_action/df-ccm/ (scope api): validate, export, import, restore-version, recompile, presets.

Todas las declaraciones de servicios son explícitas en services.xml (sin autowiring) para mantenerse alineadas con las convenciones DataFirefly.

Extender el módulo de administración

El módulo de administración está compilado y ubicado bajo Resources/public/administration/js/df-custom-code-manager.js. Está precompilado en el ZIP y no requiere ningún build local. Para extenderlo, encuentra los componentes (df-ccm-list, df-ccm-detail, df-ccm-snippet-card, df-ccm-code-field, df-ccm-preset-modal, df-ccm-version-modal) y personaliza vía el sistema de override estándar Shopware (Component.override).

FAQ y resolución de problemas

Mis fragmentos no aparecen en el storefront. ¿Has recompilado el tema? Hasta que theme:compile no se haya ejecutado tras una modificación, nada cambia. Verifica también que el contenedor y el fragmento estén activos, que el canal de venta correspondiente esté en el alcance (si el alcance está restringido), y que el modo seguro no esté activado.

Error de compilación SCSS en la consola tras theme:compile. Lo más frecuente es una variable de tema que no existe (errata) o un fragmento SCSS que abre un bloque sin cerrarlo. Desactiva el fragmento infractor, recompila para confirmar, luego corrige con calma. La validación sintáctica en la tarjeta de fragmento atrapa la mayoría de estos casos antes de guardar.

El menú Custom Code Manager no aparece en la administración. Ejecuta bin/console assets:install && bin/console cache:clear luego recarga la administración con Ctrl+Shift+R. El módulo está en el grupo Catálogos.

El editor de código muestra un textarea sin resaltado. Es el fallback cuando ni mt-code-editor (6.7) ni sw-code-editor (6.6) están disponibles. Verifica tu versión Shopware y que el módulo de administración esté correctamente cargado.

Quiero desactivar temporalmente todos los fragmentos sin eliminar nada. Eso es exactamente el modo seguro. Toggle en la configuración del plugin, recompilación, listo.

El botón «Compilar el tema» gira sin parar. Verifica los logs Shopware. La compilación puede tomar tiempo en un tema grande; en caso de bloqueo real, la causa habitual es un fragmento SCSS que bucle o contenga una variable desconocida. Activa el modo seguro, recompila, luego reactiva los fragmentos uno a uno para identificar al culpable.

Mi fragmento JavaScript no se dispara. Recuerda que el código inyectado se ejecuta en el bundle global, en un contexto distinto al de los plugins JavaScript Shopware clásicos. Para interactuar con los plugins JavaScript del storefront, escucha más bien document.addEventListener('DOMContentLoaded', …) o los eventos globales que el storefront emite.

¿Qué pasa con la desinstalación? Durante plugin:uninstall, Shopware muestra la casilla estándar Conservar datos de usuario. Si está desmarcada, el plugin elimina sus 4 tablas y todos los datos asociados (contenedores, fragmentos, versiones, vínculos de canal). Si está marcada, las tablas permanecen y recuperarás tus fragmentos si reinstalas el plugin más tarde.