Variantenauswahl Plus

Inhalt

1. Wozu dient das Plugin "Variantenauswahl Plus"
2. Was kann das Plugin "Variantenauswahl Plus"
3. Systemvoraussetzungen
4. Installation im JTL-Shop
5. Plugin "Variantenauswahl Plus" einrichten
6. Sonstiges / Bemerkungen

1. Wozu dient das Plugin "Variantenauswahl Plus"

Die von JTL-Shop mitgelieferte Standard-Variationsauswahl ist ein einfaches Dropdown-Feld. Bei Variationen mit
vielen Werten – insbesondere bei Maßangaben wie Länge, Gewicht, Volumen oder elektrischen Größen (Spannung,
Stromstärke, Leistung) – wird die Auswahl über eine lange Liste für Kunden schnell unübersichtlich.

Variantenauswahl Plus ersetzt das Standard-Dropdown wahlweise durch:

ein Number-Input – der Kunde gibt den gewünschten Wert direkt ein (z. B. „95 cm“) und das Plugin
ermittelt automatisch die passende, tatsächlich lieferbare Variante,
einen Scroll-Picker – die Variationswerte werden als scrollbare Liste dargestellt, ähnlich einer
mobilen Datumsauswahl.

Beide Bedienkonzepte sind vollständig konfigurierbar, unterstützen Einheitenumrechnung (z. B. cm ↔ m), zeigen
passende Alternativvorschläge an und lassen sich pro Artikel über Funktionsattribute in der JTL-Wawi steuern.

2. Was kann das Plugin "Variantenauswahl Plus"

2.1 Number-Input

Der Kunde trägt einen Zahlenwert in ein Eingabefeld ein oder verändert ihn über Plus-/Minus-Buttons bzw. die
Pfeiltasten. Das Plugin zerlegt den Variationsnamen anhand eines konfigurierbaren Trennzeichens, extrahiert Zahl
und Einheit und ermittelt daraus die nächstliegende, tatsächlich existierende Variante – über Einheitsgrenzen
hinweg (z. B. 105 cm → 1,05 m).

Abbildung 1: Number-Input auf der Artikeldetailseite – Eingabefeld, Einheiten-Buttons und Vorschläge

Enthaltene Funktionen:

Einheiten-Umrechnung über frei konfigurierbare Bezugsgrößen (siehe Abschnitt 2.3)
Vorschläge: neben dem Haupttreffer werden auf Wunsch der vorherige und nachfolgende
Variationswert als anklickbare Alternativen angezeigt
Eingegebene Einheit beibehalten (optional): die vom Kunden gewählte Einheit bleibt beim
Navigieren erhalten, auch wenn der getroffene Variationswert in einer anderen Einheit hinterlegt ist
Bestätigungsbutton (✓) optional ein-/ausblendbar
Platzhaltertext im Eingabefeld, pro Artikel und Sprache über Funktionsattribut pflegbar
Info-Box unterhalb der Ergebnisanzeige (siehe Abschnitt 2.4)
Farben, Schriftgrößen und Bootstrap-Klassen aller Buttons frei einstellbar (siehe Abschnitt 5.1)

2.2 Scroll-Picker

Alternativ zum Number-Input steht ein Scroll-Picker zur Verfügung: Die Variationswerte werden als vertikale
Liste dargestellt, durch die der Kunde per Maus, Touch, Mausrad, Scrollbalken oder Tastatur navigiert. Der
mittig stehende Wert gilt als ausgewählt.

Abbildung 2: Scroll-Picker auf der Artikeldetailseite

Enthaltene Funktionen:

Navigationspfeile optional ein-/ausblendbar, Position frei wählbar (links/mittig/rechts)
Scrollbalken optional ein-/ausblendbar
Anzahl gleichzeitig sichtbarer Elemente einstellbar (3–7, empfohlen ungerade)
Schriftgröße, -gewicht und -farbe sowie Hintergrund- und Rahmenfarbe frei konfigurierbar
Vollständig per Tastatur bedienbar, Screenreader-Unterstützung (siehe Abschnitt 6.2)

2.3 Einheiten-System (Bezugsgrößen)

Damit das Plugin Werte wie „95 cm“ und „1 m“ als dieselbe physikalische Größe erkennt und ineinander
umrechnen kann, verwaltet es Bezugsgrößen-Gruppen. Jede Gruppe (z. B. „Länge“) enthält beliebig
viele Einheiten mit einem Umrechnungsfaktor relativ zur Basiseinheit der Gruppe (Basiseinheit = Faktor 1).

Im Auslieferungszustand sind sechs Standardgruppen enthalten:

Gruppe	Enthaltene Einheiten
Länge	mm, cm, dm, m, km, in, ft, yd, mi, nmi
Gewicht	mg, g, kg, t
Volumen	ml, cl, dl, l, ccm, cm³, m³
Spannung	mV, V, kV
Stromstärke	mA, A
Leistung	mW, W, kW, MW

Eigene Gruppen und Einheiten lassen sich beliebig ergänzen; Standardgruppen können einzeln oder gesamt auf den
Auslieferungszustand zurückgesetzt werden. Details zur Verwaltungsoberfläche in Abschnitt 5.2.

2.4 Info-Box

Unterhalb der Ergebnisanzeige des Number-Inputs kann ein Hinweisfeld mit Überschrift, Fließtext und optionalem
Link zu einem weiterführenden Artikel eingeblendet werden. Die Inhalte werden am Vaterartikel über
Funktionsattribute gepflegt (mehrsprachig möglich) und lassen sich z. B. nutzen, um auf Zubehör, Montagehinweise
oder Mindestbestellmengen hinzuweisen. Die Anzeigebedingung (z. B. „nur wenn Titel, Text und Link ermittelt
wurden“) ist konfigurierbar.

2.5 Hilfe-Tooltip

Neben der Variationsüberschrift erscheint ein Fragezeichen-Icon, das per Klick, Hover oder Tastaturfokus einen
Hilfetext zur Bedienung des jeweiligen Auswahlelements einblendet. Die Texte sind über die Sprachvariablen-
Verwaltung des Plugins editierbar.

3. Systemvoraussetzungen

JTL-Shop 5.6 oder höher je nach Pluginversion
PHP 8.3 oder höher je nach Pluginversion
Template NOVA (inkl. NOVA-Kindtemplates)

4. Installation im JTL-Shop

Für Deinen JTL-Shop 5 beziehst Du Plugins über den JTL-Extension Store. Um auf Inhalte des JTL-Extension Stores zugreifen zu können, musst Du zunächst Dein JTL-Konto mit Deinem JTL-Shop 5 verknüpfen. Dies wird normalerweise beim Installationsprozess des Shops bereits abgefragt.

So verknüpfst Du Dein JTL-Konto mit Deinem JTL-Shop 5:

Logge Dich im JTL-Shop-Backend ein.
Navigiere im Menü zu „PLUGINS“ > „Meine Käufe“.
Klicke auf „Konto verknüpfen“.
Logge Dich mit Deinen JTL-Daten ein.
Anschließend siehst Du in „PLUGINS“ > „Meine Käufe“ die Übersicht zu Deinen Lizenzen und Subscriptions.

So buchst Du eine Extension für JTL-Shop 5:

Rufe den JTL-Extension Store auf.
Suche nach dem gewünschten Plugin.
Wähle das Plugin aus und klicke auf „Jetzt auschecken“.
Klicke im folgenden Fenster auf „Anmelden“ und melde Dich mit Deinem zentralen JTL-Login an.
Klicke im JTL-Checkout auf „Jetzt bestellen“, um die Bestellung abzuschließen.
Rufe Dein JTL-Shop-Backend auf. Unter „PLUGINS“ > „Meine Käufe“ beﬁndet sich jetzt im Bereich „Ungebundene Lizenzen“ Deine eben erworbene Lizenz.
Nun ordnest Du das Plugin Deinem Shop zu. Klicke dafür auf „An diesen Onlineshop“ anbinden.
Anschließend ﬁndest Du die Lizenz im Bereich „Gebundene Lizenzen“ und die Schaltﬂäche „Installieren“ steht zur Verfügung. Nach der Installation kannst Du das Plugin im Menü unter „PLUGINS“ > „Plugin-Manager“ in der Registerkarte „Aktiviert“ konﬁgurieren.

5. Plugin "Variantenauswahl Plus" einrichten

Nach der Aktivierung erscheint das Plugin in der Plugin-Übersicht mit vier Reitern: Einstellungen, Bezugsgrößen, Lizenz und Über.

Abbildung 3: Reiterleiste des Plugins im Shop-Backend

5.1 Reiter „Einstellungen“

Die Einstellungen sind in vier aufklappbare Bereiche gegliedert.

Allgemein

Abbildung 4: Einstellungen – Bereich „Allgemein“

Einstellung	Beschreibung
Plugin aktiv	Wenn aktiviert, wird das Plugin verwendet. Sinnvoll, um es kurzzeitig auszuschalten und Einstellungen auszuprobieren.
Zum Auswahlbereich scrollen	Nach dem Laden einer neuen Produktseite durch Variationsauswahl wird automatisch zum Auswahlbereich gescrollt.
Rahmenfarbe	Rahmenfarbe der Buttons und Eingabefelder.

Funktionsattribute (JTL-Wawi)

Einstellungen – Übersicht der Funktionsattribute

Abbildung 5: Einstellungen – Übersicht der verfügbaren Funktionsattribute (identisch mit der Tabelle in Abschnitt 5.5)

Dieser Bereich zeigt zur schnellen Referenz direkt im Backend alle unterstützten Funktionsattribute inklusive
Pflichtstatus, Beispielwert und Beschreibung an (siehe Abschnitt 5.5 für die vollständige Tabelle).

Number-Input

Abbildung 6: Einstellungen – Bereich „Number-Input“

Einstellung	Beschreibung
Trennzeichen	Zeichen, das den Variationsnamen in einzelne Teile aufteilt. Kann pro Artikel mit dem Funktionsattribut `knm_number_input_divider` überschrieben werden.
Verwendeter Teil	Index des Teils (0-basiert), der Zahl und Einheit enthält. Standard: 0 (erster Teil). Kann pro Artikel mit dem Funktionsattribut `knm_number_input_part_index` überschrieben werden.
Dauer bis zum Absenden	Solange wird nach der letzten Eingabe gewartet, bevor der passende Variationswert gesucht und angezeigt wird.
Eingegebene Einheit beibehalten	Wenn aktiviert, bleibt die gewählte Einheit beim Navigieren erhalten. Eingabe von 105 cm zeigt weiterhin cm — auch wenn der nächste Variationswert in Meter gespeichert ist.
Kompakte Vorschlagsanzeige	Aktiviert: Vorschläge zeigen nur Maß und Einheit (z. B. 15 cm) — minimalistisch und platzsparend. Deaktiviert: Vorschläge zeigen den vollständigen Variationsnamen inkl. Trennzeichen zwischen den Zusatzinfos.
Bestätigungsbutton anzeigen	Zeigt den Bestätigungsbutton (✓) rechts neben den Einheiten an. Kann deaktiviert werden, wenn die Variante per Klick auf den Vorschlagswert gewählt wird.
Vorschläge anzeigen	Zeigt neben dem nächsten Treffer auch den vorherigen und nachfolgenden Variationswert als auswählbare Vorschläge an.
Info-Box anzeigen	Legt fest, wann die Info-Box unterhalb der Ergebnisanzeige erscheint (z. B. immer, oder nur wenn Titel, Text und Link ermittelt wurden).
Sprachvariable verwenden	Ja: Sprachvariable immer als Zusatztext in der Info-Box anzeigen. Nein: Sprachvariable nur als Fallback anzeigen, wenn die Info-Box sonst leer wäre.
Bootstrap-/CSS-Klassen der Buttons	Für Bestätigungsbutton, aktive/inaktive Einheiten-Buttons sowie Haupttreffer- und Alternativ-Vorschläge lässt sich jeweils die Bootstrap-Klasse (z. B. `btn-primary`) und eine zusätzliche eigene CSS-Klasse hinterlegen.

Scroll-Picker

Abbildung 7: Einstellungen – Bereich „Scroll-Picker“

Einstellung	Beschreibung
Pfeile anzeigen	Zeigt oberhalb und unterhalb des Scroll-Pickers Pfeile zur Navigation an.
Pfeilposition	Horizontale Ausrichtung der Navigationspfeile im Scroll-Picker (links, mittig, rechts).
Scrollbalken anzeigen	Zeigt einen Scrollbalken am rechten Rand des Scroll-Pickers an.
Hintergrundfarbe	Hintergrundfarbe hinter dem Scroll-Picker. Muss dem Hintergrund des umgebenden Elements entsprechen (z. B. Seite oder Card).
Schriftgröße / -gewicht / -farbe	Darstellung der Variationswerte im Scroll-Picker.
Zeilenabstand	Abstand zwischen den einzelnen Elementen im Scroll-Picker.
Sichtbare Elemente	Anzahl der gleichzeitig sichtbaren Elemente. Empfohlen: ungerade Zahl (3, 5, 7 …).
Dauer bis zum Absenden	Solange wird nach dem Ende des Scrollvorgangs gewartet, bevor der Artikel geladen bzw. die Variation gewählt wird.

5.2 Reiter „Bezugsgrößen“

Hier werden die in Abschnitt 2.3 beschriebenen Einheiten-Gruppen verwaltet: Gruppen und Einheiten anlegen,
bearbeiten, per Drag & Drop sortieren und löschen. Die sechs Standardgruppen lassen sich einzeln oder
gemeinsam auf den Auslieferungszustand zurücksetzen.

Abbildung 8: Reiter „Bezugsgrößen“ – Verwaltung der Einheiten-Gruppen

Hinweis: Der Umrechnungsfaktor einer Einheit ist immer relativ zur Basiseinheit der Gruppe angegeben (Basiseinheit = Faktor 1).

5.3 Reiter „Lizenz“

Abbildung 9: Reiter „Lizenz“

Über diesen Reiter wird die Lizenz abgefragt, ein zeitlich begrenzter Test gestartet oder eine bestehende
Lizenz verlängert.

5.4 Reiter „Über“

Abbildung 10: Reiter „Über“ – Versionsinformationen

Zeigt die installierte Plugin-Version sowie ergänzende Informationen an.

5.5 Funktionsattribute in der JTL-Wawi einrichten

Ob und wie das Plugin für eine Variation aktiv wird, wird über Funktionsattribute am Artikel in der JTL-Wawi
gesteuert. Die grundlegende Einrichtung eines Funktionsattributs läuft dabei immer gleich ab:

In der JTL-Wawi zu Artikel → Attribute → Funktionsattribute wechseln.
Eine neue Attributgruppe anlegen (falls noch nicht vorhanden), z. B. „Variantenauswahl Plus“.
Innerhalb der Gruppe ein neues Funktionsattribut anlegen.
Den Namen exakt wie in der folgenden Tabelle angegeben eintragen (Groß-/Kleinschreibung beachten).
Das Attribut für den Shop aktivieren.
Den gewünschten Wert gemäß Tabelle setzen.
Das Funktionsattribut dem betreffenden Artikel bzw. Vaterartikel zuweisen.
Artikel/Bild-Abgleich mit dem Shop durchführen.
Ergebnis auf der Artikeldetailseite im Shop-Frontend prüfen.

Hinweis: Funktionsattribute mit dem Zusatz knm_number_input_info_* werden am
Vaterartikel gepflegt, alle übrigen Funktionsattribute am jeweiligen Variationskind.

Typ	Attribut	Wert	Beschreibung
Pflicht	`knm_scroll_input`	Variationsname	Aktiviert den Scroll-Picker für diese Variation.
Pflicht	`knm_number_input`	Variationsname	Aktiviert den Number-Input für diese Variation.
Optional	`knm_number_input_divider`	`\|`	Überschreibt das Plugin-Setting „Trennzeichen“ für diesen Artikel.
Optional	`knm_number_input_part_index`	`0`	Überschreibt das Plugin-Setting „Verwendeter Teil“ für diesen Artikel.
Optional	`knm_number_input_placeholder_ger`	Freitext	Platzhaltertext im Eingabefeld des Number-Inputs. Optional kann für jede Sprache ein sprachspezifisches FA angelegt werden (z. B. `_ger`, `_eng`, `_fre`). Ist kein sprachspezifisches FA gesetzt, wird `knm_number_input_placeholder` (ohne Suffix) als Fallback verwendet.
Optional	`knm_suggestion_list_label`	Freitext	Überschreibt die Überschrift der Vorschlagsliste für diesen Artikel (wenn Kompakte Vorschlagsanzeige deaktiviert ist).
Optional	`knm_number_input_extra`	Freitext	Wird am Kindartikel gepflegt. Zeigt einen zusätzlichen Text (z. B. „ab 30,- €“) rechts vor dem Pfeil, wenn Kompakte Vorschlagsanzeige deaktiviert ist.
Optional	`knm_number_input_info_last_option`	`1`	Wird am Vaterartikel gepflegt. Wenn auf 1 gesetzt, erscheint die Info-Box nur, wenn das eingegebene Maß auf die größte verfügbare Variante trifft.
Optional	`knm_number_input_info_title`	Freitext	Wird am Vaterartikel gepflegt. Überschrift der Info-Box. Optional sprachspezifisch (z. B. `_ger`, `_eng`, `_fre`).
Optional	`knm_number_input_info_text`	Freitext	Wird am Vaterartikel gepflegt. Fließtext der Info-Box. Optional sprachspezifisch (z. B. `_ger`, `_eng`, `_fre`).
Optional	`knm_number_input_info_article`	Freitext	Wird am Vaterartikel gepflegt. Artikelnummer (cArtNr) oder Artikel-ID (kArtikel) des verlinkten Artikels. Bei doppelter cArtNr wird das erste Ergebnis verwendet.
Optional	`knm_number_input_info_article_use_id`	`1`	Wird am Vaterartikel gepflegt. Wenn auf 1 gesetzt, wird `knm_number_input_info_article` als kArtikel ausgewertet.
Optional	`knm_number_input_info_article_category`	Freitext	Wird am Vaterartikel gepflegt. Kategorie-ID (kKategorie). Verlinkung wird nur ermittelt, wenn der Artikel in dieser Kategorie vorhanden ist. Bei mehreren Kategorien wird der erste Treffer verwendet.

6. Sonstiges / Bemerkungen

6.1 Optische Anpassung

Sämtliche Buttons (Bestätigung, Einheitenwahl, Vorschläge) lassen sich über Bootstrap-Klassen und optionale
eigene CSS-Klassen frei gestalten, ohne dass ein Template-Override notwendig ist. Farben (Rahmen, Hintergrund,
Schrift) werden ebenfalls direkt im Backend gepflegt.

6.2 Barrierefreiheit

Beide Auswahlelemente sind vollständig per Tastatur bedienbar und mit den erforderlichen ARIA-Attributen
versehen (u. a. role="listbox"/role="option" beim Scroll-Picker,
aria-live bei der Ergebnisanzeige des Number-Inputs). Fokuszustände sind deutlich sichtbar
(:focus-visible), Animationen respektieren die Systemeinstellung „Bewegungen reduzieren“.