In Magento 2 bzw. Adobe Commerce legen Sie einen CMS-Block mit dem Widget-Code an und platzieren ihn per Widget-Instanz auf allen Produktseiten. Ein eigenes GARAN-Label je Produkt pflegen Sie als Produktattribut, das Sie per CSV-Import füllen.
Der Code für Magento / Adobe Commerce
<div data-garantielabel></div>
<script src="https://www.garantielabel.app/widget.js" async></script>Weitere Optionen wie Darstellung und Sprache stellen Sie im Code-Baukasten ein.
Schritt für Schritt in Magento / Adobe Commerce
- CMS-Block anlegen
Unter Content → Blocks einen neuen Block anlegen und den Widget-Code einfügen. Ab Version 2.4.3 öffnet sich der Page Builder, dort das Element „HTML Code“ nehmen. - Widget anlegen
Unter Content → Elements → Widgets ein Widget vom Typ „CMS Static Block“ für Ihr Theme anlegen. - Platzieren
Als Layout-Update „All Product Types“ wählen und den Container „Product View Extra Hint“ angeben. Er liegt unter dem Warenkorb-Knopf. - Cache leeren
Speichern, Cache leeren und auf einer Produktseite prüfen.
Eigenes GARAN-Label je Produkt: Attribut und CSV-Import
Der CMS-Block zeigt auf allen Produktseiten denselben Inhalt. Das reicht für den Gewährleistungshinweis und für ein GARAN-Label, das für alle Produkte gilt. Braucht jedes Produkt sein eigenes GARAN-Label, legen Sie dessen Adresse in einem Produktattribut ab. Das Theme gibt das Attribut einmal auf der Produktseite aus, danach pflegen Sie nur noch Daten.
- Attribut anlegen
Unter Stores → Attributes → Product über „Add New Attribute“ ein Attribut mit dem Typ „Text Field“, dem Attribute Codegaran_label_urlund dem Scope „Global“ anlegen. Für die geschachtelte Fassung auf Wunsch ein zweites mitgaran_label_nested_url. „Visible on Catalog Pages on Storefront“ bleibt auf „No“, sonst steht die Adresse zusätzlich als Text in den Produktdetails. Danach beide Attribute unter Stores → Attributes → Attribute Set in Ihr Attributset ziehen und speichern. - Labels erstellen
Im Kundenbereich unter „CSV-Upload“ eine Datei mit Marke, Modell und Jahren hochladen, dazu eine Spalteskumit der SKU aus Magento. Die Ergebnisdatei hat die Spaltensku;brand;model;years;label_url;label_nested_url;embed_html, getrennt durch Semikolon. - Importdatei vorbereiten
In der Ergebnisdateiskubehalten,label_urlingaran_label_urlundlabel_nested_urlingaran_label_nested_urlumbenennen, alle anderen Spalten löschen und Zeilen ohne Adresse entfernen. Speichern Sie die Datei als UTF-8 ohne BOM, etwa mit LibreOffice oder einem Texteditor. Die Ergebnisdatei hat eine BOM für Excel, und Dateien mit BOM erkennt Magento laut Adobe nicht zuverlässig. Excel setzt beim Format „CSV UTF-8“ wieder eine BOM. - Importieren
Unter System → Data Transfer → Import als Entity Type „Products“ und als Import Behavior „Add/Update“ wählen, bei „Field separator“ ein Semikolon;eintragen, die Datei wählen, auf „Check Data“ klicken und danach auf „Import“. Magento ordnet jede Zeile über die SKU dem bestehenden Produkt zu. - Einmal ins Theme
Ein Entwickler oder Ihre Agentur legt in Ihrem eigenen Theme die beiden Dateien unten an und leert den Cache. Das ist eine einmalige Änderung. Danach bekommt jedes Produkt sein Label nur über das Attribut, per Import oder von Hand im Produkt.
Die Layout-Datei app/design/frontend/<Vendor>/<theme>/Magento_Catalog/layout/catalog_product_view.xml hängt einen Block unter den Warenkorb-Knopf, in den Container product.info.extrahint. Hat Ihr Theme diese Datei schon, ergänzen Sie dort nur referenceContainer:
<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
<body>
<referenceContainer name="product.info.extrahint">
<block class="Magento\Catalog\Block\Product\View" name="garan.label"
template="Magento_Catalog::product/view/garan-label.phtml" after="-"/>
</referenceContainer>
</body>
</page>Die Vorlage app/design/frontend/<Vendor>/<theme>/Magento_Catalog/templates/product/view/garan-label.phtml gibt nur dann etwas aus, wenn am Produkt eine Adresse eingetragen ist. data-nur="garan" zeigt allein das GARAN-Label, weil der CMS-Block den Gewährleistungshinweis schon zeigt. Ist die geschachtelte Fassung gepflegt, erscheint sie, und ein Klick öffnet das vollständige Label:
<?php
/** @var \Magento\Catalog\Block\Product\View $block */
/** @var \Magento\Framework\Escaper $escaper */
$full = trim((string) $block->getProduct()->getData('garan_label_url'));
$nested = trim((string) $block->getProduct()->getData('garan_label_nested_url'));
if ($full === '') {
return;
}
?>
<div data-garantielabel data-nur="garan"
data-garan-voll="<?= $escaper->escapeUrl($full) ?>"
data-garan-klein="<?= $escaper->escapeUrl($nested) ?>"></div>
<script src="https://www.garantielabel.app/widget.js" async></script>Steht im CMS-Block selbst schon ein GARAN-Label (data-garan-voll), nehmen Sie es dort heraus, sonst erscheinen zwei. Die Layout-Datei je SKU (catalog_product_view_sku_{sku}.xml, weiter unten) lohnt sich nur noch für eine Handvoll Produkte, weil jede Datei eine Änderung am Theme ist.
Konfigurierbare Produkte
Auf der Seite eines konfigurierbaren Produkts gibt die Vorlage das Attribut des Elternprodukts aus. Wählt der Kunde eine Option, bleibt die Seite dieselbe, und das Label wechselt nicht mit. Haben alle Varianten dieselbe Marke, Modellkennung und Garantiedauer, tragen Sie das Label einfach am Elternprodukt ein, also in der Zeile mit dessen SKU. Ein eigenes Label je Variante braucht zusätzliches JavaScript, das bei der Auswahl die Adressen der gewählten Variante einsetzt. Einfacher ist es oft, solche Modelle als eigene Produkte zu führen.
Besonderheiten in Magento / Adobe Commerce
- Bei aktiver Content Security Policy (Modul Magento_Csp) muss
www.garantielabel.appin die Whitelist für Skripte, Bilder und Verbindungen. - JavaScript-Bündelung und -Minifizierung sollten das externe Skript nicht einschließen.
Wo der Hinweis in Magento hingehört
Alle Produktseiten nutzen die Layout-Datei catalog_product_view.xml. Dazu kommen Dateien je Produkttyp, etwa catalog_product_view_type_configurable.xml, und je einzelnem Produkt, etwa catalog_product_view_sku_{sku}.xml. Die Spalte mit Preis und Kaufbereich ist der Container product.info.main. Darin liegt product.info.extrahint, der im Widget-Formular „Product View Extra Hint“ heißt.
Im Admin legen Sie Widgets unter Content → Elements → Widgets an. „Display On“ bestimmt den Seitentyp, „Container“ den Bereich der Seite. Für Produktseiten wählen Sie „All Product Types“ oder einen einzelnen Produkttyp. Für den Hinweis im Seitenfuß fügen Sie ein zweites Layout-Update hinzu: „All Pages“ mit dem Container „Page Footer“, am besten mit data-darstellung="link".
Konfigurierbare Produkte und Modellkennung
Ein konfigurierbares Produkt erscheint als ein Produkt mit Auswahlfeldern. Laut Adobe ist jede Variante ein eigenes einfaches Produkt mit eigener SKU. Das konfigurierbare Produkt selbst ist der Rahmen, sein Preis kommt von den Varianten.
Ein festes Feld für die Modellkennung nennt die Adobe-Dokumentation nicht. Sie legen dafür ein Produktattribut an: unter Stores → Attributes → Product, danach ordnen Sie es unter Stores → Attributes → Attribute Set in Ihr Attributset ein. Mit „Visible on Catalog Pages on Storefront“ auf „Yes“ erscheint es auf der Produktseite. Weil jede Variante ein eigenes Produkt ist, kann sie eine eigene Modellkennung tragen.
Das GARAN-Label nennt Marke und Modellkennung, es gibt also ein Label je Modellkennung. Das Widget zeigt je Platzhalter ein GARAN-Label und wechselt nicht mit der gewählten Option. Für ein Label, das nur zu einem Produkt gehört, nutzen Entwickler die Layout-Datei dieses Produkts (catalog_product_view_sku_{sku}.xml). Haben Varianten verschiedene Modellkennungen, führen Sie diese Modelle besser als eigene Produkte. Für viele Produkte gibt es oben den Weg über ein Produktattribut und den CSV-Import.
Typische Stolpersteine in Magento
- Full Page Cache: Produktseiten liegen fertig im Page Cache. Nach Änderungen frischen Sie unter System → Tools → Cache Management die Typen Page Cache, Layouts und Blocks HTML output auf.
- Widget hängt am Theme: Jede Widget-Instanz gehört zu einem Design Theme. Nach einem Theme-Wechsel legen Sie das Widget für das neue Theme an.
- Store Views: Unter Storefront Properties wählen Sie, in welchen Store Views das Widget erscheint. Bei mehreren Sprachen prüfen Sie jede Store View.
- Eigenes Theme: Eigene Layout-Dateien gehören in ein eigenes Theme. Adobe rät, die mitgelieferten Themes nicht zu verändern, wegen Kompatibilität und Updates.
Weitere Quellen
- Adobe Commerce: Product layouts (englisch)
- Adobe Commerce: Create a widget (englisch)
- Adobe Commerce: Block positions (englisch)
- Adobe Commerce: Configurable product (englisch)
- Adobe Commerce: Create product attributes (englisch)
- Adobe Commerce: Cache management (englisch)
- Adobe Commerce: Create a storefront theme (englisch)
- Magento Open Source: Optionen für „Display On“ (GitHub)
Gewährleistungslabel in der Bestellbestätigung
Laut Leitlinien der Kommission soll der Hinweis auch in der Bestätigungs-E-Mail stehen. E-Mail-Vorlagen pflegen Sie unter Marketing → Email Templates. In der Vorlage „New Order“ lässt sich die amtliche Grafik als Bild ergänzen. Ein bloßer Link reicht als dauerhafter Datenträger voraussichtlich nicht (EuGH, Rs. C-49/11); am sichersten steht der Hinweis als Bild, Text oder Anhang direkt in der Mail. Die amtlichen Dateien finden Sie im Download.
Herstellergarantie? Dann gehört das GARAN-Label dazu
Gibt der Hersteller eine kostenlose Haltbarkeitsgarantie von mehr als zwei Jahren auf die ganze Ware, gehört zusätzlich das GARAN-Label auf die Produktseite. Mit dem GARAN-Label-Generator erstellen Sie es in Sekunden aus Jahren, Marke und Modell, die ersten drei kostenlos und ohne Anmeldung. Unter jedem fertigen Label steht ein Einbett-Code mit dauerhaften Bild-Adressen: Sie laden nichts hoch und setzen ihn wie oben in Magento / Adobe Commerce ein.
Lieber eigene Dateien? Dann laden Sie die vollständige und die geschachtelte Fassung in die Medienverwaltung von Magento / Adobe Commerce und tragen die Adressen im Widget-Code ein:
<div data-garantielabel
data-garan-voll="https://…/GARAN-MX-500.svg"
data-garan-klein="https://…/GARAN-MX-500-geschachtelt.svg"></div>Das Widget zeigt dann die geschachtelte Fassung unter dem Gewährleistungslabel, ein Klick öffnet das vollständige GARAN-Label.
Häufige Fragen
Geht das auch per Layout-XML?
Ja. Entwickler binden den Block per Layout-XML in catalog_product_view.xml ein.
Wie bekommen viele Produkte ihr eigenes GARAN-Label?
Über ein Produktattribut wie garan_label_url, das Sie unter System → Data Transfer → Import aus der Ergebnisdatei des CSV-Uploads füllen. Das Theme gibt das Attribut einmal aus, danach ist alles Datenpflege.
Funktioniert das mit Hyvä?
Ja. Das Widget hängt nicht an RequireJS oder Knockout und läuft auch in Hyvä-Themes.
Muss ich den Cache leeren?
Ja, nach dem Anlegen des Widgets, sonst erscheint der Block erst später.
Kann ich ein GARAN-Label nur für ein Produkt einbinden?
Ja. Für viele Produkte am einfachsten über ein Produktattribut und den CSV-Import, beschrieben oben unter „Eigenes GARAN-Label je Produkt“. Für eine Handvoll Produkte geht auch die Layout-Datei catalog_product_view_sku_{sku}.xml, sie gilt nur für das Produkt mit dieser SKU.
Erscheint das Widget in allen Store Views?
Nur in denen, die Sie in den Storefront Properties der Widget-Instanz auswählen.
Was ist bei einem Theme-Wechsel zu tun?
Widget-Instanzen gehören zu einem Design Theme. Legen Sie das Widget für das neue Theme an, frischen Sie den Cache auf und prüfen Sie eine Produktseite.