Twig w Drupal – wprowadzenie do templatingu

Twig stał się standardowym silnikiem szablonów w Drupal od wersji 8, zmieniając sposób, w jaki front‑endowcy i backendowcy współpracują nad warstwą prezentacji. Zamiast skomplikowanego PHP w plikach templatów, otrzymujemy czytelny, bezpieczny i elastyczny język składniowy, który pomaga kontrolować **prezentację**, nie mieszając jej z logiką biznesową. Dzięki temu tworzenie **motywów**, nadpisywanie widoków oraz personalizacja wyglądu serwisu stają się znacznie prostsze i bardziej przewidywalne.

Podstawy Twig w Drupal

Czym jest Twig i dlaczego trafił do Drupal

Twig to silnik templatingu dla PHP, rozwijany w ekosystemie Symfony. Został zaprojektowany jako prosty w użyciu, ale jednocześnie bardzo **wydajny** i elastyczny sposób generowania HTML. W Drupal zastąpił stare pliki *.tpl.php*, w których logika i prezentacja często się mieszały.

Główne założenia Twig to:

• oddzielenie logiki PHP od warstwy **szablonów**,
• większe bezpieczeństwo dzięki filtrowaniu danych,
• łatwiejsza współpraca frontend–backend,
• przejrzysta i spójna składnia.

W praktyce oznacza to, że w szablonie można korzystać z prostych konstrukcji: wypisywania zmiennych, pętli, warunków czy filtrów, bez zagłębiania się w pełną składnię PHP. Programista PHP przygotowuje dane w warstwie preprocess lub w kontrolerach, a front‑end pracuje na gotowych kontekstach w plikach *.html.twig*.

Różnice między Twig a starym systemem tpl.php

W starszych wersjach Drupal szablony były plikami PHP, w których dozwolone było praktycznie wszystko: wywoływanie funkcji, logika warunkowa, zapytania do bazy. Powodowało to często chaos i trudności w utrzymaniu motywów. Twig radykalnie ogranicza to, co można zrobić bezpośrednio w szablonach, premiując minimalizm i przejrzystość.

Najważniejsze zmiany:

• w szablonach Twig nie wykonujemy bezpośrednio kodu PHP,
• wszystko opiera się na kontekście zmiennych przekazanym z Drupal,
• brak możliwości „szybkich hacków” w pliku szablonu – trzeba korzystać z preprocess lub modułów,
• czytelniejsza składnia: {{ }} dla wypisywania zmiennych, {% %} dla logiki.

Dzięki temu warstwa prezentacji jest mniej podatna na błędy, łatwiejsza do przeglądania przez osoby nietechniczne, a motywy stają się bardziej **modularne** i przewidywalne.

Składnia: zmienne, filtry, funkcje

Podstawowe elementy składni Twig w Drupal to:

• {{ zmienna }} – wypisanie wartości,
• {{ zmienna|filter }} – zastosowanie filtra,
• {% if %}, {% for %}, {% set %} – sterowanie logiką,
• {# komentarz #} – komentarz, niewidoczny w HTML.

Filtry pomagają na przykład w modyfikowaniu tekstu, formatowaniu dat czy czyszczeniu danych. Funkcje Twig (i rozszerzenia dodawane przez Drupal) dostarczają dodatkowych narzędzi, jak generowanie URL, tłumaczenia, czy sprawdzanie uprawnień.

Ważne jest, że większość zadań powinna być przygotowana wcześniej – w *preprocess* – a Twig ma jedynie zająć się **prezentacją** końcową. Tym sposobem szablon pozostaje prosty, a większość logiki jest testowalna w kodzie PHP.

Struktura plików *.html.twig* w motywach

Drag and drop w przypadku Twig nie istnieje, ale jego struktura jest bardzo hierarchiczna. Motyw może zawierać różne pliki *.html.twig*, odpowiedzialne za konkretne części strony:

• page.html.twig – główny szablon strony,
• node.html.twig – sposób prezentacji pojedynczego węzła,
• field.html.twig – ogólny szablon pola,
• block.html.twig – szablon bloku,
• region.html.twig – definicja regionów strony.

Dodatkowo można tworzyć wersje specyficzne, np. node–article.html.twig, aby zmienić wygląd tylko jednego typu zawartości. Drupal wybiera najbardziej szczegółowy pasujący szablon na podstawie systemu tzw. *theme suggestions* (podpowiedzi motywów).

Praca z kontekstem i zmiennymi w Twig

Skąd biorą się zmienne w szablonach Drupal

Drupal przekazuje do każdego szablonu zestaw zmiennych. W przypadku node.html.twig są to np. elementy typu content, node, label, url, w page.html.twig – regiony, tytuł, ścieżka. Źródłem są głównie:

• warstwa renderowania Drupal,
• funkcje preprocess (np. THEME_preprocess_node),
• hooki modułów, które dodają lub modyfikują dane.

Tak przygotowany kontekst jest następnie przekazywany do Twig jako tablice i obiekty. Frontendowiec nie musi wiedzieć, skąd dokładnie pochodzą dane – wystarczy znać ich strukturę, aby móc je **wyświetlić** i odpowiednio sformatować. Szczegółowe listy dostępnych zmiennych często znajdują się w komentarzach w plikach szablonów lub w dokumentacji.

Najczęściej używane zmienne globalne

W większości szablonów dostępne są tzw. zmienne globalne Drupal, które bardzo ułatwiają pracę:

• base_path – podstawowy adres do serwisu,
• is_front – informacja, czy użytkownik jest na stronie głównej,
• logged_in – flaga zalogowania użytkownika,
• user – obiekt aktualnego użytkownika,
• directory – ścieżka do aktywnego motywu.

Dzięki nim łatwo można np. zmieniać układ strony na stronie głównej, ukrywać lub pokazywać fragmenty interfejsu tylko dla zalogowanych albo warunkowo dołączać **zasoby** specyficzne dla motywu. Zmiennych globalnych jest więcej i są one rozszerzane przez moduły, dlatego warto korzystać z narzędzi inspekcyjnych, aby dobrze poznać swój kontekst.

Korzyści z użycia Kint i debugowania Twig

Jedną z najpraktyczniejszych metod pracy z Twig w Drupal jest użycie narzędzi takich jak Kint oraz debugowania motywu. Po włączeniu trybu developerskiego można:

• zobaczyć wszystkie dostępne sugestie szablonów w komentarzach HTML,
• podejrzeć strukturę zmiennych przy pomocy Kint (funkcja kint() w preprocess),
• odkryć, jakie pola i właściwości są aktualnie przekazywane do pliku *.html.twig*.

Debug Twig włącza się w pliku konfiguracyjnym usług Drupal (services.yml), ustawiając odpowiednie opcje. Po odświeżeniu strony w kodzie HTML pojawią się metadane opisujące, który plik szablonu został użyty, jakie są inne możliwe propozycje, oraz skąd one pochodzą. To ogromna pomoc przy tworzeniu złożonych **motywów**.

Dobre praktyki w zarządzaniu kontekstem

Aby utrzymać szablony w dobrej kondycji, warto stosować kilka zasad:

• maksymalnie ograniczać logikę w Twig – zamiast tego używać preprocess,
• jasno nazywać zmienne dodawane w preprocess, aby od razu sugerowały przeznaczenie,
• nie przekazywać zbędnych danych do Twig – im prostszy kontekst, tym łatwiej go testować,
• unikać powielania tych samych konstrukcji – korzystać z includów i bloków.

Dobre zarządzanie kontekstem sprzyja budowaniu **komponentów** wielokrotnego użytku i ułatwia migrację motywu lub jego rozbudowę. Dzięki temu praca nad większym projektem Drupal nie zamienia się w serię trudnych do śledzenia zależności i wyjątków.

Logika prezentacji: warunki, pętle i dziedziczenie

Instrukcje warunkowe w Twig

Choć Twig nie pozwala na swobodny kod PHP, oferuje podstawowe mechanizmy sterowania logiką prezentacji. Najpopularniejsze to instrukcje warunkowe if, elseif, else. Umożliwiają one uzależnienie wyświetlania części szablonu od wartości przekazanych zmiennych, np. sprawdzenie, czy pole nie jest puste lub czy użytkownik posiada określoną rolę.

Typowe zastosowania to:

• warunkowe dodawanie klas CSS,
• ukrywanie elementów dla anonimowych użytkowników,
• różny układ danych dla różnych typów węzłów.

Ważne, aby nie nadużywać warunków i nie przenosić do Twig zbyt skomplikowanej logiki. Jeśli warunek ma wiele gałęzi lub korzysta z zaawansowanych danych, lepiej przygotować wynik w preprocess i w szablonie operować prostą flagą lub już gotową strukturą.

Pętle i budowanie list

Drugim podstawowym narzędziem jest pętla for. Umożliwia przechodzenie po tablicach i kolekcjach, takich jak listy pól, elementy widoku (View) czy kolekcje encji. Z pomocą for wygodnie buduje się listy artykułów, galerie, zestawienia kategorii. Możliwe jest też korzystanie z dodatkowych zmiennych w pętli, np. loop.index czy loop.first, aby modyfikować wygląd pierwszego elementu lub numerować pozycje.

W kontekście Drupal częstym przypadkiem jest iteracja po polach z wieloma wartościami albo po wynikach widoku blokowego. Dzięki pętlom w Twig można łatwo:

• dodawać separator po każdym elemencie z wyjątkiem ostatniego,
• aplikować różne klasy do elementów parzystych i nieparzystych,
• tworzyć **struktury** list i siatek (grid) dopasowane do designu.

Dziedziczenie szablonów i bloki

Jedną z najmocniejszych funkcji Twig jest dziedziczenie szablonów. Pozwala ono zdefiniować bazowy layout, zawierający sekcje-bloki (block), a następnie nadpisywać je w szablonach potomnych. Dzięki temu można tworzyć spójne układy strony i jednocześnie różnicować szczegóły w zależności od typu zawartości.

Za pomocą dziedziczenia można:

• zdefiniować wspólny szablon dla wszystkich podstron danego typu,
• tworzyć „szkielet” layoutu z nagłówkiem, stopką i regionami,
• łatwo rozbudowywać istniejące **komponenty** o nowe warianty.

Moduły i motywy bazowe (base theme) często korzystają z tej możliwości, definiując ogólne bloki, które motyw podrzędny może rozszerzać. Pozwala to łączyć konsekwencję wizualną z elastycznością przy zmianach.

Includy i fragmenty wielokrotnego użytku

Drugim mechanizmem wspierającym ponowne wykorzystanie kodu są inkludowane fragmenty szablonów. Za pomocą include (lub embed) można wczytać osobny plik Twig odpowiedzialny np. tylko za wyświetlanie teasera artykułu, pojedynczego elementu listy czy karty produktu.

Stosowanie inkludów ma kilka zalet:

• ułatwia utrzymanie – zmiana szablonu komponentu odbywa się w jednym miejscu,
• sprzyja budowaniu biblioteki **komponentów** front‑end,
• pozwala różnym częściom systemu korzystać z tych samych wzorców.

W praktyce przy większych serwisach Drupal często tworzy się cały katalog z komponentami Twig, a główne szablony tylko składają je w odpowiednie layouty. Taki podział dobrze współgra z podejściem atomic design i integracją z narzędziami typu Pattern Lab.

Integracja Twig z motywami i preprocess

Rola preprocess w przygotowaniu danych

Funkcje preprocess w Drupal są kluczowym elementem łączącym PHP z Twig. To właśnie tam przygotowuje się dane, które później są wykorzystywane w szablonach – można dodawać własne zmienne, modyfikować istniejące, budować specjalne struktury dla widoków i pól.

Typowe zastosowania preprocess to:

• tworzenie skrótów lub uproszczonych struktur danych na potrzeby Twig,
• mapowanie pól na bardziej czytelne **nazwy** zmiennych,
• dodawanie klas CSS zależnie od stanu encji lub parametru URL,
• łączenie danych z różnych źródeł w jeden zestaw dla szablonu.

W ten sposób szablony Twig pozostają możliwie proste, a cała „inteligencja” budowania kontekstu jest po stronie PHP. To dobra praktyka, która zwiększa testowalność i przewidywalność kodu.

Konwencje nazewnicze plików Twig w motywach

Drupal wykorzystuje rozbudowany system rozpoznawania szablonów na podstawie ich nazwy. Przykład: node–article–full.html.twig będzie bardziej szczegółową wersją niż ogólne node.html.twig. Zasada jest prosta: im więcej elementów w nazwie, tym bardziej specyficzny przypadek obsługujemy.

Najczęściej stosowane warianty:

• node–TYPE.html.twig – typ węzła,
• node–TYPE–VIEW_MODE.html.twig – typ węzła i tryb wyświetlania,
• page–front.html.twig – strona główna,
• block–MODULE–ID.html.twig – konkretny blok.

Rozumienie tych konwencji pozwala precyzyjnie kontrolować, który szablon będzie wykorzystywany w danym miejscu. W połączeniu z podpowiedziami z debuggera Twig łatwo odnaleźć właściwą nazwę pliku i przygotować własny, dostosowany do potrzeb projektowych.

Rozszerzanie Twig poprzez moduły Drupal

Wiele modułów rozszerza możliwości Twig, dodając nowe filtry, funkcje czy testy. Dzięki temu można np. generować przyjazne URL, sprawdzać uprawnienia użytkownika, korzystać z tłumaczeń albo odwoływać się do konfiguracji. Każde takie rozszerzenie należy jednak traktować ostrożnie – łatwo wprowadzić zbyt wiele logiki do warstwy prezentacji.

Dobrym podejściem jest korzystanie z rozszerzeń Twig do:

• zadań typowo prezentacyjnych (np. formatowanie),
• wywołań, które są ściśle związane z wyglądem i nie mają sensu w logice biznesowej,
• integracji z systemem tłumaczeń i **interfejsem** użytkownika.

Jeśli natomiast dana operacja dotyczy logiki aplikacji, powinna zostać zrealizowana po stronie kodu PHP, przed przekazaniem danych do szablonu.

Stylowanie i klasy CSS w połączeniu z Twig

Ostatnim, bardzo praktycznym obszarem jest współpraca Twig z warstwą CSS. Drupal generuje wiele klas automatycznie (np. bazujących na typie węzła czy słowach kluczowych), ale Twig pozwala również na dynamiczne dodawanie własnych. Często stosuje się tablice klas, które w preprocess są uzupełniane o dodatkowe wartości, po czym wypisywane w szablonie.

Taki mechanizm umożliwia budowę elastycznego systemu styli, w którym klasy odpowiadają konkretnym stanom lub rodzajom treści. Twig używany jest wyłącznie do ich **wyświetlania** i prostego łączenia, a logika wyboru, które klasy mają się pojawić, leży po stronie preprocess. W rezultacie powstaje przejrzysty, łatwy do analizowania HTML, który dobrze współgra z nowoczesnymi metodykami CSS, takimi jak BEM.