Individuelle Template-Anpassungen (Twig, HTML)

In diesem Artikel erfährst du, wie du individuelle Template-Anpassungen mit dem "ThemeWare® Customizing Plugin" durchführen kannst.

Wenn du das Erscheinungsbild von ThemeWare® mittels einer Template-Anpassung individuell verändern möchtest, findest du in diesem Artikel nützliche Tipps für die Arbeit mit Template-Dateien.

Tipp: Das erstellen eines ThemeWare® Duplikates ist für Template-Anpassungen nicht notwendig.

---

Einleitung

Für individuelle Template-Anpassungen brauchst du in Shopware 6 ein eigenes Theme oder eine separate Erweiterung (Plugin oder App) und nicht – wie bei Shopware 5 – eine Theme-Ableitung.

• Prüfe ob es im Shopware Community Store bereits ein passende Erweiterung gibt.

• Alternativ kannst du die manuelle Methode mit unserem "ThemeWare® Customizing Plugin" bzw. der "ThemeWare® Customizing App" nutzen (siehe Abschnitt "Template Anpassungen integrieren (für erfahrende Anwender)").

---

Einsicht in den Quellcode

Den grundlegenden Aufbau (Ordner, Template-Dateien, Twig-Blöcke etc.) gibt das Shopware Theme "Shopware default theme" vor, da ThemeWare® technisch eine "Erweiterung" dessen ist.

Hinweis: In der Shopware Cloud gibt es derzeit keine Möglichkeit Dateien von Erweiterungen (Plugins, Apps oder Themes) einzusehen.

Achtung: Bearbeite in keinem Fall Originaldateien von Shopware oder Erweiterungen (Plugins, Apps oder Themes)!

ThemeWare® Pro-Edition

custom/plugins/TcinnThemeWareXYZ/src/Resources/views
custom/plugins/TcinnThemeWareXYZ/src/Resources/views/themeware

ThemeWare® Cloud-Edition

custom/apps/TcinnThemeWareXYZApp/Resources/views/storefront
custom/apps/TcinnThemeWareXYZApp/Resources/views/storefront/themeware

ThemeWare® leitet im Rahmen unserer HC-Architecture® nur die nötigsten Template-Dateien ab und ergänzt für eigene Funktionen und Features (z.B. Widgets) eigene Template-Dateien.

Ergänzend dazu findest du den Quellcode vom Shopware Standard-Theme auf GitHub. Im Ordner "views/storefront" befinden sich alle Template-Dateien die für die Storefront relevant sind.

Die passende Template-Datei finden

Wenn du eine bestimmte Stelle in den Templates suchst, kannst du z.B. über den Inspektor deines Browsers eine CSS-Klasse suchen die sich an dem entsprechenden Element oder zumindest in unmittelbarer Umgebung des entsprechenden Elementes befindet.

Diese CSS-Klasse kannst du dann im Shopware Git-Repository suchen. Meist findet man so recht schnell eine passende Template-Datei.

Beispiel

Möchtest du beispielsweise etwas unterhalb der Produktbeschreibung ergänzen, schau dir den HTML-Code der Beschreibung einmal genauer an:

...
<div class="product-detail-description tab-pane-container">
        <h2 class="product-detail-description-title">
                Product information "Main product with reviews"
        </h2>
        
        <div class="product-detail-description-text" itemprop="description">
                Lorem ipsum dolor sit amet, consetetur sadipscing elitr, ...
        </div>       
</div>
...

Der Beschreibung ist von einem <div> mit der Klassse product-detail-description-text umgeben.

Wir durchsuchen das Git-Repository also einmal nach dieser CSS-Klasse und finden die Datei description.html.twig (siehe GitHub).

Ein Blick in den Quellcode dieser Datei zeigt, dass der <div> mit der Klassse product-detail-description-text sich im Twig-Block component_product_description_content_text befindet.

...
{% block component_product_description_content_text %}
    <div class="product-detail-description-text"
         itemprop="description">
        {{ product.translated.description|raw }}
    </div>
{% endblock %}
...

Leite also die Datei description.html.twig für deine Template-Anpassung ab und erweitere den Twig-Bock component_product_description_content_text.

Weitere Informationen zum ableiten und erweitern von Template-Dateien findest du nachfolgend.

---

Template Anpassungen integrieren (für erfahrende Anwender)

In Shopware 6 fehlt derzeit ein vollwertiges Child-Theme über welches man Dateien einbinden und Änderungen vornehmen kann (wie z.B. bei Shopware 5). Wir haben als Workaround ein kleines kostenfreies "ThemeWare® Customizing Plugin" bzw. eine "ThemeWare® Customizing App" für die Integration von individuellen Anpassungen und eigenen Dateien entwickelt.

Alle Informationen zu den Erweiterungen, zur Installation und die Download-Links findest du in folgenden Artikeln:

Individuelle Anpassungen mit dem ThemeWare® Customizing PluginIndividuelle Anpassungen mit der ThemeWare® Customizing App (Cloud)

---

Hilfreiche Twig-Grundlagen

Shopware 6 nutzt als Template-Engine Twig und nicht mehr Smarty wie in Shopware 5. Viele Dinge sind in Twig aber gleich oder zumindest sehr ähnlich. Damit du einen groben Überblick über Twig bekommst, haben wir nachfolgend die wichtigsten Informationen kurz zusammengefasst.

Hinweis: Weiterführende Links rund um das Thema "Twig" findest du in der Twig-Dokumentation unter: https://twig.symfony.com

Eine Template-Datei ableiten

In der ersten Zeile der Datei muss definiert werden, von welcher übergeordneten Datei diese abgeleitet wird.

{% sw_extends '@Storefront/storefront/page/product-detail/headline.html.twig' %}

ThemeWare® Template-Datei ableiten

{% sw_extends '@Storefront/storefront/themeware/extensions/twt-hero-section.html.twig' %}

Inhalt in Twig-Block ergänzen

Um eigne Inhalte vor oder nach dem eigentlichen Inhalt des Blocks zu platzieren, musst du nicht den kompletten Code des Blocks kopieren. Du kannst dafür den parent-Befehl wie folgt nutzen:

Inhalt nach dem Originalinhalt des Blocks ergänzen:

{% block name_des_blocks %}
  {{ parent() }}

  {# Platziere hier den neuen Inhalt #}
{% endblock %}

Inhalt vor dem Originalinhalt des Blocks ergänzen:

{% block name_des_blocks %}
  {# Platziere hier den neuen Inhalt #}

  {{ parent() }}
{% endblock %}

Twig-Block überschreiben

Möchtest du den Originalinhalt des Blocks vollständig austauschen, kannst du auf den parent-Befehl verzichten um den Block zu leeren.

{% block page_product_detail_name_container %}
  {# Platziere hier den neuen Inhalt #}
{% endblock %}

Anzeigen aller Variablen

Die Ausgabe aller auf der Seite verfügbaren Variablen erreichst du mit dem dump-Befehl. Die Ausgabe muss in einem Block erfolgen und ist nur im Entwicklermodus verfügbar.

{{ dump() }}

Textbaustein einbinden

Den Namen des gewünschten Textbausteins kannst du der Textbaustein-Verwaltung deiner Administration ("Einstellungen" => "Shop" => "Textbausteine") entnehmen.

Damit die Übersetzungen der einzelnen Textbaustein-Sets berücksichtigt werden nutze den Zusatz |trans.

{% block name_des_blocks %}
  {{ parent() }}
  
  {{ "twt.widget.communities.headline"|trans }}
{% endblock %}

Zusatzfelder in der Storefront ausgeben

Ein Zusatzfeld auf Produktebene wird wie folgt ausgeben:

{{ page.product.translated.customFields.technischer_name_zusatzfeld }}

Ein Zusatzfeld für Kategorien wird wie folgt ausgegeben:

{{ page.footer.navigation.active.translated.customFields.technischer_name_zusatzfeld }}

Tipp: Mehr Informationen zu Zusatzfeldern und dem einbinden in die Storefront findest du im Artikel Zusatzfelder (Custom Fields).

Abfragen einer ThemeWare® Variable

Die Abfrage einer Theme-Variable (z.B. die ThemeWare® Konfiguration "Body-Klasse") in einem Twig-Block funktioniert wie folgt:

{% if theme_config('twt-body-class') %}
    ...
{% endif %}

Ausgabe einer ThemeWare® Variable

Die Ausgabe einer Theme-Variable muss ebenfalls in einem Twig-Block erfolgen. Das folgende Beispiel zeigt die ThemeWare® Konfiguration "Body-Klasse" (Tab "Weiteres" => Bereich "Experten-Einstellungen" => Abschnitt "Individuelle CSS-Klasse" => Feld "Body-Klasse").

{{ theme_config('twt-body-class') }}

---

Zusätzliches ThemeWare® Wissen

ThemeWare® Variablen finden

Über unseren ThemeWare® Config-Finder hast du die Möglichkeit alle ThemeWare® Variablen anzeigen zu lassen. Der "technische Name" in dieser Übersicht ist der Name der entsprechenden Variable, die du in Twig oder SCSS verwenden kannst.

Abgrenzung für ThemeWare® Anpassungen

Ist eine Template-Anpassung nur für einen bestimmten Verkaufskanal relevant, hast du die Möglichkeit deine Anpassung beispielsweise über die ThemeWare® Konfiguration mit der "Body-Klasse" einzuschränken.

Hinterlege dafür im Theme-Duplikat für den entsprechenden Verkaufskanal unter Tab "Weiteres" => Bereich "Experten-Einstellungen" => Abschnitt "Individuelle CSS-Klasse" => Feld "Body-Klasse" einen eindeutigen Namen für diesen Verkaufskanal (z.B. meinshopname).

Dieser Name kann dann in einer zusätzlichen Schleife auch für Twig genutzt werden.

{# Anpassung nur für Theme mit der Body-Klasse z.B. "meinshopname" #}

{% if theme_config('twt-body-class') == "meinshopname" %}
  {# Theme hat die Body-Klasse "meinshopname" #}
  ...
  {{ parent() }}
{% else %}
  {# Theme hat nicht die Body-Klasse "meinshopname" #}
  {{ parent() }}
{% endif %}

Alternativ kannst du deine Anpassung auch an die ID des Verkaufskanals binden:

{# Anpassung für einen Sales channel mit der ID "..." #}

{% if context.salesChannel.id == "..." %}
  {# Sales channel hat die ID "..." #}
  ...
  {{ parent() }}
{% else %}
  {# Sales channel hat nicht die ID "..." #}
  {{ parent() }}
{% endif %}