Product Features - Installation, Konfiguration und Attributverwaltung

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

Installation

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

composer config repositories.module.product.features vcs https://github.com/kowalco/product-featurescomposer config --global --auth github-oauth.github.com composer require kowal/module-product-featuresbin/magento module:enable Kowal_ProductFeaturesbin/magento setup:upgradebin/magento cache:flush

Nach dem Produktiv-Deployment sollten die für das Projekt üblichen Standardbefehle ausgeführt werden, z. B. DI-Kompilierung und Deploy statischer Assets, entsprechend dem Magento-Betriebsmodus.

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 unterschiedliche Eigenschaftsbereiche oder ein anderes Erscheinungsbild haben.

Product Features

Enabled

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

Werte:

• Yes - die Produkt-Eigenschaftsbereiche werden auf der Produktdetailseite gerendert,
• No - das Modul gibt keine Bereiche zurück und der Block erscheint nicht im Frontend.

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

Feature Sections

Liste der Bereiche, die auf der Produktdetailseite gerendert werden. Jede Zeile definiert einen Frontend-Bereich oder eine Gruppe von Bereichen, wenn der Typ cms_blocks verwendet wird.

Enabled

Aktiviert oder deaktiviert einen einzelnen Bereich.

Werte:

• Yes - der Bereich wird gerendert,
• No - der Bereich wird übersprungen.

Einsatz: temporäres Ausblenden eines einzelnen Bereichs, ohne seine Einstellungen zu löschen.

Section Title

Titel des Bereichs, der auf der Produktdetailseite sichtbar ist.

Beispiele:

• Produkteigenschaften,
• Sportliche Anwendung,
• Spezifikation,
• Technologien,
• Lieferung.

Einsatz: Die Bezeichnung sollte für den Kunden verständlich sein und muss nicht dem technischen Attributnamen entsprechen.

Hinweis: Beim Typ cms_blocks wird der Titel des untergeordneten Bereichs aus dem Titel des CMS-Blocks übernommen.

Attribute Code

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

Einsatz: Verwenden Sie dieses Feld, wenn der Bereich auf einem Attribut basiert, z. B. sport_usage, blocks_id, material, technology_icon.

Attribute Codes

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

Einsatz: Verwenden Sie dieses Feld, wenn ein Bereich mehrere Eigenschaften zusammenfassen soll, z. B. mehrere Skalen im Bereich Produkteigenschaften oder mehrere Parameter im Bereich Spezifikation.

Beispiel: Der Bereich Produkteigenschaften kann die Attribute fit, resistance, stretch und breathability enthalten, die alle als Skalen gerendert werden.

Display Type

Bestimmt die Art der Darstellung des Attributwerts.

Der leere Wert Auto bedeutet automatische Renderer-Auswahl:

• blocks_id wird als cms_blocks gerendert,
• Swatch-Multiselect als swatch_list,
• select mit 2 oder 3 Optionen als scale,
• select mit mehr 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,
• alle übrigen Typen als text_inline.

Verfügbare Typen:

Im Admin-Panel sind einige Positionen als available in future release gekennzeichnet. Das 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 Bereiche auf der Produktdetailseite. Eine niedrigere Zahl bedeutet frühere Anzeige.

Einsatz: Platzieren Sie die wichtigsten Bereiche am Anfang, z. B. 10 für Haupteigenschaften, 20 für Anwendungen, 30 für Spezifikationen.

Default State

Anfangszustand des Bereichs auf der Produktdetailseite.

Werte:

• Expanded - der Bereich ist standardmäßig aufgeklappt,
• Collapsed - der Bereich ist standardmäßig eingeklappt.

Einsatz: Die wichtigsten Inhalte können sofort gezeigt werden, während längere unterstützende Informationen eingeklappt bleiben.

Hide Empty

Legt fest, ob der Bereich ausgeblendet werden soll, wenn keine Daten zur Anzeige vorhanden sind.

Werte:

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

Einsatz: In den meisten Fällen wird Yes empfohlen, damit dem Kunden keine leeren Bereiche angezeigt werden.

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.

Einsatz: Ermöglicht es, einem bestimmten Bereich ein anderes Erscheinungsbild als das globale zu geben, z. B. das Profil compact, highlight oder plain.

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

Empfohlene Arbeitsreihenfolge:

1. Definieren Sie ein 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 Bereich aus.

CSS Class

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

Einsatz: 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.

Der Einsatz hängt vom Darstellungstyp 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 - Mindestwert des Bereichs,
• max - Höchstwert des Bereichs,
• low_label - Beschriftung des Bereichsanfangs,
• high_label - Beschriftung des Bereichsendes.

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':'Niedrig','high_label':'Hoch'}

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 Bereichen über das Feld Appearance Profile zugewiesen werden können.

Code

Technischer Code des Profils.

Beispiele:

• compact,
• highlight,
• plain.

Einsatz: Der Code identifiziert das Profil intern und wird als Optionswert im Dropdown Appearance Profile am Bereich verwendet.

Label

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

Einsatz: Erleichtert die Erkennung des Profils in der Konfiguration, z. B. Kompakt, Hervorgehoben, Neutral. In Kombination mit dem Code entsteht ein gut lesbares Label in der Profilauswahlliste in Feature Sections.

Background

Hintergrundfarbe des Bereichs für das Profil.

Einsatz: Hervorhebung ausgewählter Bereiche oder Anpassung an das Theme.

Text

Farbe des Standardtexts im Bereich.

Heading

Farbe des Bereichstitels.

Accent

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

Accent Background

Hintergrundfarbe von Akzentelementen.

Border

Farbe von Linien, Trennlinien, Skalenachsen und Rahmen.

Icon

Farbe des Icons zum Auf- und Zuklappen des Bereichs.

Radius, e.g. 18px

Abrundung der Bereichsecken.

Beispiele: 0, 8px, 18px.

Padding, e.g. 28px

Innenabstand des Bereichs.

Beispiele: 16px, 24px, 28px.

Label Font Size, e.g. 21px

Schriftgröße der Eigenschaftslabels im Bereich.

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

Product Features Appearance

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

Section Background Color

Hintergrundfarbe des Bereichs.

Standardmäßig: #f4f4f4.

Section Text Color

Grundlegende Textfarbe im Bereich.

Standardmäßig: #000000.

Section Heading Color

Farbe der Bereichsüberschrift.

Standardmäßig: #000000.

Muted Text Color

Farbe für unterstützende und weniger wichtige Texte.

Standardmäßig: #555555.

Accent Color

Farbe aktiver Elemente und Hervorhebungen.

Standardmäßig: #000000.

Accent Background Color

Hintergrundfarbe aktiver Elemente, z. B. Markierungen.

Standardmäßig: #ffffff.

Border Color

Farbe von Rahmen, Trennlinien und Skalenachsen.

Standardmäßig: #9b9b9b.

Icon Color

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

Standardmäßig: #000000.

Selected Text Color

Textfarbe des ausgewählten Werts.

Standardmäßig: #000000.

Selected Font Weight

Schriftstärke des ausgewählten Werts.

Standardmäßig: 700.

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

Section Border Radius

Abrundung des Bereichscontainers.

Standardmäßig: 18px.

Section Padding

Innenabstand des Bereichs.

Standardmäßig: 28px.

Section Gap

Abstand zwischen den Bereichen.

Standardmäßig: 16px.

Heading Font Size

Schriftgröße der Bereichsüberschrift.

Standardmäßig: 20px.

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

Label Font Size

Schriftgröße der Eigenschaftslabels und Wertelabels.

Standardmäßig: 21px.

Body Font Size

Schriftgröße des Basisinhalts des Bereichs.

Standardmäßig: 16px.

Attributverwaltung auf Produktebene

Das Modul erstellt kein separates System für Produktdaten. Es verwendet Magento-Produktattribute, deshalb 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 Modulbereichen verwendet werden.
4. Wenn das Produkt CMS-Blöcke nutzen soll, gehen Sie zur Gruppe Product Features und setzen Sie das Feld CMS Blocks.
5. Speichern Sie das Produkt.
6. Leeren Sie den Cache, falls das Projekt dies erfordert.

Ein Bereich erscheint im Frontend nur dann, wenn:

• das Modul aktiviert ist,
• der Bereich in der Konfiguration aktiviert ist,
• das Attribut existiert,
• das Produkt einen Attributwert hat,
• der Renderer den ausgewählten Wert verarbeiten kann,
• der Bereich 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: Standard-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, dem Produkt aktive CMS-Blöcke zuzuweisen. Jeder ausgewählte Block wird als separater Bereich gerendert, wenn in der Modulkonfiguration ein Bereich mit Folgendem existiert:

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

Der Titel des Bereichs im Frontend stammt aus dem Titel des CMS-Blocks, der Inhalt aus dem Blockinhalt. Inaktive Blöcke oder Blöcke, die für den Store View nicht verfügbar sind, 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 diese als Bereichstitel sichtbar sein können,
• weisen Sie Blöcke den richtigen Store View 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 Massenbearbeitung von Produkten vorbereitet.

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

Einsatz: schnelle Zuweisung desselben CMS-Bereichs, z. B. Lieferung, Rückgaben oder Pflegehinweise, für viele Produkte gleichzeitig.

Attribute für Skalen

Für den Typ scale verwenden Sie select Attribute mit 2 oder 3 aktiven Optionen.

Beispiel:

• Attribut fit,
• Optionen: Locker, Regular, Figurbetont.

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 scale Renderer dieses Attribut.

Multiselect-Attribute

Für Listen von Eigenschaften, Anwendungen, Technologien oder Zertifikaten verwenden Sie multiselect Attribute.

Mögliche Darstellungstypen:

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

Ein 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 verwendet werden.

Einsatz:

• Technologie-Icons,
• Farben,
• Anwendungs-Piktogramme,
• 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 Options-Icon aus Amasty ShopbyBrand / ShopbyBase abzurufen.

Icon-Quelle:

Shop by Brand > Option Edit > Other > Small Image

Der Alternativtext stammt aus Small Image Alt, und falls 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

Für kurze Informationen verwenden Sie text_inline, key_value oder badge.

Für längere Beschreibungen verwenden Sie 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 numerische Werte können verwendet werden:

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

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

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

Boolean-Attribute

Für Ja/Nein-Attribute verwenden Sie:

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

Bildattribute

Für Attribute vom Typ Bild können verwendet werden:

• image,
• image_with_label,
• image_grid.

Das Modul erstellt die Bild-URL auf Basis des Magento-Produktmedienverzeichnisses und verwendet das Attributlabel als Alternativtext.

Beispielkonfiguration

Bereich mit mehreren Skalen:

Anwendungsbereich mit Icons:

CMS-Bereiche:

Diagnose

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

• ob Enabled des Moduls den Wert Yes hat,
• ob der jeweilige Bereich Enabled = Yes hat,
• ob das Produkt das Attribut ausgefüllt hat,
• ob der richtige Attribute Code oder Attribute Codes gewählt wurde,
• ob Display Type zum Attributtyp passt,
• ob Hide Empty den leeren Bereich 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.