Mask Twig dla TYPO3

Dlaczego programiści frontend preferują Twig nad Fluid i jak Mask to umożliwia

TYPO3 z Fluid korzysta z silnika szablonów, który jest unikalny w świecie PHP. To jednocześnie jego siła i największy problem: programiści frontend przychodzący ze środowiska Symfony, Laravel lub Node.js znają Twig lub Nunjucks. Fluid nie znają. mask_twig_nunjucks_connector zamyka tę lukę, pozwalając renderować Mask Content Elements szablonami Twig lub Nunjucks zamiast szablonów Fluid.

Dla agencji, których zespół frontendowy pracuje z Twig i nie chce uczyć się nowego języka szablonów dla każdego projektu TYPO3, connector to pragmatyczne rozwiązanie. Istniejące parcjale Twig z projektów Symfony lub komponenty Nunjucks z Pattern Libraries można bezpośrednio ponownie wykorzystać.

Typowe scenariusze zastosowań

Agencje z backendem Symfony i frontendem TYPO3. Agencja rozwija swoje aplikacje webowe w Symfony i używa TYPO3 tylko do zarządzania treścią. Zespół frontend zbudował obszerną bibliotekę komponentów Twig. Zamiast przepisywać wszystkie komponenty na Fluid, connector wbudowuje istniejące szablony Twig bezpośrednio w Mask Content Elements.

Integracja Pattern Library z Nunjucks. Zespół projektowy zarządza Pattern Library (np. na bazie Fractal lub Storybook) używającą Nunjucks jako języka szablonów. Connector pozwala używać tych samych szablonów Nunjucks zarówno w Pattern Library, jak i w TYPO3.

Onboarding programistów frontend w projektach TYPO3. Nowy programista frontend zaczyna w projekcie TYPO3. Zamiast najpierw uczyć się Fluid (składnia, przestrzenie nazw, koncepcja ViewHelper), pisze szablony Twig, które już zna. Krzywa uczenia się dla projektu skraca się z 2 do 3 dni do kilku godzin.

Architektura techniczna

mask_twig_nunjucks_connector działa jako most renderujący między rozszerzeniem Mask a alternatywnym silnikiem szablonów. Mask definiuje Custom Content Elements z polami backendowymi. Standardowo Mask renderuje te elementy szablonami Fluid. Connector zastępuje ten krok renderujący.

Integracja Twig korzysta z biblioteki PHP twig/twig (tej samej, której używa Symfony). Szablony Twig leżą w systemie plików, typowo pod Resources/Private/Twig/. Pola Mask są dostępne jako zmienne szablonu ({{ data.header }}, {{ data.bodytext }}). Integracja Nunjucks może renderować szablony po stronie serwera przez most Node.js lub dostarczać je po stronie klienta jako szablony JavaScript.

Zależności: TYPO3 Core, rozszerzenie Mask, pakiet Composer twig/twig (dla Twig) lub Node.js (dla serwerowego Nunjucks). W praktyce ponad 90% instalacji connectora używa Twig, nie Nunjucks, ponieważ Twig natywnie działa w PHP i nie wymaga zewnętrznego procesu.

Częste problemy i rozwiązania

Szablon Twig nie ma dostępu do danych specyficznych dla TYPO3. Fluid-ViewHelper takie jak f:uri.page, f:translate czy f:cObject nie istnieją w Twig. Rozwiązanie: wszystkie potrzebne dane muszą być dostarczane przez mapowanie zmiennych. Connector może przez konfigurację wstrzykiwać dodatkowe dane (aktualny język, URL strony, globalne ustawienia) do kontekstu szablonu.

Renderowanie Nunjucks jest wolne. Most Node.js do serwerowego renderowania Nunjucks uruchamia dla każdego żądania proces Node. Rozwiązanie: użycie trwałego procesu workera Node.js lub przejście na Twig, który renderuje natywnie w PHP.

Aktualizacja Mask łamie nazwy zmiennych szablonu. Gdy Mask zmieni nazwę pola lub typ pola, zmieniają się zmienne szablonu. Szablony Fluid wtedy pokazują puste miejsca, szablony Twig rzucają błąd. Rozwiązanie: uruchomienie Twig w trybie strict (strict_variables: true) i testowanie szablonów po każdej aktualizacji Mask.

Migracja i kompatybilność wersji

mask_twig_nunjucks_connector to projekt społecznościowy o ograniczonym zasięgu. Kompatybilność zależy od rozszerzenia Mask: Mask jest aktywnie utrzymywane i wspiera TYPO3 v11 i v12. Connector musi być sprawdzany pod kątem kompatybilności przy każdej aktualizacji Mask.

Gosign zaleca connector dla projektów, w których zespół frontend pracuje wyłącznie z Twig i posiada istniejącą bibliotekę komponentów. Dla czystych projektów TYPO3 bez zewnętrznych wymagań szablonowych Fluid pozostaje lepszym wyborem, ponieważ jest natywnie wspierane, nie ma dodatkowych zależności i może korzystać z całej biblioteki ViewHelper TYPO3. Zysk produktywności przez ponowne użycie Twig musi przekraczać nakład utrzymania connectora - kalkulacja, którą należy konkretnie przeprowadzić przy każdym starcie projektu.