in2template dla TYPO3

in2template 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? Rozszerzenie in2template z domu in2code jest próbą odpowiedzi na to pytanie w sposób strukturalny. 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, in2template 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. in2template 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 in2template 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 in2template od nowa i stopniowo migruje treści.

Trzecim scenariuszem jest onboarding nowych redaktorów. Wydawnictwo z 30 redaktorami wyjaśnia na bazie szkieletu in2template, 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. in2template 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

in2template nie jest klasycznym add-onem, lecz raczej szablonem dla własnego Site Package. Rozszerzenie 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.

Instalacja odbywa się jako klasyczne pobieranie Composer pakietu, który następnie jest kopiowany do własnego repozytorium Site Package i zmieniana jest mu nazwa. W praktyce zespoły rzadziej używają in2template jako bezpośredniej zależności, typowe jest początkowe klonowanie, które następnie rośnie projektowo. To czyni rozszerzenie 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ą in2template jak Bootstrap lub Tailwind i liczą na aktualizacje, doznają rozczarowania: rozszerzenie to szablon do skopiowania, a nie stos upstream. Rozwiązaniem jest traktowanie in2template 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. in2template dostarcza CSS zbliżone do Tailwind 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 in2template 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 jest utrzymywane przez in2code dla TYPO3 v11 i v12, kompatybilność z TYPO3 v13 jest aktualizowana wzdłuż cykli wydań samego TYPO3. Ponieważ rozszerzenie w projektach prawie zawsze jest klonowane i dostosowywane, 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 repozytorium in2template, 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.