Motywy potomne w PrestaShop: dlaczego nigdy nie należy edytować motywu nadrzędnego

Ostatnia aktualizacja: czerwiec 2026, obejmuje motywy potomne zarówno dla Hummingbird (PrestaShop 9, proces budowania SCSS), jak i Classic (PrestaShop 8). Mechanizm nadpisywania jest identyczny dla obu motywów nadrzędnych.

Oto moment, który potrafi zmienić zadowolonego właściciela sklepu PrestaShop we sfrustrowanego: kupujesz motyw premium, chcesz zmienić trzy drobne rzeczy, inny krój nagłówków, kolor marki na przyciskach, korektę układu strony produktu, więc otwierasz /themes/your-theme/templates/catalog/product.tpl i edytujesz plik. Wygląda idealnie. Potem, sześć tygodni później, autor motywu wydaje wersję 2.1 z poprawką bezpieczeństwa i szybszą galerią produktu. Klikasz aktualizację. Wszystkie wprowadzone zmiany znikają: nadpisane, nie do odzyskania, chyba że masz kopię zapasową, z którą możesz porównać pliki.

To najczęstsza samodzielnie spowodowana szkoda przy dostosowywaniu PrestaShop, a od lat istnieje na nią właściwe rozwiązanie: motyw potomny. Ten poradnik dotyczy właśnie tego. Czym naprawdę jest motyw potomny PrestaShop na poziomie systemu plików, jak kolejność rozwiązywania nadpisań decyduje, który plik zostanie użyty, jak zbudować motyw potomny dla Hummingbird albo Classic oraz gdzie dokładnie przebiega granica między "użyj motywu potomnego" a "to wymaga modułu". Jeśli w rzeczywistości chcesz tylko dodać fragment CSS albo skrypt śledzący bez forkowania czegokolwiek, to jest węższe zadanie z osobną odpowiedzią, zobacz własny CSS i JavaScript bez psucia aktualizacji, a niżej wskażemy właściwy moment, kiedy warto do niego wrócić.

Czym naprawdę jest motyw potomny (na poziomie plików)

Motyw potomny to osobny katalog motywu, który deklaruje motyw parent w pliku config/theme.yml i dziedziczy po nim wszystko, każdy szablon, każdy zasób, każdą wartość konfiguracji, jednocześnie pozwalając nadpisywać pojedyncze pliki. Nie jest kopią motywu nadrzędnego. To cienka warstwa położona na nim. Każdy plik, którego nie umieścisz w motywie potomnym, jest serwowany z motywu nadrzędnego; każdy plik, który tam umieścisz, ma pierwszeństwo.

Cały sens tej techniki zawiera się w pytaniu "I co z tego?": ponieważ motyw potomny żyje we własnym katalogu, aktualizacja motywu nadrzędnego dotyka motywu nadrzędnego i zostawia Twoją pracę w spokoju. Motyw nadrzędny dostaje wersję v2.1, Twoje nadpisania nadal działają na v2.1, a wieczór spędzasz na czymś innym niż odtwarzanie modyfikacji z pamięci. Dostajesz poprawki błędów i usprawnienia wydajności od autora motywu oraz własny branding, zamiast wybierać między jednym a drugim.

Kolejność rozwiązywania nadpisań. Mechanika, dzięki której to działa

Aby zaufać motywom potomnym, musisz dokładnie wiedzieć, jak PrestaShop decyduje, który szablon wyrenderować. Gdy kontroler prosi o szablon, warstwa renderowania motywu sprawdza lokalizacje w stałej kolejności i zatrzymuje się na pierwszym trafieniu:

Właśnie dlatego zasada "skopiuj jeden potrzebny plik i edytuj kopię" działa bez psucia reszty: PrestaShop rozwiązuje każdy szablon niezależnie. Nadpisujesz product.tpl, a reszta sklepu nadal renderuje się z motywu nadrzędnego. Nie ma tu przełącznika wszystko albo nic, motyw potomny przechwytuje tylko dokładne ścieżki, które w nim utworzysz, a dla całej reszty przechodzi do motywu nadrzędnego. To przechodzenie dalej jest zaletą, nie ograniczeniem: im mniej plików przechwytujesz, tym więcej aktualizacji motywu nadrzędnego trafia prosto do Twojego sklepu.

config/theme.yml, plik, który deklaruje relację

Całe dziedziczenie opiera się na jednym pliku w katalogu config/ motywu potomnego: config/theme.yml. Klucz parent mówi PrestaShop: "serwuj wszystko z tego motywu, chyba że to nadpiszę". Minimalny motyw potomny dla Hummingbird wygląda tak:

parent: hummingbird
name: my-store-child
display_name: My Store Child
version: 1.0.0
assets:
  use_parent_assets: true

Wartość parent musi odpowiadać nazwie katalogu motywu nadrzędnego (a sam motyw nadrzędny musi faktycznie być zainstalowany. Motyw potomny nie może dziedziczyć po motywie, którego nie ma na serwerze). Wartość name musi być unikalna i musi odpowiadać nazwie katalogu Twojego motywu potomnego. Pomyłka w którymkolwiek z tych miejsc sprawi, że PrestaShop albo po cichu wróci do motywu nadrzędnego, albo odmówi włączenia motywu, oba przypadki łatwiej zdiagnozować, gdy wiesz, że prawie zawsze chodzi o niezgodność nazw w tym pliku.

Budowanie motywu potomnego krok po kroku

Motyw potomny niczego nie zmienia, dopóki nie zostanie wybrany jako aktywny motyw.

• Utwórz katalog, na przykład /themes/my-store-child/, z katalogiem config/ w środku. Nie kopiuj do niego plików motywu nadrzędnego. Minimalny motyw potomny może być bardzo mały, ale musi zawierać poprawny plik config/theme.yml deklarujący parent, name, display_name i version, gdy ten plik jest na miejscu, motyw renderuje się identycznie jak nadrzędny.
• Dodaj config/theme.yml w lokalizacji /themes/my-store-child/config/theme.yml z pokazaną wyżej referencją do motywu nadrzędnego.
• Kopiuj tylko te pliki, które naprawdę zmieniasz, zachowując ścieżkę względną. Aby dostosować stronę produktu, skopiuj /themes/hummingbird/templates/catalog/product.tpl do /themes/my-store-child/templates/catalog/product.tpl i edytuj wyłącznie kopię w motywie potomnym.
• Aktywuj go w panelu administracyjnym w sekcji Wygląd → Motyw & logo. Samo utworzenie katalogu nic nie zmienia, dopóki nie wybierzesz i nie użyjesz tutaj motywu potomnego, sklep nadal serwuje motyw nadrzędny. To najczęstsze pytanie wsparcia w stylu "dlaczego moja zmiana się nie pokazuje", a odpowiedź prawie zawsze brzmi: motyw potomny nigdy nie został aktywowany.

Układ katalogów motywu potomnego dokładnie odzwierciedla motyw nadrzędny. Zadaniem szablonu jest znajdować się w tej samej ścieżce względnej w motywie potomnym, w której znajduje się w motywie nadrzędnym. To dopasowanie ścieżki pozwala mechanizmowi rozwiązywania je sparować.

Co należy do motywu potomnego, a co nie

Szablony (.tpl), tak, to właściwe narzędzie

Zmiany strukturalne w znacznikach, przestawianie bloków na stronie produktu, dodanie własnej sekcji informacyjnej, zmiana sposobu renderowania nagłówka. Są dokładnie tym, do czego służą nadpisania szablonów. Skopiuj szablon z motywu nadrzędnego do odpowiadającej mu ścieżki w motywie potomnym i edytuj go tam. Nadpisywanie frontowego szablonu modułu (pliku pod ścieżką /themes/[theme]/modules/[module]/views/templates/front/[template].tpl) także jest udokumentowaną techniką, ale pamiętaj, że konkretnie w przypadku motywów potomnych to znany słaby punkt: dokumentacja PrestaShop dla motywów potomnych nie obejmuje nadpisań szablonów modułów, a istnieją otwarte zgłoszenia o niespójnym rozwiązywaniu ich z motywu potomnego (pamięć podręczna szablonów może zaserwować kopię z motywu nadrzędnego). Jeśli musisz ostylować na nowo wyjście modułu i używasz motywu potomnego, dokładnie przetestuj to na swojej wersji albo umieść nadpisanie bezpośrednio w aktywnym motywie, zamiast polegać na przechodzeniu z motywu potomnego do nadrzędnego.

CSS i JavaScript, zwykle niewłaściwa warstwa

Jeśli zmiana jest czysto wizualna, kolory, fonty, odstępy, ukrycie elementu, nadpisywanie całego szablonu to zbyt ciężkie narzędzie, które zmusza Cię do ponownego scalania tego szablonu przy każdej aktualizacji motywu nadrzędnego. Lżejszym i bezpieczniejszym dla aktualizacji rozwiązaniem jest arkusz stylów albo skrypt ładowany po zasobach motywu nadrzędnego; nie wymaga to duplikowania żadnej logiki szablonu. To na tyle osobne zadanie, że ma własną instrukcję: własny CSS i JavaScript w PrestaShop bez psucia aktualizacji. Zasada praktyczna: sięgaj po nadpisanie szablonu tylko wtedy, gdy naprawdę musisz zmienić znaczniki; wszystko, co da się zrobić w CSS, rób w CSS.

Logika biznesowa, ani jedno, ani drugie; to zadanie dla modułu

Twarda granica: jeśli Twoja zmiana dotyczy zachowania, sposobu obliczania cen, wyboru wysyłki, tego, co dzieje się przy finalizacji zakupu, motyw potomny jest całkowicie złym miejscem. Szablony wyświetlają dane; nie mogą ich przetwarzać. Gdy tylko zaczynasz pisać prawdziwą logikę PHP w pliku .tpl, umieszczasz kod biznesowy w warstwie prezentacji, gdzie nie da się go czysto testować, ponownie używać ani aktualizować. Taka praca należy do modułu (albo klasy override), nie do motywu. Motyw decyduje, jak koszyk wygląda; moduł decyduje, jak koszyk działa.

Dlaczego "lekkość" to twarda zasada, a nie miły dodatek

Każdy plik, który nadpisujesz, przestaje otrzymywać poprawki od autora motywu nadrzędnego. Jeśli autor wyda poprawiony, bardziej dostępny product.tpl w wersji v2.1, a Ty masz własną kopię, nie dostaniesz tej poprawki, Twoja kopia pozostaje zamrożona na znacznikach z v2.0, dopóki ręcznie nie scalisz różnicy. Każde nadpisanie niesie więc stały koszt utrzymania, a rachunek przychodzi przy każdej aktualizacji motywu nadrzędnego.

Dyscyplina, która utrzymuje ten koszt nisko: nadpisuj najmniejszą jednostkę, która załatwia zadanie. Musisz dodać jedną klasę do jednego elementu? Nadpisz ten jeden szablon, nie jego układ nadrzędny, nie cały katalog catalog. Potrzebujesz zmiany koloru? To CSS, nie szablon. Motyw potomny z czterema plikami nadpisań to pięciominutowa aktualizacja; motyw potomny z czterdziestoma plikami to projekt za każdym razem, gdy motyw nadrzędny się zmieni.

Jak przetrwać aktualizację motywu nadrzędnego

Gdy autor motywu nadrzędnego wydaje nową wersję, rutyna jest krótka, bo architektura wykonuje większość pracy:

• Zaktualizuj motyw nadrzędny. Motyw potomny jest osobnym katalogiem, więc nic, co zostało przez Ciebie napisane, nie zostanie nadpisane.
• Porównaj swoje nadpisania z nowymi wersjami z motywu nadrzędnego. Dla każdego skopiowanego pliku porównaj zamrożoną kopię z motywu potomnego z nową kopią z motywu nadrzędnego, używając dowolnego narzędzia diff. To jedyne miejsce, w którym płacisz koszt utrzymania, i zawsze jest on tak duży, jak liczba Twoich nadpisań.
• Scal wszystko, co warto zachować, poprawkę błędu, nowe pole, ulepszenie dostępności dodane przez autora do szablonu, który nadpisujesz, do kopii w motywie potomnym.
• Przetestuj dotknięte strony, zwłaszcza te, których szablony nadpisujesz, przed i po zmianie.

Pliki, których nie nadpisujesz, nie wymagają żadnej z tych czynności, aktualizują się automatycznie w chwili aktualizacji motywu nadrzędnego. Ta asymetria jest całym zwrotem z tej techniki: porównujesz i scalasz tylko proporcjonalnie do tego, co zostało dostosowane, a całą resztę dostajesz za darmo.

Hummingbird kontra Classic, który motyw nadrzędny w 2026 roku

Hummingbird to nowoczesny oficjalny kierunek motywów PrestaShop dla ery PS 9, podczas gdy Classic pozostaje popularny i dostępny, szczególnie w PS 8 oraz starszych sklepach. Mechanizm motywów potomnych jest identyczny niezależnie od motywu nadrzędnego, ten sam config/theme.yml, ta sama kolejność rozwiązywania, ale wybór motywu nadrzędnego zmienia sposób przygotowywania zasobów:

Jeśli aktualizujesz sklep z PrestaShop 8 z motywem potomnym opartym na Classic, nie musisz migrować do Hummingbird pierwszego dnia, Classic pozostaje dostępny jako osobny pakiet do pobrania, ale nową budowę warto zacząć od Hummingbird. Ponieważ proces budowania arkuszy stylów Hummingbird opiera się na SCSS, sposób kompilowania własnego CSS różni się od Classic; wybór motywu nadrzędnego wpływa więc głównie na sposób pracy ze stylami, a nie na logikę nadpisywania. Wybór właściwego motywu bazowego od początku to decyzja, którą warto podjąć świadomie, omawiamy ją w poradniku jak wybrać właściwy motyw PrestaShop dla swojego biznesu.

Typowe sposoby, w jakie nadal robi się to źle

• Motyw potomny nigdy nie został aktywowany. Katalog i config/theme.yml istnieją, ale sklep nadal serwuje motyw nadrzędny, bo nikt nie wybrał motywu potomnego w sekcji Wygląd → Motyw & logo. To zawsze pierwsza rzecz do sprawdzenia.
• Niezgodność nazwy w config/theme.yml. Wartość name nie odpowiada katalogowi albo parent wskazuje motyw, który nie jest zainstalowany. Motyw potomny po cichu wraca do nadrzędnego albo nie daje się włączyć.
• Rozrost nadpisań. Czterdzieści skopiowanych szablonów, bo "łatwiej było skopiować cały folder". Każdy z nich oznacza teraz ręczne scalanie przy każdej aktualizacji motywu nadrzędnego. Projektuj to tak, żeby było lekko.
• Brak kontroli wersji. Motyw potomny to kod niestandardowy. Powinien być w Git z prawdziwymi komunikatami commitów, aby złe scalanie po aktualizacji motywu nadrzędnego dało się cofnąć jednym revertem, zamiast zgadywać.
• "Tylko ten jeden raz" w motywie nadrzędnym. Nie ma czegoś takiego jak jeden raz. Jedna bezpośrednia edycja motywu nadrzędnego staje się dwudziestoma, a potem aktualizacją, której nie możesz zastosować, jest właśnie ta najważniejsza: bezpieczeństwa. Każda zmiana, choćby najmniejsza, trafia do motywu potomnego.

Najważniejszy wniosek

Postawienie motywu potomnego zajmuje około dziesięciu minut, jeden katalog, jeden config/theme.yml, poprawnie wpisana nazwa motywu nadrzędnego, aktywacja w panelu administracyjnym, i zmienia każdą przyszłą aktualizację motywu nadrzędnego z kasowania modyfikacji w nieistotne zdarzenie. To nie jest zaawansowana technika ani opcjonalna dobra praktyka; w PrestaShop to po prostu właściwy sposób dostosowywania każdego motywu, którego nie napisałeś samodzielnie. Jeśli teraz edytujesz bezpośrednio pliki motywu nadrzędnego, właściwy krok jest taki sam niezależnie od tego, jak drobne wydają się zmiany: utwórz dziś motyw potomny i przenieś do niego swoje nadpisania, zanim następna aktualizacja je usunie. Potem utrzymuj go lekko, przenoś czyste stylowanie do CSS i JS, które przetrwają aktualizacje, zachowanie do modułów, a nadpisania szablonów zostaw dla zmian w znacznikach, które naprawdę ich wymagają.

Najczęściej zadawane pytania

Czy muszę skopiować cały motyw nadrzędny do motywu potomnego?

Nie, i nie należy tego robić. Motyw potomny domyślnie dziedziczy wszystko z motywu nadrzędnego; kopiujesz do niego wyłącznie konkretne pliki, które zmieniasz, zachowując ich ścieżkę względną. Minimalny motyw potomny może być tylko katalogiem z poprawnym plikiem config/theme.yml i będzie renderował się identycznie jak motyw nadrzędny. Im mniej plików skopiujesz, tym więcej aktualizacji motywu nadrzędnego trafi prosto do Twojego sklepu.

Mój motyw potomny wygląda identycznie jak nadrzędny i nie widać żadnej zmiany. Dlaczego?

Prawie zawsze chodzi o jedną z dwóch rzeczy: motyw potomny nigdy nie został aktywowany w sekcji Wygląd → Motyw & logo (samo utworzenie katalogu nic nie zmienia) albo występuje niezgodność nazw w config/theme.yml, wartość name nie odpowiada katalogowi motywu potomnego albo parent wskazuje motyw, który nie jest zainstalowany. Najpierw sprawdź aktywację, potem YAML.

Czy mogę umieścić własny CSS i JavaScript w motywie potomnym?

Możesz, ale przy czysto wizualnych zmianach, kolorach, fontach, odstępach, ukryciu elementu, nadpisywanie całego szablonu jest zbyt ciężkie i wymusza ponowne scalanie przy każdej aktualizacji motywu nadrzędnego. Arkusz stylów albo skrypt ładowany po zasobach motywu nadrzędnego jest lżejszy i nie duplikuje żadnej logiki szablonu. Zarezerwuj nadpisania szablonów dla realnych zmian w znacznikach; wszystko, co CSS potrafi zrobić, rób w CSS. Zobacz własny CSS i JavaScript bez psucia aktualizacji.

Czy moje nadpisania przetrwają aktualizację motywu nadrzędnego?

Tak, motyw potomny żyje we własnym katalogu, więc aktualizacja motywu nadrzędnego nigdy go nie dotyka. Jedynym zadaniem, które pozostaje po Twojej stronie, jest porównanie każdego nadpisanego pliku z nową wersją z motywu nadrzędnego i scalenie każdej wartościowej zmiany (poprawki błędu, ulepszenia dostępności). Ta praca jest proporcjonalna wyłącznie do liczby skopiowanych plików, i właśnie dlatego opłaca się trzymać liczbę nadpisań nisko.

Czy motyw potomny może nadpisać frontowy szablon modułu?

To udokumentowana technika, ale konkretnie w przypadku motywów potomnych jest to znany słaby punkt, istnieją otwarte zgłoszenia o niespójnym rozwiązywaniu nadpisań szablonów modułów z motywu potomnego, ponieważ pamięć podręczna szablonów może zaserwować kopię z motywu nadrzędnego. Jeśli musisz ostylować na nowo wyjście modułu i używasz motywu potomnego, dokładnie przetestuj to na swojej konkretnej wersji albo umieść nadpisanie bezpośrednio w aktywnym motywie, zamiast polegać na przechodzeniu z motywu potomnego do nadrzędnego.

Zmiana, której chcę, dotyczy zachowania, a nie wyglądu. Czy powinna trafić do motywu potomnego?

Nie. Jeśli zmieniasz sposób obliczania cen, wyboru wysyłki albo to, co dzieje się przy finalizacji zakupu, to jest logika biznesowa i należy do modułu albo klasy override, nigdy do pliku .tpl. Szablony wyświetlają dane; nie mogą ich przetwarzać. Motyw decyduje, jak wygląda koszyk; moduł decyduje, jak koszyk działa.

Czy motyw potomny powinien być w kontroli wersji?

Tak, motyw potomny to kod niestandardowy i powinien być w Git z prawdziwymi komunikatami commitów. Korzyść widać po aktualizacji motywu nadrzędnego: jeśli scalanie pójdzie źle, dzieli Cię jeden revert od znanego, działającego stanu, zamiast zgadywania, co zostało zmienione. To także banalnie ułatwia sprawdzenie, które pliki motywu nadrzędnego zostały rozdzielone do własnych kopii i dlatego wymagają porównania przy następnej aktualizacji.

Czy Hummingbird i Classic wymagają różnych konfiguracji motywu potomnego?

Mechanizm nadpisywania jest identyczny, ten sam config/theme.yml, ta sama kolejność rozwiązywania, więc wybór motywu nadrzędnego nie zmienia logiki. Zmienia natomiast sposób pracy ze stylami: proces budowania arkuszy stylów Hummingbird opiera się na SCSS, a Classic jest prostszy, więc sposób kompilowania własnego CSS jest inny. Wybierz Hummingbird dla nowych projektów, a Classic wtedy, gdy utrzymujesz istniejący motyw potomny oparty na Classic.

Powiązane poradniki

• Własny CSS i JavaScript w PrestaShop bez psucia aktualizacji
• Jak wybrać właściwy motyw PrestaShop dla swojego biznesu
• Bloki HTML: dodawanie własnej treści w dowolnym miejscu sklepu PrestaShop