Nadpisywanie szablonów w Drupal (theme overrides)

Nadpisywanie szablonów w Drupal to jedno z kluczowych narzędzi front-end developera, który chce mieć pełną kontrolę nad warstwą prezentacji. Dzięki mechanizmowi theme overrides można precyzyjnie dostosować HTML generowany przez system, bez ingerencji w kod rdzenia ani modułów. To fundament pracy nad jakością kodu, dostępnością, wydajnością i spójnością wizualną serwisu opartego na Drupal.

Podstawy systemu szablonów w Drupal

Jak działa warstwa templatów w Drupal

Drupal korzysta z silnika Twig, aby generować HTML na podstawie danych dostarczanych przez warstwę PHP. Każda strona, blok czy element listy jest renderowany przez konkretny plik z rozszerzeniem .html.twig. Kluczową rolę odgrywa tu tzw. drzewo renderowania, w którym poszczególne elementy mają swoje typy (np. node, block, field) oraz warianty (bundle, view mode, region, itd.).

System szablonów wyszukuje najpierw najbardziej specyficzny plik szablonu, a jeśli go nie znajdzie, korzysta z bardziej ogólnego. Dzięki temu mechanizmowi możliwe jest bardzo precyzyjne nadpisywanie szablonów dla konkretnego typu zawartości, widoku czy nawet pojedynczego węzła – przy zachowaniu domyślnej logiki dla reszty serwisu.

Hierarchia i priorytety szablonów

Najważniejszym pojęciem przy nadpisywaniu jest hierarchia szablonów. Drupal generuje listę możliwych nazw plików, zaczynając od najbardziej szczegółowych, a kończąc na ogólnych. Przykładowo dla węzła typu article może to wyglądać tak:

• node–article–full.html.twig
• node–article.html.twig
• node–full.html.twig
• node.html.twig

Jeśli w aktywnym motywie znajduje się plik node–article–full.html.twig, ten szablon zostanie użyty. Jeżeli nie – Drupal przejdzie do node–article.html.twig, i tak dalej. Rozumienie tej kolejności jest kluczowe, bo pozwala planować, które szablony nadpisywać globalnie, a które tylko dla wybranych podtypów treści.

Rola motywu bazowego i motywu potomnego

W wielu projektach stosuje się podział na motyw bazowy (base theme) oraz motyw potomny (subtheme). Nadpisywanie szablonów prawie zawsze powinno odbywać się w subtheme, aby zachować możliwość aktualizacji motywu bazowego. Motyw potomny dziedziczy wszystkie szablony, biblioteki i ustawienia, ale może je dowolnie nadpisywać, umieszczając własne pliki o tej samej nazwie i strukturze katalogów.

Dobrą praktyką jest traktowanie motywu bazowego jako stabilnej warstwy fundamentu, a motywu potomnego jako przestrzeni na modyfikacje specyficzne dla projektu, klienta lub brandu. Dzięki temu można użyć jednego motywu bazowego w wielu wdrożeniach i utrzymywać spójny zestaw rozwiązań.

Gdzie szukać informacji o dostępnych szablonach

Najbardziej użytecznym narzędziem jest moduł Devel oraz podmoduł Kint. Po włączeniu opcji debugowania Twig (w services.yml) można zobaczyć w kodzie strony komentarze HTML z listą możliwych szablonów i ścieżką do plików. To właśnie tam widać, które nazwy plików są generowane dla danego elementu, co ułatwia zaplanowanie theme overrides.

Dodatkowo w dokumentacji Drupala oraz w interfejsie admina (np. w konfiguracji bloków, widoków czy typów treści) znajdziemy wskazówki dotyczące konwencji nazewniczych. Im częściej będziesz korzystać z podglądu debugowania Twig, tym szybciej zaczniesz rozpoznawać różne konteksty i ich domyślne szablony.

Nadpisywanie szablonów Twig krok po kroku

Włączanie trybu debugowania Twig

Aby skutecznie nadpisywać szablony, warto na środowisku deweloperskim włączyć debug Twig. Robi się to w pliku services.yml (najczęściej sites/development.services.yml), ustawiając odpowiednie parametry dla container debug oraz twig.debug. Po wyczyszczeniu cache, w wygenerowanym HTML pojawią się komentarze z informacjami o tym, które szablony są używane i jakie alternatywy są dostępne.

Ten krok jest kluczowy dla pracy z nadpisywaniem, ponieważ bez niego zgadujesz nazwy plików, zamiast opierać się na konkretnej liście wygenerowanej przez system. Debug Twig pomaga też zrozumieć drzewo renderowania i zależności pomiędzy elementami.

Tworzenie własnych plików .html.twig

Nadpisanie szablonu polega na skopiowaniu pliku z motywu bazowego lub modułu do katalogu szablonów w motywie potomnym, a następnie na jego modyfikacji. Przykładowy schemat:

• Znajdź oryginalny plik, np. core/modules/node/templates/node.html.twig.
• Skopiuj go do themes/custom/twoj_temat/templates/node.html.twig.
• Dostosuj strukturę HTML, klasy CSS, atrybuty i zawartość zmiennych.

Zachowanie nazwy pliku i struktury katalogów jest konieczne, aby Drupal rozpoznał plik jako override. Nie trzeba natomiast kopiować całej zawartości, jeżeli tworzymy nowy wariant na bazie listy nazw wygenerowanych przez debug Twig – wystarczy utworzyć plik o poprawnej nazwie i wykorzystać dostarczone zmienne.

Cache, rebuild i kontrola zmian

Po dodaniu lub zmianie szablonu konieczne jest wyczyszczenie pamięci podręcznej. W praktyce korzysta się z komendy drush cr albo odpowiedniej opcji w panelu administracyjnym. Bez odświeżenia cache Drupal nadal będzie używać poprzednio zkompilowanych wersji szablonów.

Aby zachować porządek, warto stosować system kontroli wersji (np. Git) i grupować zmiany w szablonach w logiczne commity. Nadpisywanie szablonów bardzo szybko rozrasta się do dużej liczby plików, dlatego dobra organizacja i opis zmian jest kluczowa dla utrzymania jakości i możliwości łatwego cofania nieudanych modyfikacji.

Najczęstsze pułapki przy theme overrides

Jednym z najczęstszych problemów jest literówka w nazwie pliku lub złe umiejscowienie pliku w drzewie katalogów. Drupal nie zgłosi błędu – po prostu zignoruje taki plik. Dlatego warto zawsze weryfikować, czy po wyczyszczeniu cache nowy szablon pojawia się w komentarzach debug Twig jako używany.

Inna pułapka to zbyt agresywne nadpisywanie ogólnych szablonów, np. node.html.twig czy field.html.twig. Zmiana takich plików wpływa na cały serwis, co może spowodować trudne do przewidzenia efekty. Zaleca się stosowanie bardziej specyficznych wariantów i korzystanie z hierarchii, aby ograniczać zasięg modyfikacji do tego, co naprawdę potrzebne.

Praktyczne wzorce nadpisywania dla najczęstszych elementów

Szablony węzłów (node) i trybów wyświetlania

Węzły (nodes) to podstawowe jednostki treści w Drupal. Każdy typ treści (bundle) może mieć wiele trybów wyświetlania (view modes), np. full, teaser czy custom. Nadpisywanie szablonów zwykle realizuje się wg schematu:

• node–article.html.twig – dla wszystkich węzłów typu article, we wszystkich trybach.
• node–article–teaser.html.twig – dla teasera typu article.
• node–page.html.twig – dla statycznych stron.

W szablonie mamy dostęp do takich zmiennych jak label, content, node czy attributes. Dobrą praktyką jest korzystanie z przekazanych atrybutów zamiast ręcznego budowania klas i id, aby zachować kompatybilność z modułami, które modyfikują drzewo renderowania.

Dla złożonych projektów często buduje się spójny system komponentów, w którym node.html.twig jedynie „opakuje” zawartość w konkretny komponent (np. kartę artykułu). Dzięki temu zmiana wyglądu jednego typu treści jest możliwa przez modyfikację niewielkiej liczby plików.

Nadpisywanie pól (field) i ich wariantów

Pola (fields) są niezwykle elastyczne, ale domyślne szablony często nie wystarczają, gdy potrzebujemy specyficznego HTML. Dla pól istnieje rozbudowana konwencja nazewnicza, np. field–node–field_image.html.twig albo field–paragraph–field_title.html.twig. To pozwala precyzyjnie określić, jak ma wyglądać jedno konkretne pole w danym kontekście.

Często stosuje się też nadpisywanie dla konkretnego typu pola, np. field–image.html.twig, aby ustalić wspólne zasady generowania tagów img, figure czy picture. W połączeniu z responsywnymi stylami graficznymi i atrybutami alt można w ten sposób podnieść dostępność i jakość techniczną serwisu.

Bloki, regiony i menu

Bloki (block) i regiony są kluczowe dla układu strony. Szablon block.html.twig jest stosunkowo ogólny, ale dzięki hierarchii możemy tworzyć warianty per moduł, per ID albo per region. Na przykład block–system-menu-block-main.html.twig pozwala całkowicie przebudować HTML głównego menu, zachowując jednocześnie konfigurację struktury w panelu administracyjnym.

Regiony (region) mają własne szablony, takie jak region–header.html.twig czy region–footer.html.twig. Nadpisanie ich pozwala łatwo kontrolować strukturę wrapperów, klas CSS i dodatkowych znaczników (np. kontenerów grid). To istotne, gdy wdrażasz spójny system layoutu oparty na wybranym frameworku CSS.

Widoki (Views) i ich wyjścia

Moduł Views generuje listy treści, tabele, siatki i wiele innych struktur. Dla każdego widoku można nadpisać szablon oparty o jego nazwę i wyświetlanie (display). Przykładowe pliki to views-view–articles.html.twig albo views-view-fields–articles–block_1.html.twig. Dzięki temu można bardzo precyzyjnie dostosować layout list, karuzel, galerii czy tabel.

Silne wykorzystanie views template overrides pozwala zbudować spójny system list i komponentów kart, zamiast powielać podobne struktury w wielu różnych szablonach node. To przekłada się na łatwiejsze utrzymanie, wyższą czytelność kodu oraz możliwość ponownego wykorzystania tych samych wzorców w innych częściach serwisu.

Zaawansowane techniki i dobre praktyki theme overrides

Preprocess i rozszerzanie zmiennych Twig

Samo nadpisanie szablonu często nie wystarczy – potrzebujemy dodatkowych danych lub przetworzonych wartości. Służą do tego funkcje preprocess i process w plikach .theme albo w osobnych plikach PHP w motywie. Dzięki nim można dodać nowe zmienne, wyliczyć stany logiczne, połączyć wartości kilku pól czy wygenerować klasy na podstawie warunków biznesowych.

Dobrą praktyką jest maksymalne ograniczenie logiki w Twig i przeniesienie jej do preprocess. Szablon ma odpowiadać za wizualną strukturę i proste warunki, a nie za złożone operacje na danych. Poprawia to czytelność i wspiera rozdzielenie odpowiedzialności między warstwą prezentacji a logiką.

Dziedziczenie Twig, include i komponentyzacja

Twig umożliwia stosowanie dziedziczenia (extends), wstawek (include) i bloków (blocks). W kontekście Drupala oznacza to możliwość budowania systemu komponentów, w którym powtarzalne fragmenty HTML są przechowywane w osobnych plikach, np. w katalogu templates/components.

Możesz zdefiniować bazowy szablon komponentu, np. card.html.twig, a następnie wykorzystywać go w wiele miejscach – w node, views, block czy paragraphs. Dzięki temu zmiana wyglądu komponentu wymaga modyfikacji jednego pliku, a nie kilkunastu rozrzuconych override’ów. To podejście jest szczególnie wartościowe w większych projektach o rozbudowanym design system.

Organizacja katalogów i konwencje nazewnicze

Im większy projekt, tym większe ryzyko chaosu w katalogu templates. Dobrym podejściem jest grupowanie szablonów według typu (np. node, field, block, views) i komponentów. Możesz tworzyć podkatalogi, takie jak templates/node, templates/field, templates/components, pamiętając jednocześnie o aktualizacji ścieżek w motywie (jeśli używasz customowych namespace’ów Twig).

Ważne jest przyjęcie spójnej konwencji nazewniczej. Można np. dodać prefiksy projektowe do komponentów albo ustalić, że wszystkie szablony związane z konkretnym modułem lub funkcjonalnością trzymasz w dedykowanym podkatalogu. Dzięki temu nowi członkowie zespołu szybciej odnajdują się w strukturze kodu.

Wydajność, bezpieczeństwo i utrzymanie

Każde nadpisanie szablonu niesie konsekwencje dla wydajności i utrzymania. Zbyt rozdrobniony system override’ów może utrudnić debugowanie i zwiększyć ryzyko błędów przy aktualizacjach modułów czy rdzenia. Dlatego przed dodaniem nowego pliku warto zadać sobie pytanie, czy na pewno jest konieczny i czy nie da się osiągnąć celu przy pomocy istniejących szablonów i preprocess.

Z perspektywy bezpieczeństwa kluczowe jest odpowiednie filtrowanie danych. Twig w Drupalu domyślnie escapuje zmienne, ale należy uważać przy stosowaniu filtrów raw czy safe. Nigdy nie wstawiaj niesprawdzonych danych użytkownika bezpośrednio do HTML. Korzystaj z escapowania i przekazuj wartości przefiltrowane po stronie PHP, jeśli musisz z nimi wykonać niestandardowe operacje.