in2template dla TYPO3

Jednolity szkielet wprowadza strukturę do Site Packages, zanim staną się piekłem utrzymania

Kto w TYPO3 stawia Site Package dla dużej strony, staje za każdym razem przed tym samym pytaniem: jak zorganizować szablony, partiale, layouty i elementy treści tak, żeby za dwa lata wciąż były utrzymywalne? in2template pojawia się w przykładach kodu in2code jako nazwa własnego rozszerzenia projektu; nie zostało opublikowane ani w TER, ani na Packagist. Strukturalną odpowiedź daje szkielet, który dostarcza podstawowe rusztowanie dla nowoczesnych Site Packages: jasną strukturę katalogów, predefiniowane elementy treści, przygotowaną konfigurację dla TypoScript, Fluid Styled Content i layoutów backendowych. Dla zespołów TYPO3, które regularnie rozpoczynają nowe projekty, taki szkielet zastępuje starą praktykę copy-paste z poprzedniego projektu klienta udokumentowanym wzorcem.

Grupą docelową są agencje z kilkoma równoległymi projektami TYPO3 i zespoły inhouse, które pielęgnują corporate-templates dla stron koncernowych lub akademickich. Szczególnie tam, gdzie deweloperki i redaktorki dzielą Site Package, spójna konwencja folderów i nazw jest niezbędna do przetrwania. Jednolity szkielet adresuje dokładnie tę lukę.

Typowe scenariusze zastosowania

Pierwszym scenariuszem jest porządny start projektu. Agencja z ośmioma deweloperami i trzema działającymi projektami TYPO3 wprowadza własny szkielet jako wewnętrzny standard dla Site Packages. Każdy nowy projekt zaczyna się tym samym szkieletem: identyczna struktura katalogów, identyczne konwencje nazw, identyczna baza TypoScript. Wynik: deweloper może przechodzić między projektami bez konieczności każdorazowej reorientacji.

Drugim scenariuszem jest modernizacja starego Site Package. Portal uczelniany z 800 stronami i katalogiem szablonów, który rósł od TYPO3 v7, jest w ramach upgrade z v11 na v12 na nowo strukturyzowany. Zamiast dalej przenosić stary chaos, zespół buduje Site Package na bazie takiego szkieletu od nowa i stopniowo migruje treści.

Trzecim scenariuszem jest onboarding nowych redaktorów. Wydawnictwo z 30 redaktorami wyjaśnia na bazie szkieletu, które elementy treści są przeznaczone do czego. Spójność w nazewnictwie i strukturze skraca szkolenie, współczynnik błędów backendowych spada.

Czwartym scenariuszem jest wewnętrzny szablon refactoringu. Firma z pięcioma instalacjami TYPO3 z różnych lat chce długoterminowo przenieść Site Packages do jednolitej struktury. Jednolity wzorzec służy przy tym jako szkielet referencyjny, wobec którego każdy stary projekt jest stopniowo przebudowywany, bez konieczności omawiania przez zespół każdorazowo nowej struktury docelowej.

Architektura techniczna

Taki szkielet nie jest klasycznym add-onem, lecz szablonem dla własnego Site Package. Przynosi strukturę katalogów: Resources/Private/Templates, Resources/Private/Partials, Resources/Private/Layouts, Configuration/TypoScript, Configuration/TsConfig, Configuration/TCA/Overrides. Rusztowanie jest uzupełnione o przygotowane elementy treści (tekst, tekst z obrazem, akordeon, teaser-grid) i konfigurację dla layoutów backendowych.

Pakietu Composer nie ma; taki szkielet kopiuje się do własnego repozytorium Site Package i zmienia mu nazwę. W praktyce zespoły rzadko używają takiego szkieletu jako bezpośredniej zależności, typowe jest początkowe klonowanie, które następnie rośnie projektowo. To czyni szkielet starter-kitem, a nie frameworkiem, który musiałby być aktualizowany między wersjami.

Dla integracji z Fluid Styled Content istnieją własne mechanizmy override, które zapewniają, że dostarczone elementy treści koegzystują z elementami core. Ścieżki TypoScript są konsekwentnie namespaced, żeby kilka Site Packages mogło działać równolegle na tej samej instalacji.

Częste problemy i rozwiązania

Pierwszym problemem jest pomylenie z frameworkiem. Zespoły, które osadzają szkielet Site Package jak Bootstrap lub Tailwind i liczą na aktualizacje, doznają rozczarowania: szkielet to szablon do skopiowania, a nie stos upstream. Rozwiązaniem jest traktowanie szkieletu jako jednorazowego wzorca i wyraźne wersjonowanie powstającego z niego własnego Site Package.

Drugim problemem jest przeładowanie niewykorzystanymi elementami treści. Starter-kit przynosi więcej elementów, niż większość projektów potrzebuje. Kto ich nie używa, mimo to wlecze je przez utrzymanie. Rozwiązaniem jest cleanup bezpośrednio po początkowym imporcie: kasowanie niewykorzystanych elementów treści, usuwanie nieużywanych layoutów backendowych, skreślanie nieużywanych bloków TypoScript.

Trzecim problemem jest dostosowanie do indywidualnych systemów designu. Szkielety często dostarczają własne CSS z własnymi klasami utility. Kto używa istniejącego systemu designu z własnymi nazwami tokenów, musi konsekwentnie przekładać dostarczoną stylizację, inaczej powstaje dublowanie stylów i sprzeczna kaskada.

Czwartym problemem są konflikty z innymi starter-kitami. Kto częściowo przejmuje szkielet i równolegle integruje elementy z innego szkieletu, otrzymuje sprzeczne ścieżki TypoScript i nakładające się namespace’y Fluid. Rozwiązaniem jest na początku projektu decyzja dokładnie o jednym szkielecie i trzymanie niespójnych komponentów dodatkowych w jasno nazwanej warstwie projektowej.

Migracja i kompatybilność wersji

in2template nie zostało opublikowane, dlatego nie da się sprawdzić, które wersje TYPO3 obsługuje. Ponieważ szkielet w projektach prawie zawsze jest klonowany i dostosowywany, kwestia wersji jest mniej kwestią ścieżek update, a bardziej kwestią dyscypliny kodu: zespoły powinny przy upgrade swojego Site Package rzucić okiem na aktualne wzorce, takie jak Site Package Builder TYPO3, aby dociągnąć strukturalne ulepszenia (nowe konwencje layoutów backendowych, nowe wzorce Fluid).

Ważny przy upgrade Site Package opartego na in2template jest spojrzenie na zmienione konwencje TYPO3: TCA-Overrides, definicje layoutów backendowych, rejestracja elementów treści i renderowanie Fluid zmieniały się między v11 a v13 wielokrotnie. Kto nie dociąga tych zmian we własnym Site Package, ryzykuje, że treści w backendzie nagle wyglądają pusto lub wizardy elementów treści już się nie pojawiają.

Gosign przejmuje w projektach TYPO3 analizę, które części istniejącego Site Package można uporządkować według wzorca zbliżonego do in2template, a które lepiej zmigrować na własny, minimalistyczny szkielet. Wynikiem jest Site Package, które przechodzi przez code review bez szmerów i przy następnym upgrade TYPO3 nie produkuje niespodzianek.