TYPO3 v14: Tres cambios de última hora en Fluid 5 para integradores

Después de las innovaciones estratégicas, características prácticas y cambios en el manejo de activos en TYPO3 v14, es hora de hablar de Fluid 5. TYPO3 v14 viene con la nueva versión Fluid - y se limpia a fondo.

Tres cambios de última hora afectan directamente a las plantillas Fluid. La buena noticia: TYPO3 13.4.21 ya escribe advertencias de obsoletos en el registro si sus plantillas se ven afectadas. Así que ya se puede comprobar ahora.

1 Las secciones CDATA ya no se eliminan

¿Qué está cambiando?

Anteriormente, Fluid eliminaba completamente el código en bloques <![CDATA[ ]]>. Esto nunca se documentó, pero mucha gente lo utilizaba como solución para comentar el código de las plantillas.

Esto ya no funciona a partir de Fluid 5. Las secciones CDATA tienen ahora un significado diferente: resuelven un viejo problema con CSS y JavaScript en línea en las plantillas de Fluid.

El problema que ahora resuelve CDATA

La sintaxis de Fluid con llaves { } colisiona con CSS y JavaScript. Una consulta de medios como @media (min-width: 1000px) { ... } o JavaScript con objetos como const data = {key: value} han confundido anteriormente a Fluid.

Por ello, Fluid 5 introduce una nueva sintaxis en los bloques CDATA:

<f:variable name="color" value="rojo" />
<style>
<![CDATA[
    @media (min-width: 1000px) {
        p {
            color de fondo: {{{color}}};
        }
    }
]]>
</style>

La regla: Fluid ignora la sintaxis { } normal dentro de <![CDATA[ ]]>. En su lugar, utiliza tres llaves {{{ }}} para variables y ViewHelpers.

Los ViewHelpers basados en etiquetas ya no funcionan en absoluto en bloques CDATA, sólo la sintaxis en línea con tres corchetes.

Lo que hay que hacer

Si ha utilizado CDATA para comentar:

Sustituya <![CDATA[ ]]> por el ViewHelper <f:comment>:

<!-- Alt (ya no funciona): -->
<![CDATA[
<f:for each="{items}" as="item">
    {item.title}
</f:for>
]]>
<!-- Nuevo: -->
<f:comment>
<f:for each="{items}" as="item">
    {item.title}
</f:for>
</f:comment>

La ventaja: Desde TYPO3 13, <f:comment> también ignora la sintaxis incorrecta de Fluid. Así que usted también puede comentar el marcado no válido.

Si usted tiene CSS en línea o JavaScript en las plantillas:

Esto todavía no es una buena práctica. Pero si no puedes evitarlo, la nueva sintaxis CDATA funciona.

Mejor: Utiliza atributos data-*, propiedades personalizadas CSS o puntos finales API dedicados para pasar valores dinámicos a CSS y JavaScript.

Proyectos afectados

Desde TYPO3 13.4.21 Fluid escribe una depreciación en el registro si encuentra <![CDATA[ ]]> para comentar. Compruebe su registro de obsoletos antes de migrar a v14.

2. los nombres de variables con prefijo guión bajo están prohibidos

Qué cambia

Fluid 5 reserva todos los nombres de variables que empiecen por guión bajo para fines internos. Esto es similar a {_all}, que ha existido durante algún tiempo.

Estos ejemplos ya no funcionan:

<f:variable name="_temp" value="un valor temporal" />
{_temp}
<f:for each="{myArray}" as="_item">
    {_item}
</f:for>
<f:render partial="Pie de página" arguments="{_data: myData}" />

También en código PHP:

$view->assign('_data', $myData);
$view->asignarMúltiple([
    '_data' => $myData,
]);

Todos estos casos lanzan una excepción a partir de Fluid 5:

#1756622558 TYPO3Fluid\Fluid\Core\Variables\InvalidVariableIdentifierException
Los identificadores de variables no pueden empezar por "_": miVariable

Lo que NO se ve afectado

Losnombres de propiedades y claves de matrices siguen funcionando con guión bajo:

{myArray._myClave}
{myObject._myProperty}

Las variables internas como {_all} permanecen sin cambios:

<f:render partial="Pie de página" arguments="{_all}"/>

Migración

Simple: Cambie el nombre de las variables. En lugar de _temp use temp, en lugar de _item use item.

Desde TYPO3 13.4.21 Fluid también escribe una deprecación en el registro si se encuentran nombres de variables afectadas.

3. tipificación estricta en ViewHelpers

Fluid 5 se vuelve más estricto con los tipos. Esto afecta a tres áreas:

3.1 Validación más estricta de los argumentos ViewHelper.

Hasta ahora, Fluid tenía muchos puntos ciegos cuando se trataba de la validación de argumentos. Los ViewHelpers no podían confiar en que los tipos que definían en su API fueran correctos.

Ahora Fluid valida de forma más estricta. Los argumentos que antes se pasaban como "válidos" (pero que no coincidían con la API de ViewHelper) ahora se rechazan.

Buenas noticias: Fluid convierte automáticamente los tipos simples. Un ViewHelper que espera una cadena también acepta un int.

Para los integradores: algunas llamadas a ViewHelper que antes funcionaban ahora pueden fallar, pero de todos modos se trataba principalmente de errores en el código de la plantilla.

Para los desarrolladores de extensiones: Ahora puede confiar en los tipos de argumentos y eliminar la lógica de validación personalizada.

3.2 valores nulos en ViewHelpers basados en etiquetas

Anteriormente, el TagBuilder de Fluid trataba los valores nulos como cadenas vacías. Esto daba lugar a atributos HTML con un valor vacío:

<f:form.textfield name="myTextBox" placeholder="{variableQuePuedeSerNula}" />

Fluid 4 y anteriores:

<input type="text" name="miCajaDeTexto" placeholder="" />

Fluid 5:

<input type="text" name="miCajaDeTexto" />

El atributo se omite por completo.

ViewHelpers afectados en el núcleo de TYPO3:

• <f:media> y <f:image>
• <f:asset.css> y <f:asset.script>
• <f:form> y <f:form.*>
• <f:link.*> (excepto <f:link.typolink>, que utiliza TypoScript)
• <f:[be.link](<http://be.link>)>
• <be:enlace.*>
• <be:miniatura>

Impacto práctico: En la mayoría de los casos irrelevante. Pero con algunos ViewHelpers (por ejemplo, <f:image>) el núcleo tuvo que ser adaptado para mostrar siempre el atributo alt - incluso si el valor es cero.

3.3 Declaraciones de tipo de retorno en las clases ViewHelper

La ViewHelperInterface de Fluid requiere ahora tipos de retorno explícitos para todos los métodos.

Si desarrolla sus propios ViewHelpers, deberá adaptarlos:

class MyViewHelper extends AbstractViewHelper
{
    // render() debe especificar un tipo de retorno (no void)
    public function render(): string
    {
        return 'Hola Mundo';
    }
    // initialiseArguments() necesita void
    public function inicializarArgumentos(): void
    {
        $this->registerArgument('nombre', 'cadena', 'El nombre');
    }
}

Las propiedades NO se ven afectadas:

class MyViewHelper extends AbstractViewHelper
{
    protected $escapeOutput = false; // No necesita declaración de tipo
    protected $escapeChildren = false;
}

Este cambio es compatible con versiones anteriores. Así que usted puede personalizar sus extensiones ahora y van a trabajar con TYPO3 13 y anteriores.

Prueba automática difícil

Desafortunadamente, la mayoría de estos cambios no pueden ser analizados automáticamente. Dependen de valores variables específicos que se pasan a las plantillas en tiempo de ejecución.

En el lado positivo, la mayoría de los problemas que Fluid 5 descubre eran previamente errores - por ejemplo, cuando una matriz se pasa a un ViewHelper que espera una cadena.

La estrategia

Fluid 5 aclara las deudas técnicas:

• Sintaxis documentada en lugar de soluciones provisionales: CDATA recibe una función oficial en lugar de ser mal utilizado como un hack.
• Espacios de nombres más claros: prefijo underscore para variables internas para que las futuras versiones de Fluid no creen conflictos.
• Seguridad tipográfica: los ViewHelpers pueden confiar en su API, se requiere menos programación defensiva.

Esto encaja en la imagen de TYPO3 v14: menos legado, estructuras más claras, estándares modernos.

Cómo prepararse

Ya comprobable:

Desde TYPO3 13.4.21, Fluid Deprecations escribe en el registro si sus plantillas se ven afectadas por los dos primeros cambios de ruptura:

• CDATA para comentar
• Nombres de variables con prefijo guión bajo

Compruebe su registro de obsoletos antes de migrar a v14.

Explorador de extensiones para ViewHelper personalizados:

El escáner de extensiones encuentra ViewHelpers sin declaraciones de tipo de retorno. Si desarrolla sus propias extensiones, ejecútelo.

Pruebas en tiempo de ejecución:

Los otros cambios (validación de argumentos, manejo de nulos) dependen de los valores en tiempo de ejecución. El análisis automático no es posible. Pruebe a fondo sus plantillas después de la actualización.

Cómo mantenerse informado

TYPO3 v14 está todavía en desarrollo. Sigo filtrando los cambios relevantes del ChangeLog y presentándolos aquí en el blog.

Si quieres recibir actualizaciones directamente, suscríbete a mi boletín TYPO3. Allí recibirá los desarrollos más importantes en un formato compacto - sin ruido, sólo lo que es realmente relevante.

Por supuesto, habrá otro curso de vídeo completo sobre TYPO3 v14 - tan pronto como la versión esté más cerca de su lanzamiento.

Fuentes y enlaces

Todos los ejemplos de código en este artículo se toman directamente de la oficial TYPO3 ChangeLog y se han adoptado sin cambios.

Rompiendo #108148 - Secciones CDATA en plantillas fluidas ya no se eliminan

Característica #108148 - Alternativa sintaxis fluido para secciones CDATA

Rompiendo #108148 - No permitir nombres de variables Fluid con prefijo guión bajo

Irrupción #108148 - Tipos estrictos en ViewHelpers de Fluid