Tworzenie własnego motywu Drupal – podstawy

Własny motyw w Drupal to sposób na pełną kontrolę nad wyglądem i strukturą serwisu, bez kompromisów wynikających z gotowych szablonów. Pozwala odwzorować identyfikację wizualną marki, zoptymalizować wydajność i ułatwić dalszy rozwój projektu. W tym artykule przejdziemy przez kluczowe elementy tworzenia motywu: strukturę plików, integrację z systemem szablonów Twig, nadpisywanie templatek oraz dobre praktyki pracy z CSS i bibliotekami zasobów.

Fundamenty motywu Drupal – jak to działa

Motyw a podmotyw – który model wybrać

Tworząc własny motyw Drupal, na początku musisz zdecydować, czy budujesz:

• motyw główny (tzw. base theme z punktu widzenia Twojego projektu),
• podmotyw (subtheme) oparty na istniejącym motywie bazowym.

Podmotyw to świetne rozwiązanie, gdy chcesz szybko wystartować, wykorzystując sprawdzone rozwiązania z motywu bazowego, np. Claro (administracja) lub motywów społeczności. Dziedziczysz wówczas gotowe szablony, style i logikę, a Twoje pliki jedynie je rozszerzają lub nadpisują.

Tworzenie motywu od zera daje maksymalną swobodę, ale wymaga lepszej znajomości systemu. Masz pełną kontrolę nad strukturą HTML, ładowaniem bibliotek i integracją z Twig. Dobrą praktyką jest wybranie podejścia pośredniego: oprzeć się na lekkim motywie bazowym, a w miarę nabierania doświadczenia przenosić część logiki i stylów do własnego niezależnego motywu.

Struktura katalogów i konwencje nazewnictwa

Standardowo motywy użytkownika umieszcza się w katalogu:

/themes/custom/nazwa_motywu

Wewnątrz tego katalogu zwykle znajdują się:

• nazwa_motywu.info.yml – główny plik konfiguracyjny motywu,
• nazwa_motywu.libraries.yml – definicje bibliotek CSS i JS,
• nazwa_motywu.theme – funkcje i hooki PHP związane z motywem,
• templates/ – folder z plikami Twig,
• css/, js/, images/ – zasoby front-end, opcjonalnie podzielone na moduły.

Nazwy plików powinny być spójne z nazwą motywu. Drupal przykłada dużą wagę do konsekwentnego, konfiguracyjnego stylu: małe litery, podkreślenia zamiast spacji, czytelne segmenty. Dzięki temu mechanizmy auto-ładowania i rozpoznawania plików działają bez dodatkowych konfiguracji.

Rola pliku .info.yml

Plik .info.yml to serce każdego motywu. Określa jego nazwę, opis, wersję Drupala oraz podstawowe parametry. Przykładowy minimalny plik może wyglądać następująco (bez stosowania cudzysłowów na początku i końcu całego bloku):

name: Mój motyw
type: theme
description: Motyw stworzony na potrzeby serwisu firmowego
core_version_requirement: ^10 || ^9
base theme: stable9
libraries:
– moj_motyw/global-styling
regions:
header: Nagłówek
content: Zawartość
footer: Stopka

Najważniejsze elementy to:

• core_version_requirement – informuje, z jaką wersją Drupala motyw jest kompatybilny,
• base theme – pozwala zdefiniować motyw bazowy, jeśli tworzysz podmotyw,
• regions – określa dostępne regiony dla bloków i treści.

Odpowiednie zdefiniowanie regionów ułatwia później konfigurację layoutu z poziomu panelu administracyjnego, bez modyfikowania kodu.

Cache, konfiguracja i tryb deweloperski

Podczas pracy nad motywem ważne jest zrozumienie, jak Drupal buforuje dane. System intensywnie korzysta z cache, aby przyspieszyć działanie serwisu, ale w trakcie tworzenia motywu może to utrudniać podgląd zmian. Typowy workflow obejmuje:

• włączenie trybu debugowania Twig,
• częste czyszczenie cache (np. drush cr),
• tymczasowe wyłączenie agresywnego cache front-endu.

Włączenie debugowania Twig dodaje do kodu HTML komentarze z informacją, który plik szablonu był użyty do renderowania danej części strony. To kluczowe, gdy chcesz ustalić, jaki plik nadpisać w katalogu templates. Dzięki temu modyfikacje motywu stają się znacznie bardziej przewidywalne i uporządkowane.

Tworzenie podstawowego motywu krok po kroku

Zakładanie katalogu i plików startowych

Pierwszy krok to utworzenie katalogu w themes/custom, np.:

/themes/custom/moj_motyw

Następnie dodajesz minimalne pliki:

• moj_motyw.info.yml – definicja motywu,
• moj_motyw.libraries.yml – definicja bibliotek,
• moj_motyw.theme – opcjonalnie, już na start.

W pliku .info.yml określasz podstawowe informacje, w libraries.yml – globalne style i skrypty, np. global-styling. Po utworzeniu plików wyczyść cache i przejdź do panelu administracyjnego Wygląd, gdzie powinien pojawić się nowy motyw. Aktywacja motywu ustawia go jako motyw domyślny dla frontu serwisu.

Definiowanie bibliotek CSS i JS

Plik libraries.yml służy do rejestrowania zasobów CSS i JavaScript. Definiujesz w nim nazwy bibliotek, powiązane pliki oraz ewentualne zależności. Przykładowa biblioteka:

global-styling:
css:
theme:
css/style.css: {}
js:
js/script.js: {}

Tę bibliotekę następnie dołączasz w pliku .info.yml, np. w sekcji libraries. Dzięki temu każdy request front-endu ładuje globalny zestaw stylów i skryptów. Drupal umożliwia także tworzenie dodatkowych bibliotek, które możesz przypisywać tylko do konkretnych typów treści, bloków lub widoków, co pozwala ograniczać nadmiarowe ładowanie zasobów.

Organizacja plików stylów i skryptów

Dla porządku warto od początku przyjąć jasną strukturę katalogów:

• css/base – reset, zmienne, typografia, elementy globalne,
• css/components – style dla konkretnych bloków i widgetów,
• css/layout – układy stron, siatki, nagłówek, stopka,
• js/components – skrypty do interaktywnych elementów,
• js/vendor – biblioteki zewnętrzne.

Jeśli korzystasz z narzędzi typu Sass, Webpack, Vite albo Gulp, możesz trzymać pliki źródłowe w osobnym katalogu src, a wynikowe style kompilować do css. Pamiętaj, że w libraries.yml wskazujesz finalne pliki generowane, a nie źródła. Taka separacja ułatwia utrzymanie projektu w dłuższej perspektywie.

Aktywacja motywu i testowanie podstaw

Po przygotowaniu wstępnych plików wykonaj:

• drush cr – jeśli używasz Drush,
• lub wyczyść cache z poziomu interfejsu administracyjnego.

Następnie w sekcji Wygląd ustaw swój motyw jako domyślny. Po przeładowaniu strony sprawdź, czy:

• ładuje się podstawowy CSS,
• nie ma błędów w logach (Raporty → Dzienniki),
• regiony zdefiniowane w info.yml są widoczne w konfiguracji bloków.

Na tym etapie motyw może wyglądać bardzo surowo, ale ważne jest, by fundamenty działały poprawnie. Kolejne kroki to praca nad szablonami Twig oraz dostosowanie struktury HTML do Twoich potrzeb projektowych.

Praca z Twig – szablony i nadpisywanie widoków

Jak działają szablony Twig w Drupal

Drupal wykorzystuje Twig jako system szablonów. Każdy element strony – węzeł (node), blok, formularz, koment – jest renderowany na podstawie odpowiedniego pliku .html.twig. Mechanizm wybiera najbardziej szczegółowy dostępny szablon na podstawie kontekstu, np. typu treści lub widoku.

Przykład dla węzłów (nodes):

• node.html.twig – szablon ogólny dla wszystkich węzłów,
• node–article.html.twig – dla typu treści article,
• node–article–teaser.html.twig – dla teaserów artykułu.

Gdy chcesz zmienić sposób wyświetlania konkretnego typu treści, kopiujesz odpowiadający mu szablon z motywu bazowego (lub z katalogu core) do swojego motywu, do folderu templates, nadając odpowiednią nazwę. Po czyszczeniu cache Drupal zaczyna używać Twojej wersji pliku.

Włączanie debugowania Twig i lokalizowanie szablonów

Tryb debugowania Twig jest nieoceniony podczas tworzenia motywu. Po jego włączeniu w źródle HTML pojawiają się komentarze z informacją, który szablon renderuje daną część strony, a także lista potencjalnych nazw szablonów, które możesz nadpisać.

Uaktywnienie debugowania odbywa się poprzez modyfikację services.yml (np. w sites/development.services.yml) i ustawienie parametrów debug: true oraz auto_reload: true, a także wyłączenie cache Twig dla środowiska deweloperskiego. Dzięki temu każda zmiana w szablonach jest widoczna po odświeżeniu strony, bez konieczności ciągłego czyszczenia cache.

Patrząc w komentarze debugowe, łatwo zidentyfikujesz np. że dany blok używa szablonu block–views-block–nazwa-widoku.html.twig, a główna zawartość strony korzysta z page.html.twig lub jego bardziej specyficznej odmiany. To znacząco skraca czas potrzebny na znalezienie właściwego pliku do modyfikacji.

Struktura podstawowego szablonu strony

Centralnym elementem motywu jest szablon page.html.twig. Określa on główną strukturę strony: nagłówek, główną zawartość, sidebar, stopkę. Wewnątrz umieszczasz regiony zdefiniowane w info.yml, np.:

• header – logo, menu główne, pasek wyszukiwania,
• content – treść główna,
• sidebar_first, sidebar_second – boczne panele,
• footer – informacje o prawach autorskich, linki pomocnicze.

Przykładowy fragment może zawierać kontener dla treści i logikę warunkową sprawdzającą, czy dany region posiada przypisane bloki. Twig umożliwia stosowanie zmiennych przekazywanych z warstwy PHP, filtrów (np. escape, date) oraz prostych konstrukcji logicznych, dzięki czemu układ strony można elastycznie dopasować do treści.

Nadpisywanie szablonów dla konkretnych elementów

Poza główną strukturą, często potrzebujesz dopasować wygląd konkretnych elementów:

• node–typ_tresci.html.twig – indywidualne layouty dla treści,
• block–id_bloku.html.twig – dedykowane szablony dla wybranych bloków,
• paragraph–typ_paragrafu.html.twig – w przypadku użycia Paragraphs,
• views-view–nazwa-widoku.html.twig – szablony dla widoków (Views).

Drupal generuje zestaw możliwych nazw na podstawie kontekstu (ID, ścieżka, typ treści). Wybierając najbardziej precyzyjną z nich, możesz modyfikować tylko ten fragment, który Cię interesuje, bez wpływu na resztę serwisu. To pozwala tworzyć elastyczne, rozbudowane interfejsy użytkownika, w pełni zgodne z wymaganiami projektu.

Stylowanie, wydajność i dobre praktyki

Separacja warstw: HTML, CSS i logika

Projektując motyw, warto trzymać się zasad czystego podziału warstw:

• struktura HTML i szablony Twig – w katalogu templates,
• stylowanie – w plikach CSS lub preprocesorach,
• logika prezentacyjna – w pliku .theme i ewentualnych usługach PHP.

Unikaj logiki biznesowej w szablonach Twig. Jeśli musisz przetworzyć dane, użyj preprocesorów (hook_preprocess_*), które przygotują wygodne zmienne dla Twig. Dzięki temu szablony pozostają czytelne, a zmiany logiki można wprowadzać w jednym miejscu. To szczególnie istotne w większych projektach, gdzie zespół designerów i programistów backend współpracuje nad tym samym motywem.

Praca z klasami CSS i BEM

Dobra praktyka to stosowanie spójnej metodologii nazewnictwa klas CSS, np. BEM. Drupal generuje własne klasy (np. node, region, block), ale warto dodawać własne, bardziej semantyczne nazwy, które ułatwiają stylowanie i utrzymanie kodu.

Preprocesory PHP pozwalają dodać klasy do elementów przed renderowaniem. Możesz np. przypisywać różne klasy w zależności od typu treści lub ról użytkownika. Dzięki temu motyw może reagować na kontekst aplikacji, zachowując przejrzystość i minimalizując powielanie stylów. Rozważ tworzenie komponentów wielokrotnego użytku, takich jak karty, bannery, przyciski, które są stylowane raz, a używane w wielu miejscach.

Optymalizacja ładowania zasobów i wydajność

Wydajność to kluczowy element dobrze zaprojektowanego motywu. Drupal zapewnia mechanizmy agregowania i kompresowania CSS oraz JS, ale motyw może dodatkowo zadbać o:

• ładowanie tylko niezbędnych bibliotek na danej podstronie,
• używanie atrybutów async i defer dla skryptów (jeśli to bezpieczne),
• optymalizację obrazów i wykorzystanie stylów obrazów (image styles),
• minimalizowanie liczby zapytań HTTP.

Możesz definiować mniejsze, wyspecjalizowane biblioteki w libraries.yml, zamiast jednej ogromnej. Następnie przypisujesz je tylko tam, gdzie są rzeczywiście potrzebne – np. dodatkowy skrypt tylko na landing page lub stylowanie specyficzne dla formularzy. To przekłada się na krótszy czas ładowania i lepsze doświadczenie użytkownika.

Przygotowanie motywu na rozwój i modyfikacje

Motyw rzadko bywa projektem jednorazowym. Z czasem pojawiają się nowe typy treści, dodatkowe sekcje strony, integracje z modułami. Aby ułatwić rozwój, od początku warto:

• prowadzić dokumentację struktury motywu i użytych konwencji,
• dzielić szablony Twig na mniejsze komponenty (include, embed),
• utrzymywać spójny system zmiennych, np. w Sass lub w konfigurowalnym pliku CSS,
• stosować system kontroli wersji (Git) i procesy przeglądu zmian.

Dobrze zaplanowany motyw Drupal staje się solidnym fundamentem dla całego serwisu, a nie przeszkodą przy każdej zmianie wymagań. Jasno wydzielone komponenty, świadome korzystanie z hooków i preprocesorów, modularne biblioteki CSS i JS oraz przemyślane wykorzystanie Twig sprawiają, że rozwój motywu jest przewidywalny, a koszty utrzymania pozostają pod kontrolą nawet w rozbudowanych projektach.