TYPO3 v14: Drie Fluïde 5 baanbrekende veranderingen voor integrators

Na de strategische vernieuwingen, praktische functies en assetveranderingen in TYPO3 v14, is het tijd om over Fluid 5 te praten. TYPO3 v14 wordt geleverd met de nieuwe Fluid versie - en deze ruimt grondig op.

Drie ingrijpende veranderingen hebben direct invloed op Fluid-sjablonen. Het goede nieuws: TYPO3 13.4.21 schrijft al deprecatiewaarschuwingen naar het logboek als uw sjablonen worden beïnvloed. Dus u kunt het nu al controleren.

1 CDATA secties worden niet langer verwijderd

Wat verandert er?

Voorheen verwijderde Fluid code in <![CDATA[ ]]> blokken volledig. Dit was nooit gedocumenteerd, maar veel mensen gebruikten het als een workaround om templatecode uit te commentariëren.

Vanaf Fluid 5 werkt dit niet meer. CDATA-secties hebben nu een andere betekenis: ze lossen een oud probleem op met inline CSS en JavaScript in Fluid-sjablonen.

Het probleem dat CDATA nu oplost

De syntaxis van Fluid met accolades { } botst met CSS en JavaScript. Een media query zoals @media (min-width: 1000px) { ... } of JavaScript met objecten zoals const data = {key: value} brachten Fluid eerder in verwarring.

Fluid 5 introduceert daarom een nieuwe syntaxis in CDATA-blokken:

<f:variabele name="kleur" value="rood" />
<style>
<![CDATA[
    @media (min-width: 1000px) {
        p {
            achtergrondkleur: {{color}};
        }
    }
]]>
</style>

De regel: Fluid negeert de normale { } syntaxis binnen <![CDATA[ ]]>. In plaats daarvan gebruikt u drie accolades {{ }}} voor variabelen en ViewHelpers.

Tag-gebaseerde ViewHelpers werken helemaal niet meer in CDATA-blokken - alleen de inline syntaxis met drie haakjes.

Wat je moet doen

Als je CDATA hebt gebruikt voor commentaar:

Vervang <![CDATA[ ]]> door de <f:comment> ViewHelper:

<!-- Alt (werkt niet meer): -->
<![CDATA[
<f:for each="{items}" as="item">
    {item.title}
</f:for>
]]>
<!-- Nieuw: -->
<f:comment>
<f:for each="{items}" as="item">
    {item.title}
</f:for>
</f:comment>

Het voordeel: Sinds TYPO3 13 negeert <f:comment> ook onjuiste Fluid-syntaxis. U kunt dus ook ongeldige markup uitcommentariëren.

Als u inline CSS of JavaScript in sjablonen hebt:

Dit is nog steeds geen goede gewoonte. Maar als u het niet kunt vermijden, werkt de nieuwe CDATA-syntaxis.

Beter: Gebruik data-* attributen, CSS aangepaste eigenschappen of speciale API-eindpunten om dynamische waarden door te geven aan CSS en JavaScript.

Betreffende projecten

Sinds TYPO3 13.4.21 schrijft Fluid een deprecation naar het logboek als het <![CDATA[ ]]> vindt om uit te commentariëren. Controleer je deprecation log voordat je migreert naar v14.

2. variabele namen met underscore voorvoegsel zijn verboden

Wat verandert er?

Fluid 5 reserveert alle variabelenamen die beginnen met een underscore voor interne doeleinden. Dit is vergelijkbaar met {_all}, dat al enige tijd bestaat.

Deze voorbeelden werken niet meer:

<f:variabele name="_temp" value="een tijdelijke waarde" />
{_temp}
<f:for each="{myArray}" as="_item">
    {_item}
</f:for>
<f:render partial="Footer" arguments="{_data: myData}" />

Ook in PHP code:

$view->assign('_data', $myData);
$view->assignMultiple([
    '_data' => $myData,
]);

Al deze gevallen gooien een uitzondering vanaf Fluid 5:

#1756622558 TYPO3Fluid\Fluid\Core\Variabelen\InvalidVariableIdentifierException
Variabele identifiers kunnen niet beginnen met een "_": _mijnVariabele

Wat wordt NIET beïnvloed

Namen van eigenschappen en array-sleutels werken nog steeds met underscore:

{myArray._myKey}
{mijnObject._mijnEigenschap}

Interne variabelen zoals {_all} blijven ongewijzigd:

<f:render partial="Footer" arguments="{_all}"/>

Migratie

Eenvoudig: Hernoem de variabelen. In plaats van _temp gebruik temp, in plaats van _item gebruik item.

Sinds TYPO3 13.4.21 schrijft Fluid ook een deprecation in het log als de betreffende variabelennamen worden gevonden.

3. Strikt typen in ViewHelpers

Fluid 5 wordt strenger met types. Dit heeft invloed op drie gebieden:

3.1 Strengere validatie van ViewHelper-argumenten.

Tot nu toe had Fluid veel blinde vlekken als het ging om argumentvalidatie. ViewHelpers konden er niet op vertrouwen dat de types die ze in hun API definieerden correct waren.

Nu valideert Fluid strenger. Argumenten die voorheen als "geldig" werden doorgegeven (maar niet overeenkwamen met de ViewHelper API) worden nu afgewezen.

Goed nieuws: Fluid converteert eenvoudige types automatisch. Een ViewHelper die een string verwacht, accepteert ook een int.

Voor integrators: Sommige ViewHelper-aanroepen die eerder werkten, kunnen nu mislukken - maar dit waren meestal bugs in de sjablooncode.

Voor uitbreidingsontwikkelaars: Je kunt nu vertrouwen op de argumenttypes en aangepaste validatielogica verwijderen.

3.2 nulwaarden in tag-gebaseerde ViewHelpers

Voorheen behandelde Fluid's TagBuilder nulwaarden als lege tekenreeksen. Dit resulteerde in HTML-attributen met een lege waarde:

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

Fluid 4 en eerder:

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

Fluid 5:

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

Het attribuut is volledig weggelaten.

Getroffen ViewHelpers in de TYPO3-kern:

• <f:media> en <f:image>
• <f:asset.css> en <f:asset.script>
• <f:form> en <f:form.*>
• <f:link.*> (behalve <f:link.typolink>, die gebruikt TypoScript)
• <f:[be.link](<http://be.link>)>
• <be:link.*>
• <be:thumbnail>

Praktisch effect: In de meeste gevallen irrelevant. Maar met sommige ViewHelpers (bijv. <f:image>) moest de core worden aangepast om altijd het alt-attribuut weer te geven - zelfs als de waarde nul is.

3.3 Terugkeertype-declaraties in ViewHelper-klassen

Fluid's ViewHelperInterface vereist nu expliciete terugkeertypes voor alle methoden.

Als u uw eigen ViewHelpers ontwikkelt, moet u deze aanpassen:

class MyViewHelper extends AbstractViewHelper
{
    // render() moet een terugkeertype specificeren (niet void)
    publieke functie render(): string
    {
        return 'Hello World';
    }
    // initialiseerArgumenten() heeft leegte nodig
    publieke functie initialiseerArgumenten(): void
    {
        $this->registreerArgument('naam', 'string', 'De naam');
    }
}

Eigenschappen worden NIET beïnvloed:

class MyViewHelper extends AbstractViewHelper
{
    protected $escapeOutput = false; // Geen type declaratie nodig
    protected $escapeChildren = false;
}

Deze wijziging is achterwaarts compatibel. Dus je kunt je extensies nu aanpassen en ze zullen werken met TYPO3 13 en eerder.

Automatisch testen moeilijk

Helaas kunnen de meeste van deze wijzigingen niet automatisch worden gescand. Ze zijn afhankelijk van specifieke variabele waarden die tijdens runtime worden doorgegeven aan sjablonen.

Aan de positieve kant waren de meeste problemen die Fluid 5 aan het licht bracht eerder bugs - bijvoorbeeld wanneer een array werd doorgegeven aan een ViewHelper die een string verwacht.

De strategie erachter

Fluid 5 ruimt technische schulden op:

• Gedocumenteerde syntaxis in plaats van workarounds: CDATA krijgt een officiële functie in plaats van misbruikt te worden als hack.
• Duidelijkere namespaces: Underscore prefix voor interne variabelen zodat toekomstige Fluid-versies geen conflicten veroorzaken.
• Typeveiligheid: ViewHelpers kunnen vertrouwen op hun API, minder defensief programmeren vereist

Dit past in het plaatje van TYPO3 v14: minder legacy, duidelijkere structuren, moderne standaarden.

Hoe bereid je jezelf voor

Al testbaar:

Sinds TYPO3 13.4.21 schrijft Fluid Deprecations naar het logboek als je sjablonen worden beïnvloed door de eerste twee brekende wijzigingen:

• CDATA voor uitcommentaar
• Variabele namen met underscore voorvoegsel

Controleer uw deprecatielogboek voordat u migreert naar v14.

Extension Scanner voor aangepaste ViewHelper:

De Extension Scanner vindt ViewHelpers zonder aangiften van terugkeertypes. Als u uw eigen extensies ontwikkelt, voer deze dan uit.

Runtimetests:

De andere wijzigingen (argumentvalidatie, null-afhandeling) zijn afhankelijk van runtime-waarden. Automatisch scannen is niet mogelijk. Test je sjablonen grondig na de upgrade.

Op de hoogte blijven

TYPO3 v14 is nog steeds in ontwikkeling. Ik blijf de relevante wijzigingen uit de ChangeLog filteren en presenteer ze hier in de blog.

Als je direct updates wilt ontvangen, schrijf je dan in voor mijn TYPO3 nieuwsbrief. Daar ontvang je de belangrijkste ontwikkelingen in een compact formaat - zonder ruis, alleen wat echt relevant is.

Er komt natuurlijk weer een uitgebreide videocursus over TYPO3 v14 - zodra de versie dichter bij de release is.

Bronnen & links

Alle codevoorbeelden in dit artikel komen rechtstreeks uit de officiële TYPO3 ChangeLog en zijn ongewijzigd overgenomen.

Doorbraak #108148 - CDATA secties in Fluid sjablonen niet langer verwijderd

Feature #108148 - Alternatieve Fluid syntaxis voor CDATA secties

Doorbraak #108148 - Fluid variabele namen met Underscore voorvoegsel niet toestaan

Onderbreking #108148 - Strict Types in Fluid ViewHelpers