Dogłębna analiza katalogu /themes/ w PrestaShop: jak naprawdę działają szablony, zasoby i motywy potomne

Ostatni przegląd: czerwiec 2026, zweryfikowano z PrestaShop 9.0 i domyślnym motywem Hummingbird 2.0 (Bootstrap 5.3, SCSS, nazwy klas w stylu BEM) oraz motywem Classic w PrestaShop 1.7/8.

Przeczytaj przewodnik po motywach potomnych: Skorzystaj z pełnego przewodnika, aby zaplanować łatwy w utrzymaniu motyw potomny dla Classic, Hummingbird lub Warehouse, obejmujący custom.css, nadpisania szablonów i konfigurację SCSS. Otwórz przewodnik po motywach potomnych.

To część 2 serii o architekturze PrestaShop. Część 1 omawia pełny przegląd struktury katalogów.

Za co odpowiada katalog /themes/

Każdy piksel części sklepu widocznej dla klientów przechodzi przez katalog /themes/. Gdy klient odwiedza stronę produktu, PrestaShop nie renderuje HTML bezpośrednio z PHP -- ładuje szablon Smarty z aktywnego motywu, uzupełnia go danymi z kontrolerów i hooków, kompiluje go i wysyła wynik. Motyw kontroluje strukturę HTML, style CSS, zachowanie JavaScriptu, a nawet to, które hooki są wyświetlane w konkretnych miejscach.

Zrozumienie działania tego katalogu oznacza zrozumienie, jak PrestaShop buduje każdą stronę widoczną dla Twoich klientów.

Struktura katalogów motywu

themes/
  classic/                          <-- PS 1.7/8 default
  hummingbird/                      <-- PS 9 default
  my-child-theme/                   <-- your customizations

  [active-theme]/
    config/
      theme.yml                     <-- theme identity, assets, layouts
    templates/
      catalog/
        product.tpl                 <-- product page
        listing/
          category.tpl              <-- category listing
          product-list.tpl          <-- product grid/list
      checkout/
        cart.tpl                    <-- shopping cart
        checkout.tpl                <-- checkout flow
        order-confirmation.tpl      <-- thank-you page
      cms/
        page.tpl                    <-- CMS content pages
      customer/
        my-account.tpl              <-- customer dashboard
        addresses.tpl               <-- address management
        history.tpl                 <-- order history
      errors/
        404.tpl                     <-- page not found
        maintenance.tpl             <-- maintenance mode
      _partials/
        head.tpl                    <-- <head> section, meta, CSS
        header.tpl                  <-- site header, navigation
        footer.tpl                  <-- site footer
        notifications.tpl           <-- success/error messages
        breadcrumb.tpl              <-- breadcrumb navigation
        pagination.tpl              <-- list pagination
      layouts/
        layout-full-width.tpl       <-- full-width page layout
        layout-left-column.tpl      <-- with left sidebar
        layout-right-column.tpl     <-- with right sidebar
        layout-both-columns.tpl     <-- both sidebars
    assets/
      css/
        theme.css                   <-- main compiled stylesheet
        custom.css                  <-- user overrides (if theme supports it)
      js/
        theme.js                    <-- main compiled JavaScript
        custom.js                   <-- user scripts
      img/
        logo.png                    <-- store logo
        favicon.ico                 <-- browser tab icon
    modules/
      ps_featuredproducts/
        views/templates/hook/
          ps_featuredproducts.tpl    <-- theme override of module template
    translations/
      en-US/
        Shop/Theme/Global.xlf       <-- theme-specific translations
    preview.png                     <-- 200x200 theme preview

Jak PrestaShop rozwiązuje szablony

Aktywny motyw decyduje, które drzewo szablonów PrestaShop sprawdza jako pierwsze.

Gdy kontroler musi wyrenderować stronę, PrestaShop szuka szablonu w określonej kolejności. Zrozumienie tej kolejności jest krytyczne -- to ona decyduje, który plik faktycznie renderuje stronę.

Kolejność rozwiązywania szablonów (od najwyższego do najniższego priorytetu):

• Motyw potomny -- themes/my-child/templates/catalog/product.tpl
• Motyw nadrzędny -- themes/classic/templates/catalog/product.tpl

Rozwiązywanie szablonów modułów (dla hooków):

• Nadpisanie modułu w motywie potomnym -- themes/my-child/modules/ps_featuredproducts/views/templates/hook/ps_featuredproducts.tpl
• Nadpisanie modułu w motywie nadrzędnym -- themes/classic/modules/ps_featuredproducts/views/templates/hook/ps_featuredproducts.tpl
• Własny szablon modułu -- modules/ps_featuredproducts/views/templates/hook/ps_featuredproducts.tpl

Ten trzystopniowy mechanizm fallbacku umożliwia tworzenie motywów potomnych: dodajesz tylko pliki, które chcesz zmienić, a cała reszta przechodzi do motywu nadrzędnego. To również dzięki niemu możliwe są nadpisania modułów na poziomie motywu: motyw może całkowicie przeprojektować sposób renderowania modułu bez dotykania jego własnych plików.

Praktyczna konsekwencja, którą musisz rozumieć: Gdy motyw nadpisuje szablon modułu, takie nadpisanie ma bezwzględny priorytet. Jeśli moduł otrzyma aktualizację naprawiającą problem bezpieczeństwa w swoim szablonie, nadpisanie w Twoim motywie nadal będzie serwować starą wersję. Przy aktualizacjach modułów trzeba ręcznie porównywać i aktualizować nadpisania w motywie. To ukryty koszt utrzymania nadpisań szablonów, który większość dokumentacji pomija.

Jak renderuje się strona: od żądania do HTML

Oto dokładna sekwencja zdarzeń, gdy klient odwiedza /en/product/linear-drain-800mm:

• Apache/Nginx odbiera żądanie i przepisuje je przez .htaccess do index.php
• Bootstrap PrestaShop ładuje config/config.inc.php i inicjalizuje Dispatcher
• Dispatcher analizuje adres URL i identyfikuje kontroler: ProductController
• ProductController::init() ładuje dane produktu z bazy danych
• ProductController::initContent() przypisuje zmienne Smarty ($product, $combinations itd.)
• Wykonanie hooków -- kontroler wywołuje Hook::exec('displayProductAdditionalInfo') oraz inne hooki. Każdy zarejestrowany moduł uruchamia swoją metodę hooka, która zwykle przypisuje własne zmienne Smarty i zwraca wyrenderowany HTML.
• Wybór szablonu -- kontroler wywołuje $this->setTemplate('catalog/product'). PrestaShop rozwiązuje to do rzeczywistej ścieżki pliku zgodnie z opisaną wyżej kolejnością.
• Opakowanie w layout -- szablon produktu jest renderowany wewnątrz szablonu layoutu (layouts/layout-full-width.tpl). Layout dołącza _partials/head.tpl, _partials/header.tpl, treść strony oraz _partials/footer.tpl.
• Kompilacja Smarty -- Smarty kompiluje pliki .tpl do PHP i zapisuje wynik w var/cache/prod/smarty/compile/. Kolejne żądania pomijają kompilację i używają bezpośrednio PHP z cache.
• Wyjście HTML -- skompilowany szablon wykonuje się, generuje HTML, a PrestaShop wysyła go do przeglądarki z odwołaniami do CSS/JS.

Cały łańcuch trwa zwykle 200-500 ms na dobrze skonfigurowanym serwerze. Z tego kompilacja szablonów zajmuje 0 ms dla żądań obsługiwanych z cache (ponownie używany jest skompilowany PHP) oraz 50-100 ms przy pierwszym żądaniu po wyczyszczeniu cache.

theme.yml: plik konfiguracyjny motywu

Minimalna konfiguracja motywu potomnego jest na tyle krótka, że da się ją ogarnąć jednym spojrzeniem:

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

Plik config/theme.yml definiuje wszystko, co dotyczy motywu: jego tożsamość, relację z motywem nadrzędnym, rejestrację zasobów, przypisania layoutów i konfigurację hooków.

parent: classic                     <-- child theme inherits from this
name: my-child-theme                <-- directory name (must match)
display_name: My Custom Theme       <-- human-readable name
version: 1.0.0
author:
  name: "Your Name"
  email: "you@example.com"

meta:
  compatibility:
    from: 1.7.0.0
    to: ~                           <-- no upper limit

assets:
  use_parent_assets: true           <-- inherit CSS/JS from parent
  css:
    all:
      - id: custom-styles
        path: assets/css/custom.css
        media: all
        priority: 200               <-- higher = loaded later
  js:
    all:
      - id: custom-scripts
        path: assets/js/custom.js
        priority: 200

theme_settings:
  default_layout: layout-full-width
  layouts:
    category: layout-left-column
    product: layout-full-width
    checkout: layout-full-width

Kluczowe pola:

• parent -- ustanawia łańcuch dziedziczenia. Bez niego PrestaShop traktuje motyw jako samodzielny i nie wraca do żadnych szablonów nadrzędnych.
• use_parent_assets: true -- ładuje CSS i JS motywu nadrzędnego przed Twoimi zasobami. Ustaw false tylko wtedy, gdy chcesz całkowicie zastąpić style motywu nadrzędnego (rzadko, a wtedy musisz dostarczyć wszystko samodzielnie).
• priority przy zasobach -- kontroluje kolejność ładowania. Zasoby motywu nadrzędnego zwykle mają priorytet 100. Ustaw zasoby motywu potomnego na 200+, aby ładowały się jako ostatnie i mogły nadpisywać style nadrzędne.
• layouts -- mapuje typy stron na szablony layoutów. Dzięki temu na stronach kategorii możesz mieć pasek boczny, a na stronach produktów układ pełnej szerokości.

Pipeline zasobów: jak CSS i JS trafiają do przeglądarki

System zasobów PrestaShop ma kilka warstw, a ich zrozumienie zapobiega najczęstszym problemom typu "moje zmiany w CSS się nie wyświetlają".

Źródła rejestracji zasobów (w kolejności ładowania):

• Zasoby z theme.yml -- rejestrowane w pliku konfiguracyjnym motywu
• Zasoby modułów -- rejestrowane przez $this->context->controller->registerStylesheet() lub registerJavascript() w metodach hooków modułu
• Zasoby właściwe dla kontrolera -- rejestrowane w metodzie setMedia() kontrolera

Warstwa CCC (łączenie, kompresja, cache):

Gdy CCC jest włączone (Panel administracyjny > Parametry zaawansowane > Wydajność), PrestaShop:

• Łączy wszystkie pliki CSS w jeden (albo kilka) scalonych plików
• Minifikuje scalony CSS
• Nadaje plikowi wynikowemu nazwę z hashem treści: themes/classic/assets/cache/combined-abc123.css
• Robi to samo dla JavaScriptu

To oznacza, że po edycji pliku CSS musisz albo zwiększyć wersję cache (PS_CCCCSS_VERSION w ps_configuration), albo usunąć scalone pliki z themes/*/assets/cache/. W przeciwnym razie przeglądarka nadal będzie ładować stary scalony plik, ponieważ nazwa pliku się nie zmieniła.

To najczęstsza przyczyna problemu "zmieniłem CSS, ale nic się nie stało" w PrestaShop. To nie błąd -- to system cache działający zgodnie z projektem. Po zmianach w SCSS należy najpierw ponownie skompilować CSS, następnie wyczyścić cache CCC, jeśli jest włączone, i wymusić odświeżenie przeglądarki z pominięciem pamięci podręcznej.

Silnik szablonów Smarty: co muszą wiedzieć twórcy modułów

PrestaShop używa Smarty 3/4 do szablonów części sklepu widocznej dla klientów. Kluczowe pojęcia:

Przypisywanie zmiennych: Kontrolery i moduły przypisują dane do Smarty, a szablony je renderują.

// In PHP (controller or module hook):
$this->context->smarty->assign('my_data', $someArray);

// In .tpl template:
{$my_data.name}
{$my_data.price|number_format:2}

System bloków: Szablony definiują nazwane bloki, które szablony potomne mogą nadpisywać.

// Parent template (classic/templates/catalog/product.tpl):
{block name='product_description'}
  <div class="product-description">{$product.description nofilter}</div>
{/block}

// Child template (my-child/templates/catalog/product.tpl):
{extends file='parent:catalog/product.tpl'}
{block name='product_description'}
  <div class="custom-description">
    {$product.description_short nofilter}
    <hr>
    {$product.description nofilter}
  </div>
{/block}

Prefiks parent: jest obowiązkowy w {extends}. Bez niego Smarty znajduje własny plik motywu potomnego i wpada w nieskończoną pętlę, która kończy się awarią przez timeout. To najczęstszy błąd w motywach potomnych.

Modyfikator nofilter: Domyślnie Smarty automatycznie escapuje zmienne, aby zapobiegać XSS. Dla zmiennych zawierających HTML (na przykład opisów produktów) musisz użyć {$var nofilter}. Bez tego tagi HTML pojawią się na stronie jako zwykły tekst.

Renderowanie hooków w szablonach:

{hook h='displayProductAdditionalInfo' product=$product}
{hook h='displayFooter'}
{widget name='ps_emailsubscription' hook='displayFooter'}

Tag {hook} wywołuje Hook::exec(), który uruchamia każdy moduł zarejestrowany w danym hooku i łączy ich wynik. Tag {widget} wywołuje metodę widgetu konkretnego modułu niezależnie od rejestracji w hooku.

Classic vs Hummingbird: różnice architektoniczne

Warstwy CSS w Hummingbird fundamentalnie zmieniają działanie specyficzności:

@layer vendors, bs-base, bs-components, bs-custom-components,
       ps-base, ps-components, ps-pages, ps-modules, utilities;

Style w późniejszych warstwach nadpisują wcześniejsze niezależnie od specyficzności selektora. Proste .product__name { color: red; } w warstwie ps-components wygrywa z bardzo szczegółowym #content .product-container .product__name { color: blue; } w warstwie bs-components. To eliminuje wojny na !important, ale wymaga zrozumienia, do której warstwy należy Twój CSS.

Dla twórców modułów wspierających oba motywy: używaj wzorca var(--css-property, fallback-value). W Classic niestandardowe właściwości CSS nie są zdefiniowane, więc wygrywa wartość fallback. W Hummingbird właściwość niestandardowa jest zdefiniowana i to ona wygrywa. Jeden plik CSS poprawnie obsługuje oba motywy.

Podkatalog modules/: nadpisania modułów na poziomie motywu

Katalog themes/[theme]/modules/ to jedna z najpotężniejszych i jednocześnie najbardziej ryzykownych funkcji PrestaShop. Pozwala motywowi całkowicie zastąpić sposób, w jaki dowolny moduł renderuje swoje szablony.

themes/my-child/modules/
  ps_featuredproducts/
    views/templates/hook/
      ps_featuredproducts.tpl        <-- replaces the module's own template
  ps_searchbar/
    views/templates/hook/
      ps_searchbar.tpl               <-- custom search bar rendering

Kiedy używać nadpisań modułów w motywie:

• Struktura HTML modułu nie pasuje do Twojego projektu
• Musisz dodać lub usunąć elementy z wyniku modułu
• Chcesz zmienić logikę Smarty (pokazywanie/ukrywanie na podstawie warunków)

Kiedy NIE używać nadpisań modułów w motywie:

• Chcesz zmienić tylko CSS -- użyj zamiast tego CSS motywu potomnego
• Moduł udostępnia opcje konfiguracji dla zmiany, której potrzebujesz -- najpierw użyj tych opcji
• Nadpisujesz moduł, który często aktualizujesz -- każda aktualizacja wymaga ponownego sprawdzenia nadpisania

Pułapka utrzymaniowa: Utrzymujemy ponad 150 modułów. Gdy moduł aktualizuje swój szablon, aby naprawić błąd albo dodać funkcję, sklepy z nadpisaniami tego szablonu w motywie nigdy nie zobaczą poprawki. Nadpisanie po cichu serwuje starą wersję. Regularnie widzimy to w pomocy technicznej -- "funkcja nie działa po aktualizacji" okazuje się przestarzałym nadpisaniem w motywie sprzed 3 wersji. Rozwiązanie jest zawsze takie samo: wykonać diff nadpisania względem aktualnego szablonu modułu, scalić zmiany albo całkowicie usunąć nadpisanie.

Wpływ architektury motywu na wydajność

Decyzje dotyczące motywu bezpośrednio wpływają na czas ładowania strony:

• Kompilacja szablonów: Pierwsze żądanie po wyczyszczeniu cache kompiluje wszystkie pliki .tpl do PHP. Motyw z 50 plikami szablonów wydłuża pierwsze ładowanie o 50-100 ms. Kolejne żądania: 0 ms (skompilowany PHP jest w cache).
• Liczba zasobów: Każdy plik CSS/JS to osobne żądanie HTTP (bez CCC). 15 oddzielnych plików CSS = 15 żądań. Z włączonym CCC: 1-2 żądania. Zawsze włączaj CCC na produkcji.
• Rozmiary obrazów: Plik theme.yml motywu definiuje typy obrazów (home_default: 250x250, large_default: 800x800). Używanie zbyt dużych typów obrazów na stronach listingu (np. large_default dla miniaturek kategorii) marnuje transfer. Używaj najmniejszego typu, który wygląda dobrze.
• Gęstość hooków: Każde wywołanie {hook} w szablonie uruchamia wszystkie zarejestrowane moduły. Nagłówek z 5 hookami, z których każdy ma 3 moduły, wykonuje 15 metod hooków modułów przy każdym ładowaniu strony. Odinstaluj moduły, których nie używasz -- nawet jeśli są wyłączone, część z nich nadal rejestruje hooki.
• Smarty nocache: Treść wewnątrz bloków {nocache}...{/nocache} nigdy nie jest cache'owana przez Smarty i jest ponownie obliczana przy każdym żądaniu. Używaj oszczędnie -- zwykle tylko dla danych zależnych od użytkownika, takich jak liczba produktów w koszyku albo status logowania.

Typowe problemy z /themes/ i ich rozwiązania

Pliki w tym katalogu, które warto rozumieć

Jeśli tworzysz moduły albo dostosowujesz motywy, warto przeczytać te pliki (w motywie nadrzędnym):

• templates/_partials/head.tpl -- miejsce, w którym generowane są CSS i meta tagi. Zrozumienie tego pliku pomaga debugować brakujące arkusze stylów.
• templates/layouts/layout-full-width.tpl -- opakowanie strony. Pokazuje szkielet HTML: nagłówek, obszar treści, stopkę i pozycje hooków.
• templates/catalog/product.tpl -- najbardziej złożony szablon. Pokazuje wszystkie bloki strony produktu, pozycje hooków i dostępne zmienne danych.
• config/theme.yml -- źródło prawdy dla zasobów, layoutów i konfiguracji motywu.
• assets/css/theme.css -- czytaj (nie edytuj), aby zrozumieć nazwy klas motywu nadrzędnego i wzorce specyficzności.

Najczęściej zadawane pytania

Czy mogę po prostu edytować bezpośrednio motyw Classic albo Hummingbird zamiast budować motyw potomny?

Możesz, ale nie powinieneś. Domyślne motywy są nadpisywane podczas aktualizacji rdzenia PrestaShop, więc wszystkie zmiany wprowadzone w themes/classic/ albo themes/hummingbird/ znikną przy następnej aktualizacji. Motyw potomny (własny folder z ustawionym parent: w theme.yml) trzyma Twoje zmiany w osobnym katalogu, którego aktualizator nie dotyka, a Ty przenosisz tylko te kilka plików, które faktycznie zmieniłeś. Do jednorazowych poprawek CSS wystarczy custom.css w motywie potomnym; po pełne nadpisanie szablonu sięgaj dopiero wtedy, gdy musisz zmienić strukturę HTML.

Dlaczego moje zmiany w SCSS albo CSS nie pojawiają się, nawet po zapisaniu pliku?

Między Twoją edycją a przeglądarką stoją dwa cache. Po pierwsze CSS motywu zwykle jest kompilowany z SCSS podczas budowania, więc ręczna edycja skompilowanego theme.css zostanie nadpisana przy następnym buildzie -- edytuj źródła SCSS i przebuduj motyw albo użyj custom.css. Po drugie, jeśli CCC jest włączone (Parametry zaawansowane > Wydajność), PrestaShop serwuje hashowany, scalony plik z themes/*/assets/cache/ i nie uwzględni zmiany, dopóki ten cache nie zostanie przebudowany. Wyczyść scalony cache (albo podbij PS_CCCCSS_VERSION), a następnie wykonaj twarde odświeżenie przeglądarki.

Czy Hummingbird jest zamiennikiem Classic typu drop-in przy przejściu na PrestaShop 9?

Nie. Hummingbird jest zbudowany na Bootstrap 5.3, z kolejnością CSS opartą na @layer i nazwami klas w stylu BEM, podczas gdy Classic używa Bootstrap 4.6 i płaskiej specyficzności. Nazwy klas, narzędzia siatki i model specyficzności są inne, więc motyw potomny albo nadpisanie szablonu napisane dla Classic nie wyrenderuje się poprawnie w Hummingbird bez przeróbek. Zaplanuj odbudowanie swoich modyfikacji pod Hummingbird zamiast ich prostego kopiowania. Wzorzec var(--property, fallback) to ten jeden fragment CSS, który może obsłużyć oba motywy z jednego pliku.

Gdzie dokładnie PrestaShop przechowuje skompilowane szablony i czy można je bezpiecznie usunąć?

Skompilowane szablony Smarty znajdują się w var/cache/prod/smarty/compile/ (oraz w odpowiedniku dla środowiska deweloperskiego pod var/cache/dev/). Usunięcie zawartości jest bezpieczne -- PrestaShop skompiluje ją ponownie przy następnym żądaniu, co jednorazowo kosztuje 50-100 ms. W PrestaShop 9 nie usuwaj brutalnie całego katalogu var/cache/prod/ w działającym sklepie, ponieważ kontener Symfony panelu administracyjnego znajduje się pod var/cache/prod/admin/, a jego usunięcie może zepsuć panel administracyjny do czasu odbudowy. Wyczyść konkretnie folder kompilacji Smarty albo użyj przycisku czyszczenia cache w panelu administracyjnym.

Szablon modułu nadpisany w moim motywie przestał uwzględniać najnowszą poprawkę modułu. Co się stało?

To priorytet nadpisania w motywie działający zgodnie z projektem. Kopia szablonu w themes/your-child/modules/<module>/views/templates/hook/ ma bezwzględny priorytet nad własnym plikiem modułu, więc gdy moduł dostarcza poprawkę w swoim szablonie, Twoje nadpisanie nadal serwuje starą wersję. Po każdej aktualizacji modułu wykonaj diff swojego nadpisania względem aktualnego szablonu modułu, scal istotne zmiany albo usuń nadpisanie, jeśli nie jest już potrzebne.

Potrzebujesz gotowego szkieletu struktury nadrzędny/potomny? Nasz generator motywów potomnych tworzy poprawnie połączony motyw potomny (z właściwym parent:, rejestracją zasobów i układem folderów), dzięki czemu omijasz najczęstsze błędy konfiguracyjne. Aby utrzymać CCC i scalone zasoby pod kontrolą na produkcji, zobacz Performance Revolution, a mapę katalogów całej platformy zacznij od przewodnika po strukturze katalogów PrestaShop.

Praktyczny przewodnik po tworzeniu motywów potomnych i dostosowywaniu szablonów znajdziesz w naszej bazie wiedzy: przewodnik po motywach potomnych.

Następny tekst w serii o architekturze: dogłębna analiza /modules/ -- pełny cykl życia modułu, od install() po hookDisplay*(), w tym skrypty aktualizacji, autoloading oraz wzorce, na których opiera się ponad 150 modułów produkcyjnych.