Styleguide para TYPO3

Por qué Styleguide es la extensión de QA más importante para desarrolladores de plantillas TYPO3

El desarrollo de plantillas en TYPO3 tiene un problema sistemático de calidad: los desarrolladores prueban sus plantillas Fluid con los datos que existen actualmente en la web. Pero los elementos de contenido tienen docenas de variantes - titulares con y sin subtítulo, bloques de texto con 3 palabras o 3 párrafos, imágenes en formato vertical y horizontal, tablas con 2 o 20 columnas. Quien solo revisa la página actual se pierde los casos extremos que aparecen después del lanzamiento.

La extensión Styleguide resuelve este problema creando automáticamente un árbol de páginas de demo que muestra cada elemento de contenido del Core en su propia página.

Escenarios de uso habituales

Desarrollo de plantillas en proyectos de relanzamiento. Una empresa encarga un relanzamiento TYPO3 con nuevo diseño corporativo. Sin Styleguide, el desarrollador frontend debe crear datos de prueba manualmente para cada elemento - con más de 30 elementos de contenido, eso lleva horas. Styleguide genera todos los datos de prueba automáticamente.

Tests de regresión tras actualizaciones TYPO3. Una actualización de v11 a v12 modifica sutilmente el renderizado de elementos individuales. Sin Styleguide, eso solo se detecta cuando un editor reporta el error en una página en producción. Con Styleguide, el desarrollador ve inmediatamente qué elementos han cambiado.

Coordinación entre equipo de diseño y desarrollo. Los diseñadores entregan mockups Figma para 10 elementos. Pero cómo se ven los 25 elementos estándar restantes en el nuevo diseño. Styleguide hace visible esta brecha: cada elemento tiene su propia página de demo, los diseños faltantes saltan a la vista inmediatamente.

Arquitectura técnica

Styleguide es una extensión Core oficial del sistema TYPO3, que desde v13 está en el repositorio del Core, pero no forma parte del paquete de código fuente. Se instala con Composer (typo3/cms-styleguide), hasta v12 también desde el TER, y después se activa. La extensión crea registros de prueba con valores sensatos para sus propias tablas de demo (tx_styleguide_*), que muestran casi todos los tipos de campo TCA del backend. Un módulo de backend permite crear y eliminar los datos de prueba. Un árbol de páginas propio muestra los elementos generados en el layout frontend, una página por tipo de contenido.

Styleguide no tiene dependencias externas. Al ser una extensión Core, se actualiza automáticamente con cada actualización de TYPO3.

Problemas frecuentes y soluciones

La página Styleguide muestra áreas vacías. Los datos de prueba se generaron pero la página frontend no muestra todos los elementos. Causa: las páginas de demo funcionan como sitio propio con su propio template raíz en lugar del de la web. Solución: verificar en el módulo de backend que el árbol de páginas se creó correctamente.

Faltan imágenes en los datos generados. Styleguide intenta incluir imágenes de prueba vía FAL. Styleguide trae sus propias imágenes de ejemplo y las copia al almacenamiento con UID 1; si falta o su configuración no es correcta, los campos de imagen quedan vacíos. Solución: revisar el almacenamiento fileadmin (UID 1) antes de generar los datos de prueba.

Problemas de rendimiento en la página Styleguide. Crear los árboles de páginas de demo genera muchos registros de golpe y, según la documentación, tarda unos segundos. Solución: activar Styleguide solo en entornos de desarrollo o staging, nunca en el sistema en producción.

Migración y compatibilidad de versiones

Styleguide está en el repositorio del Core desde TYPO3 v13 y se publica con cada versión de TYPO3. Hasta v12 tenía números de versión propios, el último 12.0.5. Tras una actualización TYPO3, los datos de prueba deben regenerarse ya que las definiciones TCA pueden cambiar entre versiones.

Gosign integra Styleguide en cada relanzamiento TYPO3 como parte fija del proceso de QA. La página Styleguide se configura en staging como referencia permanente y sirve al equipo de diseño como URL de validación. Para clientes enterprise con varias marcas o mandantes se genera una página Styleguide por mandante para comparar variantes de plantilla específicas por marca.