PrestaShop Child Themes: Classic & Hummingbird Anpassung

Was ist ein Child Theme und warum es wichtig ist

Ein Child Theme erbt Templates und Assets von einem Parent Theme und ermöglicht es Ihnen, nur das zu überschreiben, was Sie ändern. Ohne eines befinden sich alle CSS-Anpassungen oder Template-Änderungen in den Dateien des Parent Themes — und werden beim nächsten Update überschrieben.

Ein Child Theme ist eine transparente Überlagerung. PrestaShop schaut zuerst im Child Theme nach. Findet es eine Datei, wird diese verwendet. Wenn nicht, fällt es auf das Parent Theme zurück. Sie fügen nur das hinzu, was Sie ändern.

Verwenden Sie ein Child Theme für gezielte Anpassungen — Farben, Layout-Korrekturen, Template-Überschreibungen, benutzerdefiniertes CSS/JS. Erstellen Sie ein vollständig eigenes Theme nur dann, wenn Sie eine grundlegend andere Architektur benötigen.

Für neue Projekte mit PrestaShop 8.1+ wählen Sie Hummingbird — es ist der zukunftsorientierte Standard und das einzige aktiv gepflegte Theme des PrestaShop-Projekts.

Struktur eines Child Themes

Ein Child Theme befindet sich neben seinem Parent Theme im Verzeichnis /themes/. Das minimal funktionsfähige Child Theme benötigt nur zwei Dateien:

themes/my-child-theme/
  config/
    theme.yml             <-- erforderlich: Theme-Konfiguration
  preview.png             <-- erforderlich: 200x200 Theme-Vorschau

Mit zunehmenden Anpassungen spiegelt das Verzeichnis die Struktur des Parent Themes wider, enthält aber nur geänderte Dateien:

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

Fügen Sie nur Dateien hinzu, die Sie ändern. Jede hinzugefügte Datei ist eine Datei, die Sie pflegen müssen. Ein leeres Child Theme, das alles erbt, ist besser als eines, das mit unveränderten Kopien überladen ist.

Die theme.yml-Konfiguration

Die config/theme.yml ist das Herzstück Ihres Child Themes. Die entscheidende Zeile ist parent: classic (oder parent: hummingbird) — diese legt die Vererbungskette fest:

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

Ein Child Theme für Classic erstellen

Classic ist das ursprüngliche Standard-Theme von PrestaShop seit Version 1.7. Der Vorgang umfasst vier Schritte:

# 1. Verzeichnis erstellen
mkdir -p themes/my-classic-child/config

# 2. config/theme.yml mit parent: classic erstellen (siehe oben)

# 3. preview.png hinzufügen (200x200)

# 4. Aktivieren über Back Office > Design > Theme & Logo
#    Oder CLI: php bin/console prestashop:theme:enable my-classic-child

Mit use_parent_assets: true und ohne Überschreibungen erhalten Sie eine pixelgenaue Kopie von Classic. Templates, CSS, JS, Bildtypen, Layouts und Modul-Template-Überschreibungen werden alle vererbt.

Ein Child Theme für Hummingbird erstellen

Hummingbird verwendet Bootstrap 5.3 (CSS Custom Properties), CSS Layers (@layer), TypeScript kompiliert mit Webpack 5 und BEM-ähnliche Benennung (.product__name, .product__description-short). Die Einrichtung ist identisch mit Classic — erstellen Sie theme.yml mit parent: hummingbird und Kompatibilität from: 9.0.0. Der Unterschied liegt in der Asset-Anpassung.

Hummingbirds CSS-Layer-System

Hummingbird definiert diese Layer-Reihenfolge in seinem SCSS:

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

Styles in späteren Layers überschreiben frühere unabhängig von der Selektor-Spezifität. Platzieren Sie benutzerdefinierte Regeln im entsprechenden Layer:

@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;
  }
}

SCSS-Kompilierung

Für benutzerdefiniertes SCSS fügen Sie einen Build-Schritt hinzu. Erstellen Sie eine package.json mit sass als Dev-Dependency und Scripts für build:css (sass src/scss/custom.scss assets/css/custom.css --style=compressed) und watch:css. Dann npm install && npm run build:css zum Kompilieren.

Dart Sass kann ein UTF-8 BOM an kompiliertes CSS voranstellen, wodurch Browser Regeln stillschweigend ignorieren. Entfernen Sie es: sed -i '1s/^\xEF\xBB\xBF//' assets/css/custom.css

Template-Überschreibungen

Template-Überschreibungen sind die Stärke von Child Themes. PrestaShop verwendet Smarty, das ein sauberes Vererbungsmodell unterstützt.

Template-Auflösungsreihenfolge

1. Child Theme — themes/my-child/templates/
2. Parent Theme — themes/hummingbird/templates/

Methode 1: Vollständige Kopie (einfach, weniger wartbar)

Kopieren Sie das Parent-Template und bearbeiten Sie es. Ihre Version ersetzt das Parent-Template vollständig:

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

Nachteil: Sie sind für die gesamte Datei verantwortlich. Aktualisierungen des Parent-Templates erreichen Sie nicht mehr.

Methode 2: Smarty {extends} (empfohlen)

Erweitern Sie das Parent-Template und überschreiben Sie nur bestimmte Blöcke:

{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}

Das parent:-Präfix ist entscheidend — ohne es findet Smarty die eigene Datei des Child Themes und erzeugt eine Endlosschleife.

Block-Modifikatoren

Anstatt einen Block vollständig zu ersetzen, hängen Sie Inhalte an oder stellen Sie sie voran:

{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}

Hummingbirds Block-Struktur

Wichtige Überschreibungspunkte auf Hummingbirds Produktseite (catalog/product.tpl):

{block name='product_cover_thumbnails'}   — Produktbilder
{block name='product_header'}              — Produktname (h1)
{block name='product_manufacturer'}        — Markenlink
{block name='product_prices'}              — Preisanzeige
{block name='product_description_short'}   — Kurzbeschreibung
{block name='product_variants'}            — Kombinationsauswahl
{block name='product_add_to_cart'}         — Warenkorb-Button
{block name='product_tabs'}               — Beschreibung/Details-Akkordeon
{block name='product_accessories'}         — Verwandte Produkte

Um die verfügbaren Blöcke einer Seite zu finden, lesen Sie die Template-Datei des Parent Themes — jeder {block name='...'} ist ein Überschreibungspunkt.

CSS-Anpassung

CSS in theme.yml registrieren

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

Höhere priority-Werte werden später geladen, sodass Sie Parent-Styles überschreiben können. Für Hummingbird bevorzugen Sie @layer-Deklarationen, anstatt gegen die Spezifität zu kämpfen. Für Classic passen Sie die Selektortiefe des Parent Themes an. Vermeiden Sie !important.

Das Farbschema ändern

Für Hummingbird (Bootstrap 5) überschreiben Sie CSS Custom Properties:

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

JavaScript-Anpassung

JS in theme.yml registrieren

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

Ersetzen Sie all durch einen Seitennamen, um Scripts einzugrenzen: product, category, cart, checkout, cms, index (Startseite) oder einen beliebigen Controller-Namen.

PrestaShops JavaScript-Events

Ihre Scripts können über das globale prestashop-Objekt auf PrestaShop-Events lauschen:

prestashop.on('updatedProduct', function(event) { /* combination changed */ });
prestashop.on('updateCart', function(event) { /* cart updated */ });

jQuery-Verfügbarkeit

In Classic wird jQuery global geladen. In Hummingbird wird jQuery 3.x weiterhin für die Modulkompatibilität geladen, aber das Theme selbst verwendet TypeScript. Für neuen Child-Theme-Code bevorzugen Sie Vanilla JS.

Entfernen Sie jQuery nicht aus Ihrem Child Theme — Sie würden Drittanbieter-Module beschädigen, die darauf angewiesen sind. Für Ihren eigenen Code bietet Vanilla JS jedoch bessere Performance und Zukunftssicherheit.

Modul-Template-Überschreibungen

Sie können die Darstellung jedes Moduls überschreiben, indem Sie Templates im modules/-Verzeichnis Ihres Themes ablegen.

Auflösungsreihenfolge

1. Child Theme: themes/my-child/modules/module_name/views/templates/...
2. Parent Theme: themes/parent/modules/module_name/views/templates/...
3. Modul selbst: modules/module_name/views/templates/...

So überschreiben Sie

Suchen Sie das Template des Moduls (z.B. modules/ps_featuredproducts/views/templates/hook/ps_featuredproducts.tpl), kopieren Sie es in den entsprechenden Pfad unter themes/my-child/modules/ und bearbeiten Sie die Kopie. Das Modul kann frei aktualisiert werden, ohne Ihre Version zu beeinflussen.

Theme-Überschreibungen haben absolute Priorität. Wenn ein Modul sein Template aktualisiert, um ein Sicherheitsproblem zu beheben, und Ihr Theme eine ältere Kopie enthält, wird weiterhin die alte Version verwendet. Vergleichen Sie Ihre Überschreibungen regelmäßig mit den aktuellen Modulversionen.

Übersetzungen in Child Themes

Übersetzungs-Auflösungsreihenfolge:

1. Datenbank-Übersetzungen (Back Office > International > Übersetzungen)
2. Child-Theme-Verzeichnis translations/
3. Parent-Theme-Verzeichnis translations/
4. Modul-Übersetzungen
5. Core-Übersetzungen

Der einfachste Ansatz ist das Back Office (International > Übersetzungen). Für versionskontrollierte Übersetzungen erstellen Sie XLIFF-Dateien unter 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>

Für mehrsprachige Shops erstellen Sie Dateien pro Locale (translations/fr-FR/, translations/de-DE/). Leeren Sie den Cache nach Änderungen: php bin/console cache:clear

Häufige Anpassungen

Benutzerdefiniertes Header-Layout

{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}

Benutzerdefinierte Schriftarten

Platzieren Sie WOFF2-Dateien in assets/fonts/ und referenzieren Sie sie im 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; }

Verwenden Sie immer font-display: swap, um unsichtbaren Text während des Ladens zu vermeiden. Laden Sie wichtige Schriftarten vorab: <link rel="preload" as="font" type="font/woff2" crossorigin>.

Die Produktseite umstrukturieren

{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} {* aus Tabs entfernt *}

PS 9 Theme-Änderungen

• Hummingbird ist der Standard. Classic bleibt verfügbar, aber die aktive Entwicklung zielt auf Hummingbird ab.
• Smarty bleibt für das Front Office. Twig ist nur für das Admin-Panel. Ihre {extends}- und {block}-Überschreibungen funktionieren wie bisher.
• Bootstrap 5.3 ersetzt Bootstrap 4. Lesen Sie die Migrationsanleitung, wenn Sie von Classic wechseln.
• CSS Layers (@layer) verändern die Funktionsweise der Spezifität in Hummingbird.
• WebP als Standard für Bilder. Neuer framework-Schlüssel in theme.yml: bootstrap-v5.3.3.
• Einige ältere JS-Globals entfernt. Testen Sie gründlich bei der Migration von PS 8.

Twig könnte in einer zukünftigen Major-Version auch das Front Office erreichen. Saubere Templates mit minimalen Überschreibungen erleichtern jeden zukünftigen Übergang.

Theme-Probleme debuggen

Leeren Sie zunächst alle Caches: php bin/console cache:clear. Für die Entwicklung setzen Sie den Template-Cache auf „Kompilierung erzwingen“ und deaktivieren Sie CCC unter Erweiterte Einstellungen > Leistung.

Während der Entwicklung erzwingen Sie immer die Template-Kompilierung und deaktivieren Sie CCC. Andernfalls debuggen Sie gecachte Dateien.

Aktivieren Sie das Smarty-Debugging, indem Sie ?SMARTY_DEBUG an eine beliebige Front-URL anhängen. Dies zeigt geladene Templates, Dateipfade und Variablen an. Aktivieren Sie es in config/defines.inc.php, indem Sie _PS_SMARTY_FORCE_COMPILE_ und _PS_SMARTY_CONSOLE_ auf 1 setzen.

Häufige Fehler

Wenn der Cache bestehen bleibt, löschen Sie zusätzlich var/cache/prod/smarty/compile/ und var/cache/prod/smarty/cache/.

Upgrades mit Child Themes

Hier zahlen sich Child Themes aus. Wenn das Parent Theme aktualisiert wird:

• Dateien, die nur im Parent vorhanden sind — werden normal aktualisiert, das Child Theme erbt sie automatisch.
• Dateien, die im Child überschrieben wurden — die Version des Child Themes wird weiterhin verwendet, das Parent-Update ist unsichtbar.
• Eigene Child-Theme-Dateien — völlig unberührt.

Vor dem Update: Sichern Sie alles, listen Sie Ihre Überschreibungen auf (find themes/my-child/templates -name "*.tpl"), aktualisieren Sie in einer Staging-Umgebung (Anleitung zur lokalen Entwicklung), vergleichen Sie geänderte Parent-Templates mit Ihren Überschreibungen per diff und testen Sie jede angepasste Seite.

Gezielte {extends}-Überschreibungen sind vollständigen Dateikopien überlegen. Bei Block-Überschreibungen werden neue Parent-Blöcke automatisch einbezogen. Vollständige Dateikopien verpassen sie gänzlich.

Child-Theme-Checkliste vor dem Launch

Konfiguration: theme.yml enthält korrekte Werte für parent: und name: (Kleinbuchstaben, keine Leerzeichen). use_parent_assets: true ist gesetzt. preview.png existiert. Der Kompatibilitätsbereich stimmt mit Ihrer PS-Version überein.

Templates: Alle Überschreibungen verwenden nach Möglichkeit {extends file='parent:...'}. Blocknamen stimmen exakt mit dem Parent überein. Keine Smarty-Fehler in var/logs/. Modul-Überschreibungen gegen aktuelle Modulversionen getestet. nofilter für HTML-Variablen verwendet.

Assets: Benutzerdefiniertes CSS wird nach dem Parent geladen (hohe priority). Kein übermäßiger Einsatz von !important. Schriftarten verwenden font-display: swap und WOFF2. Keine JS-Konsolenfehler. CCC aktiviert, ohne etwas zu beeinträchtigen.

Tests: Desktop (Chrome, Firefox, Safari, Edge), Mobil (iOS Safari, Android Chrome), responsive Breakpoints. Überprüfen Sie: Startseite, Kategorien, Produkt, Warenkorb, Bestellvorgang, Kundenkonto, CMS, Suche, 404.

Wartung: Child Theme in Git. Überschriebene Templates dokumentiert. Build-Prozess dokumentiert (siehe unsere Anleitung zu Entwicklungswerkzeugen). Das Team weiß, dass Parent-Dateien nicht bearbeitet werden dürfen.