Product Highlights¶

Extension for Magento 2¶

Bedienungsanleitung¶

CopeX GmbH
Web: https://copex.io
Email: office@copex.io

Inhaltsverzeichnis¶

Abschnitt	Seite
1 Voraussetzungen	2
2 Installation	2
3 Highlights auf der Kategorie pflegen	3
4 Vererbung entlang des Kategoriebaums	5
5 Icons	6
6 Store Views	7
7 Ausgabe im Theme	7
8 Zwischenspeicher	8
9 Fehlerbehandlung	9
10 Lizenz	10

1 Voraussetzungen¶

Magento 2.4.7 bis 2.4.9
PHP 8.1 bis 8.5
Luma- oder Hyvä-Theme
Keine weiteren Module erforderlich

2 Installation¶

composer require copex/module-producthighlights
php bin/magento module:enable CopeX_ProductHighlights
php bin/magento setup:upgrade
php bin/magento cache:flush

setup:upgrade legt das Kategorie-Attribut highlight_attributes an. Danach steht im Kategorieformular der Abschnitt Product Highlights zur Verfügung.

Zum Entfernen des Moduls:

php bin/magento module:disable CopeX_ProductHighlights

Das Attribut und die gepflegten Werte bleiben dabei erhalten. Soll beides mit entfernt werden, wird das Modul deinstalliert. Dabei läuft der Data Patch zurück und löscht das Attribut:

php bin/magento module:uninstall CopeX_ProductHighlights

3 Highlights auf der Kategorie pflegen¶

Die Pflege erfolgt im Magento-Backend unter Katalog → Kategorien. Nach Auswahl einer Kategorie öffnet sich der Abschnitt Product Highlights.

Jede Zeile beschreibt ein Highlight:

Feld	Bedeutung
Attribut	Das Produktattribut, dessen Wert angezeigt wird. Die Liste enthält alle Produktattribute mit Bezeichnung.
Icon	Ein Symbol, das vor dem Wert steht. Optional.
Icon-Alternativtext	Der Alternativtext des Icons. Bleibt er leer, wird die Bezeichnung des Attributs verwendet.

Über Highlight hinzufügen entsteht eine weitere Zeile, über das Papierkorb-Symbol wird eine Zeile entfernt.

Reihenfolge¶

Die Reihenfolge der Zeilen ist die Reihenfolge der Ausgabe. Sie wird per Drag-and-drop am Anfasser links geändert und beim Speichern übernommen.

Was auf der Produktseite erscheint¶

Angezeigt wird die Bezeichnung des Attributs und der Wert des jeweiligen Produkts. Führt ein Attribut bei einem Produkt keinen Wert, entfällt die Zeile für dieses Produkt. Bei Auswahllisten wird der Text der gewählten Option ausgegeben, bei Mehrfachauswahl alle gewählten Optionen durch Komma getrennt.

4 Vererbung entlang des Kategoriebaums¶

Ein Produkt übernimmt die Konfiguration der Kategorie, in der es liegt. Hat diese Kategorie keine eigene Konfiguration, wird die der Oberkategorie verwendet, und so weiter bis zur Wurzel.

Sobald eine Kategorie eine eigene Konfiguration besitzt, gilt ausschließlich diese. Die Konfiguration der Oberkategorie wird dann nicht ergänzt, sondern vollständig ersetzt.

Ein Beispiel:

Kategorie	Konfiguration	Ergebnis für Produkte dieser Kategorie
Tresore	Feuerschutz, Schlossart	Feuerschutz, Schlossart
Tresore → Wertschutzschränke	keine	Feuerschutz, Schlossart (geerbt)
Tresore → Möbeltresore	Gewicht	nur Gewicht

Liegt ein Produkt in mehreren Kategorien, wird die tiefste Kategorie des aktuellen Store-Baums herangezogen. Kommt der Besucher über eine Kategorieseite auf das Produkt, gilt diese Kategorie.

5 Icons¶

Erlaubt sind SVG und PNG, maximal 1 MB je Datei. Der Dateidialog bietet von vornherein nur diese beiden Typen an.

Neben der Schaltfläche zum Hochladen steht eine zweite, Auswählen. Dahinter liegt eine Liste der bereits abgelegten Icons, sodass dieselbe Datei nicht für jede Kategorie erneut hochgeladen werden muss. Die Liste wird bei jedem Öffnen frisch gelesen, ein Icon aus einer anderen Zeile steht also sofort zur Verfügung. Angezeigt werden nur SVG- und PNG-Dateien.

Die Liste klappt unterhalb der Schaltflächen auf, die Zeile wird dabei höher. Sie überlagert die Tabelle nicht, deshalb bleibt sie auch in schmalen Spalten vollständig sichtbar.

Hochgeladene Icons landen unter pub/media/catalog/category/highlight_icons. Der Upload prüft vor dem Schreiben der Datei:

die Dateiendung,
den MIME-Typ,
bei SVG zusätzlich das Markup.

SVG-Dateien mit Skripten, Ereignisattributen, eingebetteten Fremdinhalten oder externen Verweisen werden abgelehnt. Magento selbst prüft SVG-Markup nicht, deshalb bringt das Modul diese Prüfung mit.

Wird eine Zeile gelöscht, bleibt die Icon-Datei erhalten. Sie kann in anderen Kategorien oder Store Views weiter verwendet werden. Nicht mehr benötigte Dateien werden im Medienverzeichnis entfernt.

6 Store Views¶

Das Attribut hat Store-Scope. Eine Kategorie kann je Store View eine eigene Zusammenstellung führen, etwa mit anderen Attributen für einen fremdsprachigen Shop.

Ohne eigenen Wert im Store View gilt der Wert der Standardansicht.

7 Ausgabe im Theme¶

Der Block heißt copex.product.highlights. Unter Luma sitzt er in product.info.main zwischen der SKU-Zeile und dem Bestellformular.

Unter Hyvä gibt das Template der Produktangaben nur Kindblöcke aus, die es namentlich kennt. Ein fremder Block wird nie abgefragt und rutscht deshalb an das Ende der Seite, unterhalb des Bewertungsformulars. Das Modul verschiebt ihn darum in den Container alert.urls. Das ist die früheste Stelle, die das Standard-Theme noch ausgibt: unter dem Lagerstatus und oberhalb der Attributtabelle. Diese Stelle teilt sich eine Flex-Zeile mit dem Lagerstatus, auf breiten Bildschirmen stehen die Highlights daher neben dem Lagerstatus statt über die volle Breite.

Zwischen den Sternen und der Kurzbeschreibung gibt es keinen Platzhalter, die Kurzbeschreibung steht fest im Template. Wer die Highlights dort haben möchte, legt im Theme einen eigenen Container an und verschiebt den Block ein zweites Mal. Der letzte Verschiebebefehl gewinnt:

<referenceBlock name="product.info">
    <container name="product.info.short_description.before"/>
</referenceBlock>
<move element="copex.product.highlights" destination="product.info.short_description.before"/>

Das Modul nennt nur Container aus dem Standard-Theme. Ein eigenes Theme überschreibt die Platzierung jederzeit.

Hyvä und Tailwind¶

Das Modul meldet sich beim Tailwind-Lauf von Hyvä an. Die Klassen des Hyvä-Templates landen dadurch auch dann im kompilierten CSS, wenn das Modul unter vendor/ liegt. Nach der Installation wird das Theme einmal neu gebaut:

cd app/design/frontend/<Anbieter>/<Theme>/web/tailwind
npm run build

Eigenes Markup entsteht durch Austausch des Templates im Theme:

<referenceBlock name="copex.product.highlights"
                template="Mein_Theme::product/view/highlights.phtml"/>

Das ViewModel liefert je Highlight label, value, icon_url und alt.

8 Zwischenspeicher¶

Die aufgelöste Konfiguration wird je Kategorie und Store View zwischengespeichert. Der Eintrag ist mit jeder Kategorie des Pfads verknüpft, eine Änderung an einer Oberkategorie verwirft daher auch die Einträge ihrer Unterkategorien.

Beim Speichern einer Kategorie geschieht das automatisch. Der Eintrag gehört zum Cache-Typ "Collections Data", er wird also auch von der Cache-Verwaltung im Admin und von cache:flush erfasst. Nach einem Import oder einer direkten Änderung in der Datenbank hilft:

php bin/magento cache:clean

9 Fehlerbehandlung¶

Meldung	Ursache	Abhilfe
Als Highlight-Icon sind nur SVG- und PNG-Dateien erlaubt.	Die Datei hat eine andere Endung oder einen anderen MIME-Typ.	Datei als SVG oder PNG speichern und erneut hochladen.
Die SVG-Datei enthält Skripte oder externe Verweise und wurde abgelehnt.	Das SVG enthält aktive Inhalte.	SVG im Grafikprogramm ohne Skripte exportieren, etwa als "einfaches SVG".
Das Icon konnte nicht gespeichert werden.	Das Medienverzeichnis ist nicht beschreibbar oder die Datei ist leer.	Schreibrechte auf `pub/media` prüfen.

Erscheinen auf der Produktseite keine Highlights, sind die häufigsten Ursachen:

Das Produkt führt bei keinem der gewählten Attribute einen Wert.
Die Konfiguration wurde in einem anderen Store View gepflegt.
Der Zwischenspeicher ist noch nicht verworfen, siehe Abschnitt 8.

Verarbeitungsfehler werden nach var/log/system.log geschrieben und führen nie zu einem Abbruch der Produktseite. Im Zweifel bleibt der Bereich leer.

10 Lizenz¶

Proprietäre Software der CopeX GmbH. Die Nutzung setzt eine gültige Lizenzvereinbarung voraus.

CopeX GmbH
Web: https://copex.io
Email: office@copex.io