Den Balken im Theme oder in einer Headless-Storefront anpassen
Diese Anleitung richtet sich an Agentur-Entwicklerinnen und -Entwickler. Sie behandelt die Twig-Blöcke, die CSS-Custom-Properties, die JavaScript-Events und die Store API.
Das Markup überschreiben
Der Balken ist eine Twig-Komponente, @Storefront/storefront/component/ssd-unlock-bar/unlock-bar.html.twig, eingebunden auf drei Seiten:
| Seite | Block, der sie einbindet |
|---|---|
| Off-Canvas-Warenkorb | component_offcanvas_cart_ssd_unlock_bar |
| Warenkorbseite | page_checkout_cart_ssd_unlock_bar |
| Bestellbestätigungsseite | page_checkout_confirm_ssd_unlock_bar |
Jeder Teil der Komponente hat einen eigenen Block, beginnend mit ssd_unlock_bar: etwa ssd_unlock_bar_message, ssd_unlock_bar_track, ssd_unlock_bar_milestone, ssd_unlock_bar_gift_popover und ssd_unlock_bar_gift_choice. Erweitern Sie das Template in Ihrem Theme und überschreiben Sie nur die Blöcke, die Sie brauchen.
Geschenkpositionen im Warenkorb werden über Kind-Blöcke der Core-Templates für Positionen gekennzeichnet: component_line_item_type_product_ssd_gift_badge, component_line_item_type_product_ssd_gift_meta und component_line_item_quantity_ssd_gift_display.
Alles rund um den Balken ist Bootstrap-5-Markup (card, badge, btn btn-link, Text-Utilities). Ein Theme, das Bootstrap umgestaltet, gestaltet also auch den Balken um.
Mit CSS-Custom-Properties umgestalten
Die eigenen Styles des Balkens lesen Custom Properties auf .ssd-unlock-bar. Sie greifen standardmäßig auf die Bootstrap-Variablen des Themes zurück (--bs-primary, --bs-success, --bs-border-color, --bs-border-radius, --bs-body-color), sodass die meisten Themes nichts überschreiben müssen. Die wichtigsten:
| Property | Steuert |
|---|---|
--ub-fill | den gefüllten Teil des Balkens |
--ub-track | den leeren Teil des Balkens |
--ub-done | freigeschaltete Markierungen |
--ub-text | den Text des Balkens |
--ub-h | die Höhe des Balkens |
--ub-radius | den Eckenradius des Balkens |
--ub-marker | die Größe der Markierungen |
Farben und Feineinstellungen aus der Plugin-Konfiguration werden als diese Properties in eine kleine, begrenzte <style>-Regel geschrieben, sodass die Werte des Händlers die Vorlage schlagen. Der Abschnitt trägt die Klassen ssd-unlock-bar--preset-{native|minimal|bold|steps} und ssd-unlock-bar--marker-{photo|icon|dot|number}.
In JavaScript auf Freischaltungen reagieren
Wird ein Meilenstein freigeschaltet, während die Kundschaft zusieht, veröffentlicht die Storefront UnlockBar/milestoneUnlocked auf document.$emitter. Das Event wird als CustomEvent auf document ausgelöst, beide Formen funktionieren also:
document.$emitter.subscribe('UnlockBar/milestoneUnlocked', (event) => {
const { milestoneId, reward, threshold } = event.detail;
// reward: 'free_shipping' oder 'gift'; threshold: eine Zahl in der Währung des Verkaufskanals
});Es feuert einmal pro Meilenstein, auch bei reduzierter Bewegung (nur die Animation entfällt). Ob ein Meilenstein neu ist, entscheidet der Server und speichert es am Warenkorb. Das Event wiederholt sich deshalb nicht beim Neuladen, und auf dem Gerät der Kundschaft wird nichts gespeichert.
Den Balken über die Store API lesen
Jede Warenkorb-Antwort der Store API enthält den Zustand des Balkens in extensions.unlockBarProgress:
| Feld | Bedeutung |
|---|---|
qualifyingAmount | der Warenwert, der mit allen Beträgen verglichen wird |
milestones | die Meilensteine dieser Kundschaft, nach Betrag sortiert |
nextMilestone | der nächste gesperrte Meilenstein, oder null |
percent | wie weit der Balken gefüllt ist |
allUnlocked | true, wenn alle Meilensteine freigeschaltet sind |
Jeder Meilenstein hat id, type (free_shipping oder gift), title, description, threshold, unlocked, remaining, declined, newlyUnlocked und icon. Ein Geschenk-Meilenstein hat zusätzlich gift (das Geschenk im Warenkorb, mit productId, giftOptionId, productNumber, name, value und cover) und giftOptions (die Optionen, aus denen die Kundschaft wählen kann).
newlyUnlocked ist in der ersten Warenkorb-Antwort nach der Freischaltung true und in keiner späteren. Nutzen Sie es, um den Freischaltmoment in einer Headless-Storefront abzuspielen.
Das Geschenk über die Store API ändern
| Route | Wirkung |
|---|---|
POST /store-api/ssd-unlock-bar/gift/{milestoneId}/choose mit giftOptionId | tauscht das Geschenk gegen eine andere Option (Pro) |
POST /store-api/ssd-unlock-bar/gift/{milestoneId}/add-back | fügt ein entferntes Geschenk wieder hinzu |
Beide berechnen den Warenkorb neu und geben ihn zurück. Ein Geschenk entfernen Sie über die normale Route zum Löschen von Positionen; sie markiert es als entfernt. Eine Mengenänderung an einer Geschenkposition wird abgelehnt.
Geschenkpositionen in Bestellungen
Ein Geschenk ist eine Produktposition für 0 € mit dem echten Produkt, Produktnummer, Steuerregeln und Lieferinformationen. Ihr Payload enthält ssdCpbGiftMilestoneId, ssdCpbGiftOptionId, ssdCpbGiftThreshold und ssdCpbGiftValue. Das Neuberechnen einer Bestellung in der Administration fügt nie Geschenke hinzu und entfernt keine.
Regelbedingung
Die Rule-Builder-Bedingung ssdCpbMilestoneUnlocked („Unlock Bar-Meilenstein ist freigeschaltet“) erhält eine Meilenstein-ID und trifft zu, wenn der Warenkorb diesen Meilenstein freigeschaltet hat. Sie braucht einen Warenkorb und trifft deshalb in Bereichen ohne Warenkorb nie zu, etwa in einem Flow zu einer bestehenden Bestellung.
