Mask Twig para TYPO3

Por qué los desarrolladores frontend prefieren Twig a Fluid y cómo Mask lo hace posible

TYPO3 usa con Fluid un motor de plantillas único en el mundo PHP. Eso es al mismo tiempo su fortaleza y su mayor problema: los desarrolladores frontend que vienen del entorno Symfony, Laravel o Node.js conocen Twig o Nunjucks. Fluid no lo conocen. El mask_twig_nunjucks_connector cierra esta brecha permitiendo renderizar elementos de contenido Mask con plantillas Twig o Nunjucks en lugar de plantillas Fluid.

Para agencias cuyo equipo frontend trabaja con Twig y no quiere aprender un nuevo lenguaje de plantillas para cada proyecto TYPO3, el conector es la solución pragmática. Partials Twig existentes de proyectos Symfony o componentes Nunjucks de Pattern Libraries se reutilizan directamente.

Escenarios de uso habituales

Agencias con backend Symfony y frontend TYPO3. Una agencia desarrolla sus aplicaciones web en Symfony y usa TYPO3 solo para gestión de contenido. El equipo frontend ha construido una amplia librería de componentes Twig. En lugar de reescribir todos los componentes en Fluid para TYPO3, el conector integra las plantillas Twig existentes directamente en elementos de contenido Mask.

Integración de Pattern Library con Nunjucks. Un equipo de diseño mantiene una Pattern Library (por ejemplo, basada en Fractal o Storybook) que usa Nunjucks como lenguaje de plantillas. El conector permite usar las mismas plantillas Nunjucks tanto en la Pattern Library como en TYPO3.

Onboarding de desarrolladores frontend en proyectos TYPO3. Un nuevo desarrollador frontend se incorpora a un proyecto TYPO3. En lugar de aprender primero Fluid (sintaxis, namespaces, concepto de ViewHelper), escribe plantillas Twig que ya domina. La curva de aprendizaje se reduce de 2-3 días a pocas horas.

Arquitectura técnica

El mask_twig_nunjucks_connector funciona como puente de renderizado entre la extensión Mask y un motor de plantillas alternativo. Mask define Custom Content Elements con campos backend. Por defecto, Mask renderiza estos elementos con plantillas Fluid. El conector sustituye este paso de renderizado.

La integración Twig usa la librería PHP twig/twig (la misma que usa Symfony). Las plantillas Twig se ubican en el sistema de archivos, típicamente bajo Resources/Private/Twig/. Los campos Mask están disponibles como variables de plantilla ({{ data.header }}, {{ data.bodytext }}). La integración Nunjucks puede renderizar plantillas en servidor vía un puente Node.js o entregar las plantillas como JavaScript en el cliente.

Problemas frecuentes y soluciones

La plantilla Twig no tiene acceso a datos específicos de TYPO3. Fluid ViewHelpers como f:uri.page, f:translate o f:cObject no existen en Twig. Una plantilla Twig no puede acceder directamente al árbol de páginas TYPO3, traducciones u otros elementos de contenido. Solución: todos los datos necesarios deben proporcionarse vía variable mapping. El conector puede inyectar datos adicionales (idioma actual, URL de página, configuración global) en el contexto de la plantilla.

El renderizado Nunjucks es lento. El puente Node.js para renderizado Nunjucks en servidor inicia un proceso Node por cada petición. Eso no se nota con elementos individuales, pero con páginas con más de 10 elementos Mask los tiempos de renderizado se acumulan. Solución: usar un proceso Node.js worker persistente o cambiar a Twig, que renderiza nativamente en PHP.

Una actualización de Mask rompe los nombres de variables de plantilla. Si Mask renombra un campo o cambia un tipo de campo, las variables de plantilla cambian. Las plantillas Fluid muestran entonces espacios vacíos, las plantillas Twig lanzan un error. Solución: usar Twig en modo estricto (strict_variables: true) y testear plantillas contra las variables actualizadas tras cada actualización de Mask.

Migración y compatibilidad de versiones

El mask_twig_nunjucks_connector es un proyecto de la comunidad con difusión limitada. La compatibilidad depende de la extensión Mask, que se mantiene activamente y soporta TYPO3 v11 y v12. El conector debe verificarse con cada actualización de Mask, ya que se conecta a procesos internos de renderizado.

Gosign recomienda el conector para proyectos donde el equipo frontend trabaja exclusivamente con Twig y trae una librería de componentes existente. Para proyectos TYPO3 puros sin requisitos de plantillas externas, Fluid sigue siendo la mejor opción por su soporte nativo y el acceso a toda la biblioteca de ViewHelpers de TYPO3. La ganancia de productividad por reutilización de Twig debe superar el coste de mantenimiento del conector.