Jak dostosować motyw i nie stracić zmian przy aktualizacji

Dlaczego na każdym sklepie, którym się zajmujemy, uruchamiamy motyw potomny

Sam serwis mypresta.rocks działa na motywie mypresta-rocks, motywie potomnym Hummingbird, który utrzymujemy samodzielnie. Każdy sklep klienta, który migrowaliśmy od 2013 roku, kończy tak samo: motyw potomny tego, co kupił sprzedawca, z naszymi nadpisaniami na wierzchu. Powód jest prosty. Autorzy motywów wydają aktualizacje. Sprzedawcy kupują motywy „premium”, a potem ktoś edytuje pliki .tpl motywu nadrzędnego bezpośrednio. Pół roku później motyw się aktualizuje i każda poprawka znika.

Motyw potomny oddziela dostosowania szablonów od aktualizacji motywu nadrzędnego. Mechanizm ładowania szablonów w PrestaShop najpierw zagląda do motywu potomnego, a jeśli nie znajdzie pliku, sięga do motywu nadrzędnego. Dostarcza się wyłącznie te pliki, które rzeczywiście zostały zmienione. Cała reszta jest dziedziczona.

Pół dnia poświęcone na skonfigurowanie motywu potomnego zwróciło się, z nawiązką, na każdym sklepie, który aktualizowaliśmy od 2018 roku. Pół dnia, którego się nie poświęca, kończy się e-mailem od klienta zatytułowanym „strona znów wygląda źle”.

Motyw potomny warto stosować do zmian punktowych, kolorów, drobnych korekt układu, nadpisań szablonów, własnego CSS/JS, nadpisań szablonów modułów. Pełny, autorski motyw należy budować dopiero wtedy, gdy projekt tak bardzo różni się od czegokolwiek dostępnego standardowo, że dziedziczenie kosztowałoby więcej, niż oszczędza.

Do czegokolwiek nowego na PS 9.1+ warto wybrać Hummingbird. To jedyny motyw, który PrestaShop aktywnie rozwija. Classic nadal działa, ale każda nowa funkcja rdzenia trafia najpierw do Hummingbird.

Deklarowanie dziedziczenia za pomocą theme.yml

Motyw potomny zaczyna się od pliku config/theme.yml, a nie od pełnej kopii folderu motywu nadrzędnego. Aktywny motyw mypresta-rocks deklaruje parent: hummingbird, metadane wyświetlania oraz zgodność z PrestaShop 9 w jednym miejscu, dzięki czemu PrestaShop może załadować motyw nadrzędny i zastosować wyłącznie te pliki, które zostały świadomie nadpisane.

Projekty oparte na Classic korzystają z tej samej zasady z parent: classic. Tę konfigurację warto utrzymywać małą, wersjonowaną i przetestowaną na sklepie testowym, zanim zostanie włączona na produkcji; przewodnik po środowisku testowym PrestaShop to właściwe uzupełnienie tego wdrożenia.

Utrzymywanie porządku w folderze motywu potomnego

Motyw potomny powinien zawierać wyłącznie pliki będące własnością użytkownika: jego konfigurację, obraz podglądu, wybrane nadpisania szablonów, wybrane nadpisania szablonów modułów oraz zasoby, które się kompiluje lub rejestruje. Uporządkowany motyw potomny łatwiej skontrolować niż pełną kopię motywu nadrzędnego, ponieważ każdy plik ma jasny powód istnienia.

Pokazana tutaj struktura pochodzi z motywu działającej witryny. Nadpisania znajdują się w katalogach templates/ i modules/, podczas gdy niezmienione pliki pozostają w Hummingbird. Przewodnik po narzędziach deweloperskich pomaga utrzymać powtarzalność kompilacji zasobów oraz kroków wdrożenia.

Nadpisywanie bloków Smarty zamiast kopiowania całych szablonów

Dostosowanie strony produktu może rozszerzać szablon nadrzędny i zastępować jeden nazwany blok, na przykład product_header lub product_tabs. Dzięki temu zmiany napływające z Hummingbird pozostają dostępne, a motyw potomny odpowiada tylko za konkretną zmianę układu.

Pełne kopie szablonów nadal działają, ale zwiększają koszt utrzymania. Warto preferować {extends file='parent:...'} oraz precyzyjne nadpisania {block}, a następnie testować dostosowane widoki produktu, kategorii, checkoutu i modułów po każdej aktualizacji motywu lub PrestaShop. Przewodnik po hookach i nadpisaniach omawia tę samą zasadę własności na poziomie modułu.

Otwieranie właściwej strony ustawień Motyw i logo

Gdy pliki są już gotowe, motyw potomny należy spakować jako gotowy do importu plik ZIP. Wymagany jest plik config/theme.yml; generator mypresta.rocks tworzy plik ZIP z tym plikiem w katalogu głównym archiwum, a importer PrestaShop 9 rejestruje go poprawnie.

W PrestaShop 9 należy przejść do panelu administracyjnego > Wygląd > Motyw i logo. To właściwa strona ustawień przesyłania motywu, aktywacji, logo, układów stron oraz zaawansowanego dostosowywania motywu.

1. Należy otworzyć Wygląd > Motyw i logo.
2. Należy kliknąć Dodaj nowy motyw w nagłówku strony.
3. Należy pozostawić zainstalowany istniejący motyw nadrzędny; motyw potomny po nim dziedziczy.

Importowanie pliku ZIP motywu potomnego z komputera

Na stronie Import motywu należy użyć opcji Importuj z komputera i wybrać plik ZIP zawierający pliki motywu potomnego. PrestaShop odczytuje metadane motywu z pliku config/theme.yml i rejestruje motyw po pomyślnym przesłaniu.

1. Należy wybrać plik ZIP motywu potomnego w polu Plik ZIP.
2. Należy kliknąć Zapisz, aby go przesłać.
3. Należy wrócić do Motyw i logo, wybrać Użyj tego motywu, wyczyścić pamięć podręczną i sprawdzić wygląd sklepu.

W przypadku sklepów produkcyjnych warto najpierw przesłać i przetestować motyw na środowisku testowym, a następnie wykonać te same kroki aktywacji podczas spokojnego okna serwisowego.

Generowanie pliku ZIP motywu potomnego Hummingbird online

Child Theme Generator to publiczne narzędzie na mypresta.rocks, więc nie ma modułu generatora do zainstalowania we własnym sklepie. Należy otworzyć stronę generatora, wybrać Hummingbird (PrestaShop 9), wpisać nazwę motywu potomnego, ustawić wersję PrestaShop na 9.x i dołączyć pliki startowe, które mają się znaleźć w pliku ZIP.

W tej weryfikacji PS9 generator pobrał hummingbirdchild.zip zawierający config/theme.yml, custom.css, custom.js, opcjonalne nadpisania Smarty, obraz podglądu, plik README oraz opcjonalne pliki kompilacji SCSS.

Weryfikowanie wygenerowanego motywu potomnego po imporcie

Po przesłaniu wygenerowanego pliku ZIP przez Import motywu należy wrócić do Wygląd > Motyw i logo. Wygenerowany motyw powinien pojawić się obok motywów nadrzędnych, wraz z nazwą wyświetlaną, wersją, autorem i obrazem podglądu.

Pokazany tutaj import demonstracyjny na PS9 utworzył motyw Hummingbird Child w wersji 1.0.0 autorstwa mypresta.rocks. W tym momencie można go aktywować opcją Użyj tego motywu, wyczyścić pamięć podręczną i przejrzeć wygląd sklepu przed użyciem go na produkcji.

Jak motyw potomny naprawdę wygląda na dysku

Motyw potomny mieszka obok swojego motywu nadrzędnego wewnątrz katalogu /themes/. Ten przykład zawiera wymaganą konfigurację i opcjonalny obraz podglądu:

themes/my-child-theme/
  config/
    theme.yml             <-- wymagany: parent + name + version
  preview.png <-- opcjonalny: podgląd 200x200 wyświetlany w BO

Gdy tylko rozpoczyna się dostosowywanie, katalog odzwierciedla strukturę motywu nadrzędnego, ale zawiera wyłącznie zmienione pliki:

themes/my-child-theme/
  config/theme.yml
  assets/
    css/custom.css
    js/custom.js
  templates/
    catalog/product.tpl
    _partials/header.tpl
  modules/
    ps_featuredproducts/views/templates/hook/
      ps_featuredproducts.tpl
  translations/en-US/Shop/Theme.xlf
  preview.png

Dyscyplina, która ma znaczenie: plik należy dodawać dopiero wtedy, gdy faktycznie się go zmienia. Każdy skopiowany plik to plik, którego jest się teraz właścicielem i który trzeba utrzymywać. Pusty motyw potomny, który wszystko dziedziczy, jest zdrowszy niż taki wypchany niezmienionymi kopiami szablonów nadrzędnych.

theme.yml: jedyny plik, który jest naprawdę obowiązkowy

Krytyczny wiersz to parent: classic lub parent: hummingbird. To właśnie on uruchamia dziedziczenie. Jeśli zostanie pomylony, PrestaShop potraktuje motyw potomny jako samodzielny, bez motywu nadrzędnego, do którego można by sięgnąć, i połowa witryny wyrenderuje się jako pusta.

parent: classic
name: my-child-theme
display_name: My Child Theme
version: 1.0.0
author:
  name: "Your Name"
  email: "you@example.com"
  url: "https://yoursite.com"

meta:
  compatibility:
    from: 1.7.0.0
    to: ~

assets:
  use_parent_assets: true

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

Tworzenie motywu potomnego dla Classic

Na Classic działa większość sklepów na PS 1.7 i 8.x. Cztery kroki i można działać na żywo:

# 1. Utworzyć katalog
mkdir -p themes/my-classic-child/config

# 2. Zapisać config/theme.yml z parent: classic (por. wyżej)

# 3. Umieścić preview.png (200x200): na tym etapie wystarczy dowolny PNG

# 4. Aktywować przez Back Office > Wygląd > Motyw i logo
#    Albo przez CLI: php bin/console prestashop:theme:enable my-classic-child

Przy use_parent_assets: true i bez żadnych nadpisań witryna renderuje się identycznie jak Classic. To bezpieczny punkt wyjścia. Najpierw warto potwierdzić, że pusty motyw potomny działa, a następnie dodawać nadpisania pojedynczo.

Tworzenie motywu potomnego dla Hummingbird

Hummingbird działa inaczej. Bootstrap 5.3 z niestandardowymi właściwościami CSS, warstwy CSS (@layer) do kontroli kaskady, TypeScript kompilowany przez Webpack 5 oraz nazewnictwo w stylu BEM (.product__name, .product__description-short). Konfiguracja jest taka sama jak w Classic, należy zapisać theme.yml z parent: hummingbird oraz zakresem zgodności zaczynającym się od 9.1.0. Ciekawą częścią jest sposób dostosowywania zasobów.

System warstw CSS i dlaczego przestaje się walczyć ze specyficznością

Hummingbird deklaruje kolejność swoich warstw w SCSS:

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

Style w późniejszych warstwach wygrywają z wcześniejszymi, niezależnie od specyficzności selektora. To część, która zaskakuje osoby przychodzące z Classic. !important nie jest już potrzebny. Dłuższy selektor nie jest potrzebny. Wystarczy umieścić reguły we właściwej warstwie, a wygrają.

@layer ps-components {
  .product__name {
    font-family: 'Your Custom Font', sans-serif;
  }
}

@layer ps-pages {
  .page--category .product-miniature {
    border: 1px solid #eee;
    border-radius: 8px;
  }
}

Kompilacja SCSS

Jeśli zamiast zwykłego CSS preferowany jest SCSS, należy dodać krok kompilacji. Plik package.json z sass jako zależnością deweloperską, skrypty dla build:css (sass src/scss/custom.scss assets/css/custom.css --style=compressed) oraz watch:css. Następnie npm install && npm run build:css.

Dart Sass czasami dokleja na początku skompilowanego CSS znacznik kolejności bajtów UTF-8 (BOM). Przeglądarki wtedy po cichu ignorują pierwszą regułę i traci się pół godziny na zastanawianie, dlaczego reset się nie stosuje. Należy go usunąć: sed -i '1s/^\xEF\xBB\xBF//' assets/css/custom.css. Dodaliśmy to do każdego potoku kompilacji Sass, który prowadzimy.

Nadpisania szablonów

To tutaj motywy potomne zarabiają na siebie. Implementacja Smarty w PrestaShop obsługuje przejrzysty model dziedziczenia i to właśnie tak każdy z naszych sklepów stosuje korekty układu.

Jak PrestaShop wybiera szablon

1. Motyw potomny: themes/my-child/templates/
2. Motyw nadrzędny: themes/hummingbird/templates/

Droga na skróty: skopiowanie całego pliku

Należy skopiować szablon nadrzędny do motywu potomnego, a następnie go edytować. Wersja użytkownika zastępuje wersję nadrzędną całkowicie:

cp themes/hummingbird/templates/catalog/product.tpl \
   themes/my-child/templates/catalog/product.tpl

Cena, którą się płaci: jest się teraz właścicielem całego pliku. Gdy PrestaShop wyda poprawkę tego szablonu w kolejnej mniejszej aktualizacji (a wydaje), ta kopia jej nie otrzyma. Tego podejścia używamy do szablonów, które naprawdę przepisaliśmy od początku do końca, i prawie nigdy w innych przypadkach.

Właściwa droga: {extends} i nadpisanie tylko tych bloków, na których zależy

{extends file='parent:catalog/listing/category.tpl'}

{block name='product_list_header'}
  <div class="custom-category-header">
    <h1>{$category.name}</h1>
    <p>{$listing.pagination.total_items} products</p>
  </div>
{/block}

Prefiks parent: ma znaczenie. Bez niego Smarty rozwiązuje plik z powrotem do własnego szablonu potomnego, który rozszerza sam siebie, nieskończona pętla, timeout PHP. Widzieliśmy to na każdym projekcie Smarty, który się rozrasta, ktoś pisze fragment, zapomina o prefiksie i obserwuje, jak żądanie umiera.

Dołączanie i poprzedzanie zamiast zastępowania

Nie zawsze chce się zastąpić blok, czasem chce się coś do niego dodać. Smarty ma na to modyfikatory:

{extends file='parent:catalog/product.tpl'}

{block name='product_description' append}
  <div class="shipping-notice">Free shipping on orders over $50</div>
{/block}

{block name='product_prices' prepend}
  <span class="price-badge">Best Price</span>
{/block}

Bloki, które udostępnia strona produktu Hummingbird

Punkty nadpisania w pliku catalog/product.tpl Hummingbird:

{block name='product_cover_thumbnails'}: zdjęcia produktu
{block name='product_header'}: nazwa produktu (h1)
{block name='product_manufacturer'}: link do marki
{block name='product_prices'}: wyświetlanie ceny
{block name='product_description_short'}: opis skrócony
{block name='product_variants'}: selektory kombinacji
{block name='product_add_to_cart'}: przycisk dodania do koszyka
{block name='product_tabs'}: akordeon opisu/szczegółów
{block name='product_accessories'}: produkty powiązane

W przypadku dowolnej innej strony sztuczka polega na przeczytaniu szablonu nadrzędnego. Każdy {block name='...'} w szablonie nadrzędnym to punkt nadpisania, który można obrać za cel z motywu potomnego.

Dostosowywanie CSS

Konwencja custom.css, i dlaczego Classic oraz Hummingbird jej nie respektują

Kilka popularnych motywów komercyjnych (Warehouse, Flavor oraz kilka motywów z marketplace) automatycznie ładuje custom.css i custom.js, jeśli te pliki istnieją w katalogu assets/ motywu. Plik assets.yml motywu rejestruje je z wysokim priorytetem, ładują się jako ostatnie i nigdy nie są ruszane przez aktualizacje motywu, ponieważ nie są częścią plików dystrybucyjnych motywu. To najczystszy wzorzec, jaki PrestaShop ma dla sytuacji „chcę po prostu dodać kilka reguł CSS bez posiadania motywu potomnego”.

themes/your-theme/
  assets/
    css/
      theme.css          <-- główny arkusz stylów motywu (aktualizowany przez motyw)
      custom.css         <-- własne nadpisania (nigdy nieruszane przez aktualizacje)
    js/
      theme.js           <-- główny JS motywu (aktualizowany przez motyw)
      custom.js          <-- własne skrypty (nigdy nieruszane przez aktualizacje)

Kiedy wybrać które rozwiązanie:

• custom.css: zmiany wyłącznie w CSS: kolory, czcionki, odstępy, ukrywanie elementów, drobne zmiany układu. Bez zmian w HTML. Bez JS. Najszybsza możliwa pętla iteracji.
• Motyw potomny: wszystko, co zmienia strukturę HTML, dodaje JavaScript, nadpisuje szablon modułu lub przebudowuje układ. Motyw potomny może zawierać własny custom.css na wierzchu.

Classic i Hummingbird nie ładują automatycznie custom.css. Jeśli używany jest domyślny motyw PrestaShop, potrzebny jest albo motyw potomny z plikiem zarejestrowanym w theme.yml, albo moduł taki jak Custom CSS & JavaScript, który pozwala wstrzykiwać kod z panelu administracyjnego. Tego drugiego używamy na małych sklepach klientów, gdzie sprzedawca nie korzysta z SSH, a nam wystarczy wprowadzić trzy korekty kolorów.

CCC sprawi problemy. Gdy Łączenie, kompresja, pamięć podręczna (CCC) jest włączone, plik custom.css zostaje scalony w plik łączony o nazwie będącej skrótem. Po edycji custom.css na froncie nic się nie zmienia, dopóki nie podbije się wersji CSS w ustawieniach Wydajność lub nie usunie się themes/*/assets/cache/. Każde zgłoszenie wsparcia w stylu „przecież zmieniłem CSS!”, na które odpowiadaliśmy, zaczyna się właśnie tutaj.

Rejestrowanie CSS przez theme.yml

assets:
  use_parent_assets: true
  css:
    all:
      - id: my-child-custom-style
        path: assets/css/custom.css
        media: all
        priority: 200

Wyższe wartości priority ładują się później, dając naturalną przewagę nadpisywania nad stylami nadrzędnymi. Na Hummingbird zamiast gimnastyki z priorytetami warto preferować @layer, to cały powód, dla którego istnieje system warstw. Na Classic warto dopasować głębokość selektora motywu nadrzędnego i unikać !important. Gdy raz zacznie się rozsypywać !important, wchodzi się w wojnę, którą można tylko eskalować.

Zmiana kolorystyki sklepu Hummingbird w trzech wierszach

:root {
  --bs-primary: #2563eb;
  --bs-primary-rgb: 37, 99, 235;
  --bs-body-font-family: 'Inter', system-ui, sans-serif;
}

To wszystko. Podejście Bootstrap 5 oparte na niestandardowych właściwościach sprawia, że zmiany na poziomie rebrandingu nie wymagają ani jednej rekompilacji SCSS.

Dostosowywanie JavaScript

Rejestrowanie JS przez theme.yml

assets:
  use_parent_assets: true
  js:
    all:
      - id: my-child-custom-js
        path: assets/js/custom.js
        priority: 200

Wystarczy zamienić all na nazwę strony, aby ograniczyć zasięg skryptu: product, category, cart, checkout, cms, index (strona główna) lub dowolna nazwa kontrolera. Większość skryptów analitycznych i śledzących ładujemy globalnie, a większość usprawnień specyficznych dla strony. Z ograniczonym zasięgiem; nie ma powodu, by przyklejony pasek strony koszyka był parsowany przy każdej odsłonie produktu.

Magistrala zdarzeń JS w PrestaShop

Front office udostępnia niewielką magistralę zdarzeń na window.prestashop. Zamiast odpytywać DOM, warto nasłuchiwać zdarzeń, które są istotne:

prestashop.on('updatedProduct', function(event) { /* zmieniono kombinację */ });
prestashop.on('updateCart', function(event) { /* zaktualizowano koszyk */ });

jQuery: nadal jest ładowane i nadal nie należy go usuwać

Classic ładuje jQuery globalnie. Hummingbird również ładuje jQuery 3.x ze względu na zgodność z modułami, mimo że sam motyw jest oparty na TypeScript. Dla własnego kodu na Hummingbird czysty JavaScript daje lepszą wydajność, Bootstrap 5 porzucił zależność od jQuery, a motyw idzie w jego ślady. Jeśli jednak usunie się jQuery, żeby „posprzątać”, każdy zewnętrzny moduł, który nadal używa $(...), się zepsuje. Mamy zasadę: nigdy nie wyłączać jQuery na sklepie produkcyjnym bez wcześniejszego sprawdzenia każdego aktywnego modułu.

Nadpisania szablonów modułów

Szablony dowolnego modułu można nadpisać z poziomu motywu, odzwierciedlając strukturę katalogów modułu w themes/your-child/modules/. To jedna z najlepszych funkcji PrestaShop i najczystszy sposób na zmianę stylu modułu firmy trzeciej bez jego forkowania.

Kolejność rozstrzygania

1. Motyw potomny: themes/my-child/modules/module_name/views/templates/...
2. Motyw nadrzędny: themes/parent/modules/module_name/views/templates/...
3. Sam moduł: modules/module_name/views/templates/...

Mechanika

Należy znaleźć szablon modułu (np. modules/ps_featuredproducts/views/templates/hook/ps_featuredproducts.tpl), skopiować go do odpowiadającej ścieżki w katalogu modules/ motywu, edytować. Moduł aktualizuje się swobodnie, nie ruszając wersji użytkownika.

Nadpisania motywu wygrywają bezwzględnie. Jeśli moduł załata swój szablon, by naprawić lukę XSS, a motyw ma sprzed pół roku kopię, nadal renderuje się stara wersja, wraz z XSS. Nadpisania modułów warto porównywać (diff) z bieżącymi wersjami modułów co najmniej raz na kwartał. Robimy to w ramach kwartalnej konserwacji każdego sklepu.

Tłumaczenia wewnątrz motywów potomnych

Kolejność wyszukiwania tłumaczeń:

1. Tłumaczenia z bazy danych (panel administracyjny > Międzynarodowe > Tłumaczenia)
2. Katalog translations/ motywu potomnego
3. Katalog translations/ motywu nadrzędnego
4. Tłumaczenia modułów
5. Tłumaczenia rdzenia

Do jednorazowych zmian ciągów wystarczy edytor tłumaczeń w panelu administracyjnym. Do wszystkiego, co ma trafić do Git, należy utworzyć pliki XLIFF w themes/my-child/translations/en-US/Shop/Theme/Global.xlf:

<xliff xmlns="urn:oasis:names:tc:xliff:document:1.2" version="1.2">
  <file original="shop-theme-global" source-language="en-US"
        target-language="en-US" datatype="plaintext">
    <body>
      <trans-unit id="add_to_cart" approved="yes">
        <source>Add to cart</source>
        <target>Add to bag</target>
      </trans-unit>
    </body>
  </file>
</xliff>

Sklepy wielojęzyczne otrzymują po jednym katalogu na każdą lokalizację: translations/fr-FR/, translations/de-DE/. Po zmianach należy wyczyścić pamięć podręczną. Tłumaczenia są agresywnie buforowane: php bin/console cache:clear.

Dostosowania, które ostatecznie wykonujemy na większości sklepów

Przebudowany nagłówek

{extends file='parent:_partials/header.tpl'}

{block name='header_nav'}
  <nav class="custom-header-nav container">
    <div class="row align-items-center">
      <div class="col-md-3">{hook h='displayNav1'}</div>
      <div class="col-md-6 text-center">
        <a href="{$urls.base_url}"><img src="{$shop.logo}" alt="{$shop.name}"></a>
      </div>
      <div class="col-md-3 text-end">{hook h='displayNav2'}</div>
    </div>
  </nav>
{/block}

Własne czcionki zrobione poprawnie

Pliki WOFF2 w assets/fonts/, do których odwołuje się CSS:

@font-face {
  font-family: 'CustomFont';
  src: url('../fonts/CustomFont-Regular.woff2') format('woff2');
  font-weight: 400;
  font-display: swap;
}
body { font-family: 'CustomFont', system-ui, sans-serif; }

Zawsze należy ustawiać font-display: swap. Bez tego przeglądarka ukrywa tekst do czasu załadowania czcionki, a wynik Largest Contentful Paint zostaje ukarany przez Core Web Vitals. Krytyczną czcionkę warto wstępnie wczytać: <link rel="preload" as="font" type="font/woff2" crossorigin>. Widzieliśmy, jak wyniki LCP skakały o 30 punktów na sklepach, które wprowadziły tylko tę jedną poprawkę.

Przeniesienie pełnego opisu poza zakładki

{extends file='parent:catalog/product.tpl'}

{block name='product_description_short'}
  <div class="product__description-short">{$product.description_short nofilter}</div>
  {if $product.description}
    <div class="product__description-full mt-3">{$product.description nofilter}</div>
  {/if}
{/block}

{block name='product_description'}{/block} {* usunięte z zakładek *}

Co zmieniło się w motywach PS 9

• Hummingbird jest domyślny na świeżych instalacjach PS 9.1. Zaktualizowane sklepy zachowują poprzedni motyw. Classic nadal jest dostarczany i działa, ale nowe funkcje trafiają najpierw do Hummingbird.
• Smarty pozostaje w front office. Twig jest używany w panelu administracyjnym (coraz częściej, choć migracja nie jest jeszcze ukończona w 100%). Nadpisania {extends} i {block} we front office działają dalej bez zmian.
• Bootstrap 5.3 zamiast Bootstrap 4. W przypadku migracji motywu potomnego z Classic na Hummingbird przewodnik migracji Bootstrap to strona, którą warto mieć otwartą.
• Warstwy CSS zmieniają sposób rozstrzygania specyficzności. Należy przestać sięgać po !important.
• WebP jest domyślnym formatem obrazów. Nowy klucz framework w theme.yml: bootstrap-v5.3.3.
• Niektóre starsze zmienne globalne JS zniknęły. Wszystko, co zaczepiało się o stary JS z Classic, będzie wymagało przetestowania.

Twig może w końcu dotrzeć do front office w przyszłej wersji głównej. Jeśli utrzyma się nadpisania minimalne, a nazwy bloków rozsądne, przejście będzie łatwiejsze, gdy to nastąpi.

Debugowanie problemów z motywem

Pierwszy ruch, zawsze: php bin/console cache:clear. Na potrzeby pracy deweloperskiej warto ustawić pamięć podręczną szablonów na „Wymuś rekompilację” i wyłączyć CCC w Parametry zaawansowane > Wydajność. Wszystko inne oznacza debugowanie plików z pamięci podręcznej, a nie własnego kodu.

Jeśli zmienia się szablon i nie widać zmiany, to pamięć podręczna kłamie. Nie należy dalej majstrować przy szablonie, należy wyczyścić pamięć podręczną, wymusić rekompilację, a potem spojrzeć ponownie. Połowa zgłoszeń „moje nadpisanie nie działa”, które otrzymujemy, zaczyna się od zapomnianej pamięci podręcznej kompilacji.

Dopisanie ?SMARTY_DEBUG do dowolnego adresu URL frontu wywołuje wyskakujące okno pokazujące każdy załadowany szablon i każdą zmienną w zasięgu. Ustawienie _PS_SMARTY_FORCE_COMPILE_ oraz _PS_SMARTY_CONSOLE_ na 1 w config/defines.inc.php utrzymuje to włączone między przeładowaniami.

Błędy, na które faktycznie się natknie

Jeśli pamięć podręczna naprawdę utknęła, należy ręcznie usunąć var/cache/prod/smarty/compile/ oraz var/cache/prod/smarty/cache/. Robimy to częściej, niż chcielibyśmy przyznać.

Aktualizacja: gdzie motyw potomny w końcu się zwraca

Gdy motyw nadrzędny się aktualizuje, oto co dzieje się z każdym plikiem:

• Tylko w motywie nadrzędnym: aktualizuje się normalnie, motyw potomny automatycznie dziedziczy nową wersję.
• Nadpisany w motywie potomnym: wersja z motywu potomnego nadal wygrywa. Aktualizacja motywu nadrzędnego jest dla sklepu niewidoczna.
• Własne pliki tylko motywu potomnego: całkowicie nietknięte.

Przed uruchomieniem aktualizacji motywu nadrzędnego: należy wykonać kopię zapasową wszystkiego, wypisać własne nadpisania (find themes/my-child/templates -name "*.tpl"), uruchomić aktualizację na środowisku testowym (mamy na to instrukcję w przewodniku po lokalnym środowisku deweloperskim), porównać (diff) zmienione szablony nadrzędne z własnymi nadpisaniami, a następnie przetestować każdą dostosowaną stronę na prawdziwych urządzeniach. Pominięcie któregokolwiek z tych kroków sprawi, że okaże się to o 8 rano w niewłaściwy poniedziałek.

Punktowe nadpisania {extends} biją kopie całych plików, za każdym razem. Gdy motyw nadrzędny dodaje nowy blok, motyw potomny z {extends} dziedziczy go automatycznie. Kopia całego pliku pomija go całkowicie, a okazuje się to dopiero, gdy klient poskarży się, że nowej funkcji nie ma.

Lista kontrolna przed uruchomieniem

Konfiguracja: theme.yml ma poprawny parent: oraz pisaną małymi literami, bez spacji wartość name:. Ustawiono use_parent_assets: true. Jeśli dołączono preview.png, obraz wyświetla się poprawnie. Zakres zgodności odpowiada wersji PS, na której się wdraża.

Szablony: Każde nadpisanie używa {extends file='parent:...'} tam, gdzie to możliwe. Nazwy bloków odpowiadają nadrzędnym znak w znak. Katalog var/logs/ jest czysty. Nadpisania modułów zostały porównane (diff) z bieżącymi wersjami modułów. nofilter jest na każdej zmiennej HTML, która nie wymaga ponownego escapowania.

Zasoby: Własny CSS ładuje się po nadrzędnym (wysoki priority lub właściwa @layer). Bez rozsianego !important. Czcionki w formacie WOFF2 z font-display: swap. Bez błędów w konsoli JS. CCC zostało włączone, a witryna nadal się renderuje.

Testy: Desktop w Chrome, Firefox, Safari, Edge. Mobilnie w iOS Safari i Android Chrome. Każdy responsywny punkt przełamania. Dotyk: strona główna, kategorie, produkt, koszyk, checkout, konto klienta, CMS, wyszukiwarka, 404.

Konserwacja: Motyw potomny jest w Git. Nadpisania są udokumentowane w miejscu, które człowiek znajdzie. Proces kompilacji jest spisany (więcej w naszym przewodniku po narzędziach deweloperskich). Zespół wie, że nie wolno edytować plików motywu nadrzędnego.

Powiązane lektury

• Jak migrować do PrestaShop 9: kompletny przewodnik aktualizacji: zmiany motywów przy skoku na PS 9
• Hooki i nadpisania PrestaShop: przewodnik referencyjny dla deweloperów: kiedy sięgnąć po hook zamiast nadpisania motywu
• SEO w PrestaShop: adresy URL, schema, mapy witryny i Core Web Vitals: przyjazne SEO dostosowania motywu
• Motywy potomne w PrestaShop: dlaczego nigdy nie należy edytować motywu nadrzędnego
• Jak wybrać odpowiedni motyw PrestaShop dla swojej firmy

Powiązane moduły

• HTML Blocks: dodawanie konfigurowalnych bloków treści zamiast edytowania szablonów
• Mega Menu: budowanie zaawansowanego nagłówka/nawigacji bez ingerencji w motyw
• Product Extra Info Tabs: dodawanie zakładek na stronie produktu bez nadpisywania szablonów

Powiązane pytania

• Zmiany CSS nie pojawiają się na froncie sklepu.
• Tłumaczenie modułu nie działa, tekst zostaje po angielsku.
• Override nie działa. Mój custom template jest ignorowany.
• Darmowe a premium szablony PrestaShop: co tak naprawdę otrzymujesz
• Co sprawdza ocena przydatności motywu?
• Czy mogą Państwo ocenić motyw, który już kupiłem lub na którym zbudowałem sklep?