Custom Data Toolkit — Dokumentation

Für Shop-Betreiber:innen und Administrator:innen, die eines oder mehrere CDT-Plugins einsetzen.

Custom Data Toolkit besteht aus sechs Plugins, die aufeinander aufbauen. Core ist die gemeinsame, immer benötigte Basis. Die eigentliche Bedienoberfläche — Katalog → Custom Data Toolkit — liefert das Filter-Plugin; installierte Zusatzmodule (Sort, Columns, Search, Elasticsearch) erscheinen automatisch als weitere Abschnitte in genau diesem einen Register, es entsteht keine zusätzliche Admin-Seite.

PluginKurzbeschreibung
CoreTechnisches Fundament: Schema-Analyse, Feldregister, Surface-Aktivierung. Immer erforderlich.
FilterStorefront- und Admin-Filter je Feld/Entität; stellt außerdem das zentrale Admin-Register bereit.
SortBeliebige Felder als Storefront-Sortieroption.
ColumnsBeliebige Felder als zusätzliche Spalte in Admin-Listen (Produkte, Bestellungen, Kunden).
SearchErweitert Storefront- und Admin-Suche um zusätzliche Felder.
ElasticsearchPremium-Erweiterung: Elasticsearch-/OpenSearch-Unterstützung für alle CDT-Flächen.
BundleKomfort-Paket, das Core + Filter + Sort + Columns + Search in einem Produkt bündelt.

Wie die Module zusammenspielen

Core (Pflicht)
 └─ Filter   → liefert Katalog → Custom Data Toolkit (Register-UI für alle Module)
 └─ Sort     → eigener Abschnitt "Als Sortierung verfügbar machen" im Register
 └─ Columns  → eigener Abschnitt "Als Admin-Spalte anzeigen" im Register
 └─ Search   → eigener Abschnitt "In Suche einbeziehen" im Register
 └─ Elasticsearch (optional) → Mapping/Reindex-Hinweise im Register, wenn ES aktiv ist
Bundle = Core + Filter + Sort + Columns + Search in einem Produkt

Core Pflicht

Technisches Fundament der CDT-Familie

Analysiert den Shop, führt ein zentrales Feldregister und stellt die Programmierschnittstelle bereit, auf der Filter, Sortierung, Admin-Spalten und Suche aufbauen.

Für wen ist dieses Plugin?

Für jeden, der eines der anderen CDT-Plugins (Filter, Sort, Columns, Search, Elasticsearch) einsetzen möchte — Core ist deren gemeinsame Voraussetzung. Core selbst liefert keine eigene Bedienoberfläche; die Konfiguration erfolgt im Register, das vom Filter-Plugin bereitgestellt wird (siehe Filter).

Was macht Core?

Voraussetzungen

Installation

bin/console plugin:refresh
bin/console plugin:install --activate CustomDataToolkitCore

Nach der Aktivierung passiert im Admin zunächst nichts sichtbar — Core arbeitet im Hintergrund. Installieren Sie zusätzlich mindestens Filter, um das Register zu sehen und Felder tatsächlich freizugeben.

Konfiguration

Unter Einstellungen → Erweiterungen → Custom Data Toolkit Core → Konfigurieren:

EinstellungStandardBedeutung
Dynamische Sortierungen aktivAnSchaltet die vom Sort-Plugin erzeugten product_sorting-Einträge global ein/aus.
Bool-Felder als Sortierung anbietenAusOb boolesche Felder zusätzlich als Sortieroption vorgeschlagen werden.
Schema bei Plugin-Events automatisch analysierenAnFührt nach Plugin-Installation/-Update automatisch eine neue Schema-Analyse aus, ohne manuellen Klick auf „Schema analysieren“.

Verwendung

  1. Im Admin zu Katalog → Custom Data Toolkit navigieren (Fläche, die das Filter-Plugin bereitstellt).
  2. Auf „Schema analysieren“ klicken. Core durchsucht alle Entitäten und meldet die Anzahl gefundener Felder/Entitäten.
  3. Ergebnis erscheint in der Feldauswahl, gruppiert nach Basis-Felder, Assoziationen und Custom Fields — bereit zur Freigabe über die anderen CDT-Module.

Programmierschnittstelle (für Integrationen)

MethodePfadZweck
POST/api/_action/cdt/analyzeSchema-Analyse manuell auslösen
GET/api/_action/cdt/field-registrationsAktuelles Feldregister abfragen
GET/api/_action/cdt/listing-contextsVerfügbare Listing-Kontexte (Produkt, Kategorie, Bestellung, Kunde, Hersteller, Produktsuche)
GET/POST/api/_action/cdt/surfaces/{listingContext}Surface-Aktivierung lesen/schreiben (Parameter salesChannelId, categoryId optional)
GET/api/_action/cdt/compatibilityKompatibilitäts-/Bundle-Hinweise

Grenzen & Hinweise

↑ Zur Modulübersicht

Filter

Storefront- und Admin-Filter je Feld/Entität

Macht beliebige Custom Fields, Custom Entities und Assoziationen ohne Code als Storefront-Filter und Admin-Filter nutzbar. Liefert außerdem das zentrale Custom Data Toolkit-Register im Admin, in dem alle CDT-Module konfiguriert werden.

Für wen ist dieses Plugin?

Für Shops, die Kunden im Storefront nach eigenen Produktmerkmalen (technische Daten, B2B-Attribute, individuelle Kategorisierungen) filtern lassen möchten, sowie für Administrator:innen, die dieselben Felder auch in der Admin-Produktliste filtern wollen.

Wichtig: Auch wer nur Sort, Columns oder Search nutzen möchte, profitiert von der Installation dieses Plugins — es stellt die einzige Bedienoberfläche (Katalog → Custom Data Toolkit) bereit, in der alle Module ihre Schalter zeigen.

Voraussetzungen

Installation

bin/console plugin:refresh
bin/console plugin:install --activate CustomDataToolkitFilter
bin/console cache:clear   # Administration neu bauen, falls nötig: bin/build-administration.sh

Das Register: Katalog → Custom Data Toolkit

Nach der Installation erscheint im Hauptmenü unter Katalog der neue Eintrag „Custom Data Toolkit“. Die Übersichtsseite gliedert sich in:

Verfügbare Filtertypen

TypStorefront-DarstellungGeeignet für
Multi-SelectFacette mit Terms-AggregationAuswahl-Custom-Fields, Assoziationen
Ja/Nein (Boolean)CheckboxBool-Custom-Fields
Bereich / SliderZahleneingabe bzw. Range-Slider mit Min/Max-AggregationZahlenfelder
Freitext (Contains)SuchfeldText-/Langtextfelder
DatumsbereichVon/Bis-AuswahlDatumsfelder
Entitäts-AuswahlAuswahllisteAssoziationen zu anderen Entitäten
Text-Chips (LongText)Mehrfachauswahl per Tag-EingabeLangtextfelder mit mehreren Begriffen (ODER-Verknüpfung)

Bei Multi-Select- und Entitäts-Auswahl-Filtern lässt sich zusätzlich die „Wertgruppierung (Limit)“ setzen — die maximale Anzahl an Facetten-Werten, die im Storefront angezeigt wird.

Schritt-für-Schritt: einen Filter aktivieren

  1. Katalog → Custom Data Toolkit öffnen, ggf. zuerst „Schema analysieren“ ausführen.
  2. Gewünschtes Feld über die Suche oder die Gruppen finden.
  3. Im Abschnitt „Als Filter verfügbar machen“ den Schalter aktivieren und Filtertyp sowie Position (Reihenfolge in der Filterleiste, niedrigere Zahl = weiter oben) wählen.
  4. Falls gewünscht, Verkaufskanal/Kategorie einschränken statt global freizugeben.
  5. „Speichern“ klicken — die Erfolgsmeldung „Konfiguration wurde erfolgreich gespeichert“ bestätigt die Übernahme. „Verwerfen“ macht ungespeicherte Änderungen rückgängig.
  6. Filter im Storefront prüfen: Kategorie- bzw. Such-Listing öffnen, neue Facette sollte in der Filterleiste erscheinen.

Konfiguration (Systemeinstellungen)

Unter Einstellungen → Erweiterungen → Custom Data Toolkit Filter → Konfigurieren:

EinstellungStandardBedeutung
Storefront-Filter aktivAnSchaltet alle CDT-Storefront-Filter global ein/aus, unabhängig von den Einzelfreigaben im Register.
Admin-Filter aktivAnSchaltet die CDT-Filter in der Admin-Produktliste global ein/aus.

Hinweise zur Kompatibilität

Ist zusätzlich das Fremdplugin SwagAdminListingConfig aktiv, weist das Register darauf hin, dass sich Admin-Spalten/-Filter überschneiden können, und empfiehlt, sich auf ein einheitliches Register (CDT) festzulegen. Ist das Bundle-Plugin installiert, aber ein Einzelmodul (z. B. Sort) fehlt oder ist deaktiviert, erscheint ebenfalls ein Hinweis im Register.

Elasticsearch-Hinweis

Ist Custom Data Toolkit Elasticsearch aktiv, zeigt das Register nach Änderungen an filterbaren Feldern einen Hinweis, dass ein bin/console es:index erforderlich ist, bevor die Änderung in der Suche wirksam wird.

↑ Zur Modulübersicht

Sortierung

Custom Data Toolkit — Sort

Macht beliebige Custom Fields, Custom Entities und Assoziationen ohne Code als Storefront-Sortieroption nutzbar.

Für wen ist dieses Plugin?

Für Shops, deren Kunden Produktlisten nach eigenen Merkmalen sortieren sollen — z. B. nach einem technischen Kennwert, einem Freigabedatum oder einem individuellen Rang-Feld, das über Custom Fields gepflegt wird.

Voraussetzungen

Installation

bin/console plugin:refresh
bin/console plugin:install --activate CustomDataToolkitSort

Verwendung

  1. Katalog → Custom Data Toolkit öffnen (Register-UI von Filter).
  2. Gewünschtes Feld auswählen.
  3. Im Abschnitt „Als Sortierung verfügbar machen“ den Schalter aktivieren und die Sortierrichtung wählen: Aufsteigend (A→Z), Absteigend (Z→A) oder Beide Richtungen (erzeugt zwei Sortieroptionen).
  4. Speichern — CDT legt automatisch einen passenden Eintrag im Shopware-Sortier-Repository (product_sorting) an, erkennbar am Schlüsselpräfix cdt.* (z. B. cdt.customFields_mein_feld).
  5. Im Storefront erscheint die neue Option im Sortier-Dropdown des betroffenen Listings.

Konfiguration

Die globalen Schalter für Sortierungen liegen im Plugin Core (Einstellungen → Erweiterungen → Custom Data Toolkit Core): „Dynamische Sortierungen aktiv“ und „Bool-Felder als Sortierung anbieten“.

Hinweise

↑ Zur Modulübersicht

Admin-Spalten

Custom Data Toolkit — Columns

Zeigt beliebige Custom Fields, Custom Entities und Assoziationen ohne Code als zusätzliche Spalte in Admin-Listen an (Produkte, Bestellungen, Kunden).

Für wen ist dieses Plugin?

Für Administrator:innen, die in den Produkt-, Bestell- oder Kundenlisten des Admins auf einen Blick eigene Datenfelder sehen möchten, ohne jeden Datensatz einzeln zu öffnen — etwa einen internen Statuscode, ein Freigabedatum oder ein B2B-Kennzeichen.

Voraussetzungen

Installation

bin/console plugin:refresh
bin/console plugin:install --activate CustomDataToolkitColumns

Verwendung

  1. Katalog → Custom Data Toolkit öffnen (Register-UI von Filter).
  2. Gewünschtes Feld auswählen.
  3. Im Abschnitt „Als Admin-Spalte anzeigen“ den Schalter aktivieren und die Position festlegen (Reihenfolge der Spalte in der Liste).
  4. Speichern.
  5. Betroffene Admin-Liste öffnen (Produkte, Bestellungen oder Kunden, je nachdem für welchen Listing-Kontext das Feld registriert wurde) — die neue Spalte erscheint in der Spaltenauswahl der Liste und kann dort ein-/ausgeblendet werden.

Unterstützte Admin-Listen

Bereits in Shopware vorhandene Standard-Listing-Felder werden in der Feldauswahl automatisch ausgeblendet (Hinweis „{Anzahl} Standard-Listing-Felder ausgeblendet“ im Register), damit die Liste nicht mit Duplikaten überladen wird.

Hinweise zur Kompatibilität

Ist zusätzlich das Fremdplugin SwagAdminListingConfig aktiv, weist das Register darauf hin, dass sich Admin-Spalten überschneiden können, und empfiehlt ein einheitliches Register (CDT) zu verwenden, um doppelte oder widersprüchliche Spaltenkonfigurationen zu vermeiden.

↑ Zur Modulübersicht
Custom Data Toolkit — Search

Bezieht beliebige Custom Fields, Custom Entities und Assoziationen ohne Code in die Storefront- und Admin-Suche mit ein.

Für wen ist dieses Plugin?

Für Shops, deren Kunden nach Begriffen suchen sollen, die in eigenen Datenfeldern stehen (z. B. eine Herstellernummer, ein technisches Kürzel oder ein individuelles Schlagwort), sowie für Administrator:innen, die dieselben Felder in der Admin-Produktsuche wiederfinden möchten.

Voraussetzungen

Was macht Search?

Installation

bin/console plugin:refresh
bin/console plugin:install --activate CustomDataToolkitSearch

Verwendung

  1. Katalog → Custom Data Toolkit öffnen (Register-UI von Filter).
  2. Gewünschtes Feld auswählen.
  3. Im Abschnitt „In Suche einbeziehen“ den Schalter aktivieren.
  4. Speichern.
  5. Suchbegriff, der im Feldwert vorkommt, im Storefront-Suchfeld bzw. in der Admin-Produktsuche eingeben — das Produkt sollte nun in den Treffern erscheinen.

Hinweise

↑ Zur Modulübersicht

Elasticsearch Premium-Add-on

Custom Data Toolkit — Elasticsearch

Erweitert alle CDT-Flächen (Filter, Sortierung, Suche) um Elasticsearch-/OpenSearch-Unterstützung, inklusive automatischer Index-Mapping-Pflege.

Für wen ist dieses Plugin?

Für Shops, die Elasticsearch oder OpenSearch für die Produktsuche/-listings einsetzen. Ohne dieses Plugin funktionieren Filter, Sortierung und Suche der übrigen CDT-Module nur über die klassische Datenbank-Criteria-API — mit aktivem Elasticsearch würden CDT-Felder sonst in den ES-Ergebnissen fehlen, da sie nicht Teil des Standard-Mappings sind.

Voraussetzungen

Was macht Elasticsearch?

Installation & Einrichtung

  1. Elasticsearch-/OpenSearch-Unterstützung im Shopware-Core aktivieren (core.elasticsearch.enabled, Hosts in den Systemeinstellungen hinterlegt).
  2. Plugin installieren und aktivieren:
    bin/console plugin:refresh
    bin/console plugin:install --activate CustomDataToolkitElasticsearch
  3. Unter Einstellungen → Erweiterungen → Custom Data Toolkit Elasticsearch → Konfigurieren den Schalter „CDT-Elasticsearch-Integration aktivieren“ einschalten (Standard: aus).
  4. Nach der Aktivierung sowie nach jeder Änderung an Feld-Freigaben im Register:
    bin/console es:mapping:update
    bin/console es:index

Reindex-Hinweis im Register

Solange Elasticsearch aktiv ist, zeigt das Register (Katalog → Custom Data Toolkit, bereitgestellt von Filter) bei jeder Änderung an einem such-/filterrelevanten Feld einen Hinweis: „Elasticsearch: Mapping geändert — bitte bin/console es:index ausführen und danach den Hinweis bestätigen.“ Nach dem Reindex lässt sich der Hinweis über die Statusseite quittieren.

Programmierschnittstelle

MethodePfadZweck
GET/api/_action/cdt-elasticsearch/statusLiefert enabled, integrationActive, requiresReindex
POST/api/_action/cdt-elasticsearch/acknowledge-reindexReindex-Hinweis quittieren, nachdem der Reindex gelaufen ist

Hinweise

↑ Zur Modulübersicht

Bundle

Custom Data Toolkit — Bundle

Komfort-Paket, das Core, Filter, Sort, Columns und Search in einem Produkt bündelt — ein Kauf statt fünf.

Für wen ist dieses Plugin?

Für alle, die von Anfang an die volle CDT-Funktionalität wollen (Filter, Sortierung, Admin-Spalten und Suche für eigene Datenfelder), ohne die Module einzeln zu suchen und zu installieren. Elasticsearch bleibt bewusst außen vor und wird nur empfohlen, da es zusätzliche Infrastruktur (einen laufenden Elasticsearch-/OpenSearch-Server) voraussetzt.

Enthaltene Module

ModulAufgabe
CoreSchema-Analyse, Feldregister, Surface-API
FilterStorefront-/Admin-Filter, zentrales Register
SortStorefront-Sortierung
ColumnsAdmin-Spalten
SearchStorefront-/Admin-Suche

Nicht enthalten, optional nachrüstbar: Elasticsearch.

Installation

Der Bundle-Kauf installiert automatisch alle fünf enthaltenen Plugins als Abhängigkeiten:

bin/console plugin:refresh
bin/console plugin:install --activate CustomDataToolkitCore
bin/console plugin:install --activate CustomDataToolkitFilter
bin/console plugin:install --activate CustomDataToolkitSort
bin/console plugin:install --activate CustomDataToolkitColumns
bin/console plugin:install --activate CustomDataToolkitSearch
bin/console plugin:install --activate CustomDataToolkitBundle
bin/console cache:clear

Verwendung

Alle Flächen werden über ein Register bedient: Katalog → Custom Data Toolkit. Das Bundle selbst fügt der Administration zusätzlich einen eigenen Übersichtspunkt „Custom Data Toolkit“ hinzu, der die installierten Module auflistet und direkt zum Register verlinkt („Register öffnen“).

Details zur eigentlichen Konfiguration je Fläche (Filtertypen, Sortierrichtung, Spaltenposition, Sucheinbindung) stehen in den jeweiligen Modul-Abschnitten oben.

Kompatibilitäts-Hinweise

Ist ein Teil des Bundles (z. B. Sort) nachträglich deaktiviert worden, während das Bundle selbst aktiv bleibt, zeigt das Register einen Hinweis wie „Custom Data Toolkit (Bundle) ist aktiv, aber Custom Data Toolkit (Sort) nicht — Sortierfunktionen des Bundles fehlen. Bitte aktivieren.“ — analog für Filter, Columns und Search.

↑ Zur Modulübersicht
>

Frage zu einem Modul, ein Bug oder Feature-Wunsch? Support-Ticket öffnen oder direkt an support@kernpfad.dev schreiben.