Eine Template-Datei erweitern

hostware verwendet im Hintergrund die Twig-Template-Engine. Dadurch kannst du jedes Storefront-Template überschreiben, indem du eine Datei am entsprechenden Pfad in deinem Theme oder Modul ablegst und nur die Blöcke neu definierst, die du ändern möchtest.

Mach dich vertraut

Mach dich zunächst mit den zentralen Template-Dateien des hostware-Storefronts vertraut. Sieh dir das Verzeichnis /resources/views/storefront an. Dort findest du alle grundlegenden Twig-Templates.

Die Verzeichnisstruktur ist äußerst wichtig und sollte jederzeit berücksichtigt werden. Du benötigst die Pfadstruktur immer dann, wenn du etwas erweitern möchtest.

Erweiterungsvorgang

Was möchtest du ändern?

Finde das Template, das du ändern möchtest. Musst du das HTML-Layout wirklich ändern, um das Theme an das Design anzupassen? Vielleicht kannst du dein Ziel allein mit CSS erreichen.

Nehmen wir an, du möchtest die folgende Produktkarte anpassen, die wahrscheinlich in einer separaten Komponente gekapselt ist.

Template finden

Du findest diese spezielle Karte unter /storefront/components/product/card.twig.

In diesem Fall sieht die Template-Datei so aus. Wie du siehst, befindet sich an jedem strategischen Punkt ein {% block %}-Wrapper um das HTML. Dadurch kannst du so wenig wie möglich ändern.

Das Ziel dieses Beispiels ist, a) der Klasse .card eine weitere Klasse hinzuzufügen und b) dem Kartentitel ein Präfix voranzustellen.

Erstelle dein Überschreibungs-Template

Um dieses Template zu überschreiben, musst du in deinem Theme- oder Modulverzeichnis ein Template mit demselben Namen und derselben Pfadstruktur erstellen.

Erstelle für dieses Beispiel das folgende Template: custom\themes\hw\hostx\resources\views\storefront\component\product\card.twig

Die erste Zeile deiner benutzerdefinierten card.twig-Datei sollte den Pfad zu der Datei enthalten, die du überschreiben möchtest. In diesem Fall müssen wir den Namespace storefront:: voranstellen, da wir ein zentrales Template ändern möchten. Dadurch weiß das hostware-Framework, in welcher Reihenfolge die Templates gerendert werden sollen.

{% hw_extends 'storefront::component/product/card.twig' %}

Einzelne Blöcke überschreiben

In unserem Beispiel möchten wir den Teil mit class="card" überschreiben, um unsere zusätzliche Klasse hinzuzufügen. Dazu müssen wir im ursprünglichen Template einen {% block %} finden, der vor dem Element steht, das wir ändern möchten. In diesem Beispiel eignet sich der Block product_item_card perfekt.

Schreiben wir zunächst den folgenden Code, um vorerst die gesamte Produktkarte zu überschreiben:

Der neue Inhalt „Overwrite!“ wird nun ANSTELLE des ursprünglichen Inhalts innerhalb dieses bestimmten Blocks gerendert. Stattdessen sollten wir nur das ändern, was wir benötigen, und anschließend den nächsten untergeordneten Block rendern, damit wir so wenig Kerncode wie möglich überschreiben. Das sollte funktionieren:

Wir möchten außerdem den Titel ändern. Jeder Block, den du ändern möchtest, MUSS sich auf der obersten Ebene deiner Twig-Datei befinden. Verschachtelte Blöcke sind ungültig, wenn du sie überschreiben möchtest. Sieh dir die Originaldatei an, um den am besten geeigneten Block zum Überschreiben zu finden. In unserem Fall scheint der Block product_item_card_head_inner am besten geeignet zu sein.

Unsere Überschreibungsdatei sieht nun so aus:

Sieh es dir an

Nachdem du die Datei gespeichert hast, solltest du deine Änderungen anzeigen. (Falls nicht, leere den Cache!)

Verschachtelte Blöcke

Beim Überschreiben eines Blocks werden auch alle darin enthaltenen untergeordneten Blöcke ersetzt, sofern du sie nicht erneut aufrufst. Nehmen wir einen äußeren Block product_item_card_head, der einen inneren Block product_item_card_head_inner enthält: Wenn du nur den äußeren Block deklarierst, wird auch der innere Block aus der Ausgabe entfernt.

Es gibt zwei Möglichkeiten, den ursprünglichen Inhalt eines inneren Blocks beizubehalten:

• Überschreibe den innersten Block anstelle seines übergeordneten Blocks, sodass der ursprüngliche Inhalt des äußeren Blocks weiterhin darum herum gerendert wird. Dieses Muster – „so wenig wie möglich überschreiben“ – ist fast immer das, was du möchtest.

• Wenn du den äußeren Block überschreiben musst, rufe darin {{ block('product_item_card_head_inner') }} oder {{ parent() }} auf, um den untergeordneten bzw. den ursprünglichen Inhalt an dieser Stelle zu rendern.

Partials mit hw_include wiederverwenden

Das Erweitern dient dazu, ein vorhandenes Template zu ändern. Um ein Partial inline einzufügen, verwende hw_include. Dabei wird dieselbe Auflösungskette Theme → Modul → Core durchlaufen. Wenn ein Theme eine eigene Version eines Partials bereitstellt, wird diese Version überall verwendet, wo das Partial eingebunden wird.

{% hw_include 'storefront::component/product/card.twig' with { product: product } %}

Beide Tags erfordern die Namespace-Form. Ein einfacher Pfad ohne :: wird vom Template-Resolver abgelehnt.

Fehlerbehebung

Wenn deine Änderungen nicht gerendert werden, prüfe Folgendes:

1. Entspricht dein Template-Pfad dem Pfad im zentralen Template?

2. Hast du das hw_extends-Flag korrekt in die erste Zeile deines Templates eingefügt?

3. Überschreibst du den richtigen Block auf der ersten Ebene deiner Twig-Datei?

4. Hast du den Cache geleert? Über Administration > Settings > Debug kannst du ihn in der Benutzeroberfläche leeren oder php artisan twig:clean über die CLI ausführen.

Wenn dein Überschreibungs-Template gerendert wird, aber Teile des ursprünglichen Templates fehlen, verschluckt ein äußerer Block wahrscheinlich die inneren Blöcke. Überprüfe noch einmal den obigen Abschnitt „Verschachtelte Blöcke“.

Wenn du weitere Probleme hast, kontaktiere uns bitte.