Skip to content

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:

SeiteBlock, der sie einbindet
Off-Canvas-Warenkorbcomponent_offcanvas_cart_ssd_unlock_bar
Warenkorbseitepage_checkout_cart_ssd_unlock_bar
Bestellbestätigungsseitepage_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:

PropertySteuert
--ub-fillden gefüllten Teil des Balkens
--ub-trackden leeren Teil des Balkens
--ub-donefreigeschaltete Markierungen
--ub-textden Text des Balkens
--ub-hdie Höhe des Balkens
--ub-radiusden Eckenradius des Balkens
--ub-markerdie 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:

js
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:

FeldBedeutung
qualifyingAmountder Warenwert, der mit allen Beträgen verglichen wird
milestonesdie Meilensteine dieser Kundschaft, nach Betrag sortiert
nextMilestoneder nächste gesperrte Meilenstein, oder null
percentwie weit der Balken gefüllt ist
allUnlockedtrue, 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 ​

RouteWirkung
POST /store-api/ssd-unlock-bar/gift/{milestoneId}/choose mit giftOptionIdtauscht das Geschenk gegen eine andere Option (Pro)
POST /store-api/ssd-unlock-bar/gift/{milestoneId}/add-backfü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.

Your Vision. Signed, Sealed, Delivered.