TYPO3 v14: Trzy przełomowe zmiany Fluid 5 dla integratorów

Po strategicznych innowacjach, praktycznych funkcjach i zmianach w obsłudze zasobów w TYPO3 v14, nadszedł czas, aby porozmawiać o Fluid 5. TYPO3 v14 jest dostarczany z nową wersją Fluid - i dokładnie ją czyści.

Trzy przełomowe zmiany mają bezpośredni wpływ na szablony Fluid. Dobra wiadomość: TYPO3 13.4.21 już zapisuje ostrzeżenia o wycofaniu w dzienniku, jeśli dotyczy to szablonów. Możesz to sprawdzić już teraz.

1 Sekcje CDATA nie są już usuwane

Co się zmienia

Wcześniej Fluid całkowicie usuwał kod w blokach <![CDATA[ ]]>. Nigdy nie zostało to udokumentowane, ale wiele osób używało tego jako obejścia do komentowania kodu szablonu.

Nie działa to już od wersji Fluid 5. Sekcje CDATA mają teraz inne znaczenie: rozwiązują stary problem z inline CSS i JavaScript w szablonach Fluid.

Problem, który teraz rozwiązuje CDATA

Składnia Fluida z nawiasami klamrowymi { } koliduje z CSS i JavaScript. Zapytanie o media, takie jak @media (min-width: 1000px) { ... } lub JavaScript z obiektami takimi jak const data = {key: value} wcześniej dezorientowały Fluid.

Fluid 5 wprowadza zatem nową składnię w blokach CDATA:

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

Zasada: Fluid ignoruje normalną składnię { } w <![CDATA[ ]]>. Zamiast tego należy użyć trzech nawiasów klamrowych {{ }}} dla zmiennych i ViewHelperów.

ViewHelpery oparte na tagach nie działają już w ogóle w blokach CDATA - tylko składnia inline z trzema nawiasami.

Co należy zrobić

Jeśli użyłeś CDATA do komentowania:

Zastąp <![CDATA[ ]]> ViewHelperem <f:comment>:

<!-- Alt (już nie działa): -->
<![CDATA[
<f:for each="{items}" as="item">
    {item.title}
</f:for>
]]>
<!-- Nowość: -->
<f:comment>
<f:for each="{items}" as="item">
    {item.title}
</f:for>
</f:comment>

Zaleta: Od TYPO3 13, <f:comment> ignoruje również nieprawidłową składnię Fluid. Można więc również komentować nieprawidłowe znaczniki.

Jeśli masz wbudowany CSS lub JavaScript w szablonach:

Nadal nie jest to dobra praktyka. Ale jeśli nie możesz tego uniknąć, nowa składnia CDATA działa.

Lepiej: Użyj atrybutów data-*, niestandardowych właściwości CSS lub dedykowanych punktów końcowych API, aby przekazać dynamiczne wartości do CSS i JavaScript.

Projekty, których to dotyczy

Od wersji TYPO3 13.4.21 Fluid zapisuje deprecjację w dzienniku, jeśli znajdzie <![CDATA[ ]]> do skomentowania. Sprawdź dziennik deprecjacji przed migracją do wersji 14.

2. nazwy zmiennych z prefiksem podkreślenia są zabronione.

Co się zmienia

Fluid 5 rezerwuje wszystkie nazwy zmiennych zaczynające się od podkreślenia do celów wewnętrznych. Jest to podobne do {_all}, które istniało już od jakiegoś czasu.

Te przykłady już nie działają:

<f:variable name="_temp" value="wartość tymczasowa" />
{_temp}
<f:for each="{myArray}" as="_item">
    {_item}
</f:for>
<f:render partial="Footer" arguments="{_data: myData}" />

Również w kodzie PHP:

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

Wszystkie te przypadki powodują wyjątek od wersji Fluid 5:

#1756622558 TYPO3Fluid\\Fluid\\Core\\\Variables\\InvalidVariableIdentifierException
Identyfikatory zmiennych nie mogą zaczynać się od "_": _myVariable

Co NIE uległo zmianie

Nazwy właściwości i klucze tablic nadal działają z podkreśleniem:

{myArray._myKey}
{myObject._myProperty}

Zmienne wewnętrzne, takie jak {_all}, pozostają niezmienione:

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

Migracja

Proste: Zmień nazwy zmiennych. Zamiast _temp użyj temp, zamiast _item użyj item.

Od wersji TYPO3 13.4.21 Fluid zapisuje również deprecjację w dzienniku, jeśli znaleziono zmienione nazwy zmiennych.

3. ścisłe wpisywanie w ViewHelpers

Fluid 5 staje się bardziej rygorystyczny z typami. Dotyczy to trzech obszarów:

3.1 Bardziej rygorystyczna walidacja argumentów ViewHelpera.

Do tej pory Fluid miał wiele martwych punktów, jeśli chodzi o walidację argumentów. ViewHelperzy nie mogli ufać, że typy zdefiniowane w ich API są poprawne.

Teraz Fluid waliduje bardziej rygorystycznie. Argumenty, które wcześniej były przekazywane jako "prawidłowe" (ale nie pasowały do API ViewHelper) są teraz odrzucane.

Dobra wiadomość: Fluid automatycznie konwertuje proste typy. ViewHelper, który oczekuje ciągu znaków, akceptuje również int.

Dla integratorów: Niektóre wywołania ViewHelper, które działały wcześniej, mogą teraz zawieść - ale i tak były to głównie błędy w kodzie szablonu.

Dla twórców rozszerzeń: Możesz teraz polegać na typach argumentów i usunąć niestandardową logikę walidacji.

3.2 Wartości null w ViewHelperach opartych na tagach

Wcześniej TagBuilder Fluida traktował wartości null jako puste ciągi znaków. Skutkowało to atrybutami HTML z pustą wartością:

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

Fluid 4 i wcześniejsze:

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

Fluid 5:

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

Atrybut jest całkowicie pominięty.

Dotknięte ViewHelpers w rdzeniu TYPO3:

• <f:media> i <f:image>.
• <f:asset.css> i <f:asset.script>
• <f:form> i <f:form.*>
• <f:link.*> (z wyjątkiem <f:link.typolink>, który używa TypoScript)
• <f:[be.link](<http://be.link>)>
• <be:link.*>
• <be:thumbnail>

Praktyczny wpływ: W większości przypadków nieistotne. Jednak w przypadku niektórych ViewHelperów (np. <f:image>) rdzeń musiał zostać dostosowany, aby zawsze renderować atrybut alt - nawet jeśli jego wartość wynosi zero.

3.3 Deklaracje typów zwracanych w klasach ViewHelper

Interfejs ViewHelperInterface Fluida wymaga teraz jawnych typów zwracanych dla wszystkich metod.

Jeśli tworzysz własne ViewHelpery, musisz je dostosować:

class MyViewHelper extends AbstractViewHelper
{
    // render() powinna określać typ zwracany (nie void)
    public function render(): string
    {
        return 'Hello World';
    }
    // initialiseArguments() wymaga void
    public function initialiseArguments(): void
    {
        $this->registerArgument('name', 'string', 'The name');
    }
}

Nie ma to wpływu na właściwości:

class MyViewHelper extends AbstractViewHelper
{
    protected $escapeOutput = false; // Deklaracja typu nie jest konieczna
    protected $escapeChildren = false;
}

Ta zmiana jest kompatybilna wstecz. Możesz więc teraz dostosować swoje rozszerzenia i będą one działać z TYPO3 13 i wcześniejszymi.

Automatyczne testowanie trudne

Niestety, większość z tych zmian nie może być skanowana automatycznie. Zależą one od konkretnych wartości zmiennych, które są przekazywane do szablonów w czasie wykonywania.

Z drugiej strony, większość problemów wykrytych przez Fluid 5 była wcześniej błędami - na przykład, gdy tablica została przekazana do ViewHelpera, który oczekuje ciągu znaków.

Stojąca za tym strategia

Fluid 5 usuwa błędy techniczne:

• Udokumentowana składnia zamiast obejść: CDATA otrzymuje oficjalną funkcję zamiast być nadużywanym jako hack.
• Bardziej przejrzyste przestrzenie nazw: Prefiks podkreślenia dla zmiennych wewnętrznych, aby przyszłe wersje Fluid nie powodowały konfliktów.
• Bezpieczeństwo typów: ViewHelperzy mogą polegać na swoim API, wymagane jest mniej programowania defensywnego.

Pasuje to do obrazu TYPO3 v14: mniej spuścizny, bardziej przejrzyste struktury, nowoczesne standardy.

Jak się przygotować

Już testowalne:

Od wersji TYPO3 13.4.21, Fluid Deprecations zapisuje do logu, jeśli twoje szablony są dotknięte przez pierwsze dwie przełomowe zmiany:

• CDATA do komentowania
• Nazwy zmiennych z prefiksem podkreślenia.

Sprawdź dziennik deprecjacji przed migracją do wersji 14.

Skaner rozszerzeń dla niestandardowego ViewHelpera:

Skaner rozszerzeń znajduje ViewHelpery bez deklaracji typu zwracanego. Jeśli tworzysz własne rozszerzenia, uruchom go.

Testy środowiska uruchomieniowego:

Pozostałe zmiany (walidacja argumentów, obsługa wartości null) zależą od wartości runtime. Automatyczne skanowanie nie jest możliwe. Po aktualizacji należy dokładnie przetestować szablony.

Jak być na bieżąco

TYPO3 v14 jest nadal w fazie rozwoju. Nadal filtruję istotne zmiany z ChangeLog i prezentuję je tutaj na blogu.

Jeśli chcesz otrzymywać aktualizacje bezpośrednio, zapisz się do mojego newslettera TYPO3. Otrzymasz tam najważniejsze zmiany w kompaktowym formacie - bez szumu, tylko to, co jest naprawdę istotne.

Oczywiście pojawi się kolejny kompleksowy kurs wideo na temat TYPO3 v14 - gdy tylko wersja będzie bliżej wydania.

Źródła i linki

Wszystkie przykłady kodu w tym artykule pochodzą bezpośrednio z oficjalnego TYPO3 ChangeLog i zostały przyjęte bez zmian.

Łamanie #108148 - sekcje CDATA w szablonach Fluid nie są już usuwane

Funkcja #108148 - Alternatywna składnia Fluid dla sekcji CDATA

Łamanie #108148 - Niedozwolone nazwy zmiennych Fluid z prefiksem podkreślenia

Łamanie #108148 - ścisłe typy we Fluid ViewHelpers