Product Features - Installation, Konfiguration und Attributverwaltung

Dieses Dokument beschreibt die Konfiguration des Moduls kowal/module-product-features, die Bedeutung aller administrativen Felder sowie die Arbeit mit Attributen auf Produktebene.

Installation

Das Modul ist für die Installation über Composer vorgesehen.

Die Zugangsdaten zum Composer-Repository, E-Mail-Adresse des Kunden und Lizenz-Token, erhalten Sie nach dem Kauf per E-Mail. Sie sind außerdem im Kundenbereich nach dem Login unter kowal.store verfügbar. Ersetzen Sie TWOJ_EMAIL_KLIENTA durch die E-Mail-Adresse Ihres Kontos und TWOJ_TOKEN durch den erhaltenen Token. Führen Sie die Befehle im Magento-Hauptverzeichnis aus.

composer config repositories.kowal composer https://repo.kowal.storecomposer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'composer require kowal/module-product-featuresbin/magento module:enable Kowal_ProductFeaturesbin/magento setup:upgradebin/magento cache:flush

Nach dem produktiven Deployment müssen die für das Projekt üblichen Standardbefehle ausgeführt werden, z. B. DI-Kompilierung und Deployment statischer Assets, entsprechend dem Betriebsmodus von Magento.

Speicherort der Konfiguration

Die Modulkonfiguration befindet sich im Magento-Admin-Panel:

Stores > Configuration > Catalog > Product Features

Die Darstellungseinstellungen befinden sich in einer separaten Gruppe:

Stores > Configuration > Catalog > Product Features Appearance

Die Konfigurationsfelder sind auf den Ebenen Default, Website und Store View verfügbar. Dadurch können verschiedene Store Views andere Merkmalsabschnitte oder ein anderes Erscheinungsbild haben.

Product Features

Enabled

Aktiviert oder deaktiviert das Modul für den jeweiligen Konfigurationsbereich.

Werte:

• Yes - Produktmerkmalsabschnitte werden auf der Produktseite gerendert,
• No - das Modul gibt keine Abschnitte zurück und der Block erscheint nicht im Frontend.

Anwendung: schnelles Deaktivieren des Moduls für den gesamten Shop, eine ausgewählte Website oder Store View, ohne die Abschnittskonfiguration zu löschen.

Feature Sections

Liste der auf der Produktseite gerenderten Abschnitte. Jede Zeile definiert einen Frontend-Abschnitt oder eine Gruppe von Abschnitten, wenn der Typ cms_blocks verwendet wird.

Enabled

Aktiviert oder deaktiviert einen einzelnen Abschnitt.

Werte:

• Yes - der Abschnitt wird beim Rendern berücksichtigt,
• No - der Abschnitt wird übersprungen.

Anwendung: temporäres Ausblenden eines Abschnitts, ohne seine Einstellungen zu löschen.

Section Title

Titel des Abschnitts, der auf der Produktseite sichtbar ist.

Beispiele:

• Cechy produktu,
• Zastosowanie Sportowe,
• Specyfikacja,
• Technologie,
• Dostawa.

Anwendung: Der Name sollte für Kunden verständlich sein und muss nicht dem technischen Namen des Attributs entsprechen.

Hinweis: Für den Typ cms_blocks wird der Titel des untergeordneten Abschnitts aus dem Titel des CMS-Blocks übernommen.

Attribute Code

Ein einzelnes Produktattribut, das vom Abschnitt verwendet wird. Das Feld hat die Form eines Dropdowns mit einer Liste von Produktattributen.

Anwendung: Verwenden Sie dieses Feld, wenn der Abschnitt auf einem einzelnen Attribut basiert, z. B. sport_usage, blocks_id, material, technology_icon.

Attribute Codes

Liste mehrerer Produktattribute, die von einem Abschnitt verwendet werden. Das Feld hat die Form eines Multiselects.

Anwendung: Verwenden Sie dieses Feld, wenn ein Abschnitt mehrere Merkmale aggregieren soll, z. B. mehrere Skalen im Abschnitt Cechy produktu oder mehrere Parameter im Abschnitt Specyfikacja.

Beispiel: Der Abschnitt Cechy produktu kann die Attribute fit, resistance, stretch und breathability enthalten, die alle als Skalen gerendert werden.

Display Type

Bestimmt die Art der Darstellung des Attributwerts.

Ein leerer Wert Auto bedeutet automatische Auswahl des Renderers:

• blocks_id wird als cms_blocks gerendert,
• Swatch-Multiselect als swatch_list,
• Select mit 2 oder 3 Optionen als scale,
• Select mit einer größeren Anzahl von Optionen als selected_label,
• Multiselect als text_list,
• Boolean als checkmark,
• Date als date,
• Price als price,
• Textarea als text_block,
• image/media_image als image,
• sonstige Typen als text_inline.

Verfügbare Typen:

Im Admin-Panel ist ein Teil der Einträge als available in future release markiert. Dies betrifft Typen, die bereits in der Konfigurationsliste sichtbar sind, aber noch keine eigene, endgültige Frontend-Darstellung haben:

• table,
• badge,
• badge_list,
• icon_value,
• icon_list,
• swatch_grid.

Sort Order

Reihenfolge der Abschnitte auf der Produktseite. Eine niedrigere Zahl bedeutet eine frühere Anzeige.

Anwendung: Platzieren Sie die wichtigsten Abschnitte am Anfang, z. B. 10 für Hauptmerkmale, 20 für Einsatzbereiche, 30 für Spezifikationen.

Default State

Anfangszustand des Abschnitts auf der Produktseite.

Werte:

• Expanded - der Abschnitt ist standardmäßig ausgeklappt,
• Collapsed - der Abschnitt ist standardmäßig eingeklappt.

Anwendung: Die wichtigsten Inhalte können sofort angezeigt werden, während längere Zusatzinformationen eingeklappt bleiben.

Hide Empty

Entscheidet, ob der Abschnitt ausgeblendet werden soll, wenn keine Daten zur Anzeige vorhanden sind.

Werte:

• Yes - der Abschnitt wird ausgeblendet, wenn das Produkt keinen Attributwert hat oder der Renderer keine Elemente zurückgibt,
• No - der Abschnitt kann auch ohne Elemente sichtbar bleiben.

Anwendung: Meist wird Yes empfohlen, damit Kunden keine leeren Abschnitte sehen.

Appearance Profile

Auswahl eines Darstellungsprofils, das im Feld Appearance Profiles definiert wurde.

Das Feld hat die Form eines Dropdowns. Der Administrator gibt den Code nicht mehr manuell ein, sondern wählt ein fertiges Profil aus der Liste, in der Regel im Format code - label.

Anwendung: Ermöglicht es, einem konkreten Abschnitt ein anderes Erscheinungsbild als das globale zuzuweisen, z. B. das Profil compact, highlight oder plain.

Wenn das Feld leer ist und die Option Use global appearance ausgewählt ist, verwendet der Abschnitt die globale Darstellung.

Empfohlene Arbeitsreihenfolge:

1. Definieren Sie das Profil in Appearance Profiles,
2. speichern Sie die Konfiguration,
3. kehren Sie zu Feature Sections zurück,
4. wählen Sie das Profil in der Spalte Appearance Profile für den entsprechenden Abschnitt.

CSS Class

Zusätzliche CSS-Klasse, die dem Abschnitt hinzugefügt wird.

Anwendung: individuelle Anpassung des Erscheinungsbilds im Frontend-Theme, z. B. product-features-section--technical.

Renderer Options JSON

Optionale Einstellungen, die im JSON-Format an den Renderer übergeben werden.

Die Anwendung hängt vom Präsentationstyp ab. Beispiele:

{'unit':'cm','precision':1}

Für number_with_unit:

• unit - Einheit, z. B. cm, %, g/m2,
• precision - Anzahl der Nachkommastellen.

Für range_bar:

• min - minimaler Bereichswert,
• max - maximaler Bereichswert,
• low_label - Label für den Bereichsanfang,
• high_label - Label für das Bereichsende.

Für rating_dots:

• steps - Anzahl der Punkte oder Stufen.

Der Typ radial_chart erfordert keine zusätzlichen Optionen. Der Renderer liest den Attributwert oder das Optionslabel im Format x/y, z. B. 1/6, 4/6, 7/10.

Beispiel für einen Bereichsbalken:

{'min':0,'max':100,'low_label':'Niska','high_label':'Wysoka'}

Beispiel für Punkte:

{'steps':5}

Hinweis: Das Feld muss gültiges JSON enthalten. Ein ungültiger Wert wird vom Renderer ignoriert.

Appearance Profiles

Liste optionaler Darstellungsprofile, die über das Feld Appearance Profile Abschnitten zugewiesen werden können.

Code

Technischer Code des Profils.

Beispiele:

• compact,
• highlight,
• plain.

Anwendung: Der Code identifiziert das Profil intern und wird als Optionswert im Dropdown Appearance Profile beim Abschnitt verwendet.

Label

Beschreibender Profilname, der für den Administrator sichtbar ist.

Anwendung: Erleichtert das Erkennen des Profils in der Konfiguration, z. B. Kompaktowy, Wyróżniony, Neutralny. Zusammen mit dem Code bildet er ein verständliches Label in der Profilauswahlliste in Feature Sections.

Background

Hintergrundfarbe des Abschnitts für das Profil.

Anwendung: Hervorhebung ausgewählter Abschnitte oder Anpassung an das Theme.

Text

Farbe des Grundtexts im Abschnitt.

Heading

Farbe des Abschnittstitels.

Accent

Akzentfarbe, z. B. für aktive Elemente, Skalenpunkte oder Hervorhebungen.

Accent Background

Hintergrundfarbe von Akzentelementen.

Border

Farbe von Linien, Trennzeichen, Skalenachsen und Rahmen.

Icon

Farbe des Icons zum Ein- und Ausklappen des Abschnitts.

Radius, e.g. 18px

Abrundung der Abschnittsecken.

Beispiele: 0, 8px, 18px.

Padding, e.g. 28px

Innenabstand des Abschnitts.

Beispiele: 16px, 24px, 28px.

Label Font Size, e.g. 21px

Textgröße der Merkmalslabels im Abschnitt.

Beispiele: 16px, 18px, 21px, 1.25rem.

Product Features Appearance

Diese Gruppe enthält das globale Erscheinungsbild der Abschnitte. Die Einstellungen werden in CSS-Variablen umgewandelt und auf den Wrapper des Moduls angewendet.

Section Background Color

Hintergrundfarbe des Abschnitts.

Standard: #f4f4f4.

Section Text Color

Grundfarbe des Textes im Abschnitt.

Standard: #000000.

Section Heading Color

Farbe der Abschnittsüberschrift.

Standard: #000000.

Muted Text Color

Farbe von Hilfstexten und weniger wichtigen Texten.

Standard: #555555.

Accent Color

Farbe aktiver Elemente und Hervorhebungen.

Standard: #000000.

Accent Background Color

Hintergrundfarbe aktiver Elemente, z. B. Markierungen.

Standard: #ffffff.

Border Color

Farbe von Rahmen, Trennzeichen und Skalenachsen.

Standard: #9b9b9b.

Icon Color

Farbe des Icons + / - in der Abschnittsüberschrift.

Standard: #000000.

Selected Text Color

Textfarbe des ausgewählten Werts.

Standard: #000000.

Selected Font Weight

Schriftstärke des ausgewählten Werts.

Standard: 700.

Beispiele: 400, 500, 600, 700, bold.

Section Border Radius

Abrundung des Abschnittscontainers.

Standard: 18px.

Section Padding

Innenabstand des Abschnitts.

Standard: 28px.

Section Gap

Abstand zwischen Abschnitten.

Standard: 16px.

Heading Font Size

Schriftgröße der Abschnittsüberschrift.

Standard: 20px.

Beispiele: 18px, 20px, 1.25rem, clamp(18px, 2vw, 22px).

Label Font Size

Schriftgröße von Merkmalslabels und Wertlabels.

Standard: 21px.

Body Font Size

Schriftgröße des Hauptinhalts des Abschnitts.

Standard: 16px.

Attributverwaltung auf Produktebene

Das Modul erstellt kein separates Produktdatensystem. Es verwendet Magento-Produktattribute, daher erfolgt die Inhaltsverwaltung hauptsächlich in der Produktbearbeitung.

Bearbeitung eines einzelnen Produkts

1. Gehen Sie zu Catalog > Products.
2. Öffnen Sie das Produkt zur Bearbeitung.
3. Füllen Sie die Attribute aus, die von den Modulabschnitten verwendet werden.
4. Wenn das Produkt CMS-Blöcke verwenden soll, gehen Sie zur Gruppe Product Features und setzen Sie das Feld CMS Blocks.
5. Speichern Sie das Produkt.
6. Leeren Sie den Cache, wenn das Projekt dies erfordert.

Der Abschnitt erscheint im Frontend nur dann, wenn:

• das Modul aktiviert ist,
• der Abschnitt in der Konfiguration aktiviert ist,
• das Attribut existiert,
• das Produkt einen Attributwert hat,
• der Renderer den ausgewählten Wert verarbeiten kann,
• der Abschnitt nicht durch Hide Empty ausgeblendet wurde.

Attribut blocks_id / CMS Blocks

Während setup:upgrade fügt das Modul ein Produktattribut hinzu:

• Code: blocks_id,
• Label: CMS Blocks,
• Typ: text,
• Input: multiselect,
• Source Model: aktive CMS-Blöcke,
• Backend: standardmäßiges Magento-Backend für Multiselect,
• Scope: Store View,
• Gruppe: Product Features,
• sichtbar in der Produktbearbeitung,
• verfügbar im Produktgrid und in der Grid-Filterung.

Das Feld CMS Blocks ermöglicht es, einem Produkt aktive CMS-Blöcke zuzuweisen. Jeder ausgewählte Block wird als separater Abschnitt gerendert, wenn in der Modulkonfiguration ein Abschnitt existiert mit:

• Attribute Code: blocks_id,
• Display Type: cms_blocks.

Der Abschnittstitel im Frontend stammt aus dem Titel des CMS-Blocks, der Inhalt aus dem Blockinhalt. Inaktive oder für den Store View nicht verfügbare Blöcke werden nicht gerendert.

Verwaltung von CMS-Blöcken

Blöcke, die von blocks_id verwendet werden, werden standardmäßig in Magento erstellt:

Content > Elements > Blocks

Empfehlungen:

• verwenden Sie klare Blocktitel, da sie als Abschnittstitel sichtbar sein können,
• weisen Sie Blöcke den richtigen Store Views zu,
• setzen Sie den Block auf aktiv,
• speichern Sie in Blöcken beschreibende Inhalte, die von vielen Produkten gemeinsam genutzt werden sollen, z. B. Lieferung, Rückgaben, Anleitungen, Technologien.

Massenbearbeitung von Produkten

Das Attribut blocks_id ist für die Arbeit mit der Massenbearbeitung von Produkten vorbereitet.

1. Gehen Sie zu Catalog > Products.
2. Markieren Sie Produkte im Grid.
3. Wählen Sie die Aktion Update Attributes.
4. Setzen Sie den Wert des Feldes CMS Blocks.
5. Speichern Sie die Änderungen.

Anwendung: schnelle Zuweisung desselben CMS-Abschnitts, z. B. Dostawa, Zwroty oder Instrukcja pielęgnacji, zu vielen Produkten gleichzeitig.

Attribute für Skalen

Verwenden Sie für den Typ scale select-Attribute mit 2 oder 3 aktiven Optionen.

Beispiel:

• Attribut fit,
• Optionen: Luźny, Regularny, Dopasowany.

Das Produkt sollte eine der Optionen ausgewählt haben. Das Modul zeigt alle Skalenoptionen an und hebt die dem Produkt zugewiesene hervor.

Wenn das Attribut weniger als 2 oder mehr als 3 Optionen hat, überspringt der Renderer scale dieses Attribut.

Multiselect-Attribute

Verwenden Sie für Listen von Merkmalen, Einsatzbereichen, Technologien oder Zertifikaten multiselect-Attribute.

Mögliche Präsentationstypen:

• text_list,
• badge_list,
• swatch_list,
• swatch_grid,
• multiselect_icon,
• icon_list.

Das Produkt kann mehrere Werte ausgewählt haben. Das Modul rendert nur die dem Produkt zugewiesenen Werte.

Magento-Swatches

Wenn ein Multiselect-Attribut Magento-Swatches verwendet, kann der Typ swatch_list oder swatch_grid genutzt werden.

Anwendung:

• Technologie-Icons,
• Farben,
• Piktogramme für Einsatzbereiche,
• Materialkennzeichnungen.

Wenn eine Option einen Bild-Swatch hat, zeigt das Modul das Bild an. Wenn sie einen Farb- oder Text-Swatch hat, verwendet das Modul die entsprechende Variante.

Amasty-Icons

Für den Typ multiselect_icon versucht das Modul, das Optionsicon aus Amasty ShopbyBrand / ShopbyBase abzurufen.

Icon-Quelle:

Shop by Brand > Option Edit > Other > Small Image

Der Alternativtext stammt aus Small Image Alt, und wenn dieser fehlt, aus dem Optionslabel.

Wenn Amasty nicht installiert ist oder die Option kein Icon hat, zeigt das Modul nur das Label an.

Text- und HTML-Attribute

Verwenden Sie für kurze Informationen text_inline, key_value oder badge.

Verwenden Sie für längere Beschreibungen text_block, accordion_text oder html_block.

Hinweis: html_block und accordion_text rendern HTML und sollten daher ausschließlich für vertrauenswürdige administrative Inhalte verwendet werden.

Numerische Attribute

Für Zahlenwerte können verwendet werden:

• number_with_unit - wenn die Zahl eine Einheit benötigt,
• range_bar - wenn der Wert als Fortschritt innerhalb eines Bereichs angezeigt werden soll,
• rating_dots - wenn der Wert eine Stufe oder Bewertung beschreibt.

Beispiel für Renderer Options JSON für eine Zahl mit Einheit:

{'unit':'%','precision':0}

Boolean-Attribute

Verwenden Sie für Ja/Nein-Attribute:

• yes_no, wenn der Kunde sowohl Yes als auch No sehen soll,
• checkmark, wenn das Merkmal nur sichtbar sein soll, wenn das Produkt es besitzt.

Bildattribute

Für Bildattribute können verwendet werden:

• image,
• image_with_label,
• image_grid.

Das Modul erstellt die Bildadresse auf Grundlage des Medienverzeichnisses des Magento-Produkts und verwendet das Attributlabel als Alternativtext.

Beispielkonfiguration

Abschnitt mit mehreren Skalen:

Abschnitt für Einsatzbereiche mit Icons:

CMS-Abschnitte:

Diagnose

Wenn ein Abschnitt im Frontend nicht erscheint, prüfen Sie:

• ob Enabled des Moduls den Wert Yes hat,
• ob der jeweilige Abschnitt Enabled = Yes hat,
• ob das Produkt das Attribut ausgefüllt hat,
• ob der richtige Attribute Code oder die richtigen Attribute Codes ausgewählt wurden,
• ob Display Type zum Attributtyp passt,
• ob Hide Empty den leeren Abschnitt nicht ausblendet,
• ob das Attribut für den jeweiligen Store View verfügbar ist,
• ob der CMS-Block aktiv und dem richtigen Store View zugewiesen ist,
• ob der Magento-Cache aktualisiert wurde.