Versandkostenfrei-Leiste (dffreeshipbar) — Vollständige Anleitung

Vollständige Anleitung zum Modul dffreeshipbar für PrestaShop 8 und 9: Installation, Schwellenwerte pro Land und Bundesland, Filterung nach Versanddienstleister, Anzeigepositionen, Multishop und Fehlerbehebung. Alle Auflösungsregeln sind dokumentiert, Grenzfälle inbegriffen.

Überblick

dffreeshipbar zeigt eine Fortschrittsleiste, die dem Kunden anzeigt, wie viel er noch ausgeben muss, um kostenlosen Versand zu erhalten. Ist der Schwellenwert erreicht, wechselt die Meldung zu einer Bestätigung.

Das Modul arbeitet mit eigenen Schwellenwerten, gespeichert in eigenen Tabellen. Es liest die native Einstellung PS_SHIPPING_FREE_PRICE zu keinem Zeitpunkt: Sie können sie auf 0 belassen und Ihren Gratisversand über Versandstaffeln steuern, ohne dass es zu Konflikten kommt.

Die Besonderheit des Moduls ist seine zweistufige Gebietsauflösung. Ein Schwellenwert lässt sich auf Länderebene festlegen, aber auch auf Ebene der PrestaShop-Bundesländer — so lassen sich Gebiete unterschiedlich behandeln, die verwaltungstechnisch demselben Land zugeordnet sind, etwa die Überseedepartements des französischen Mutterlandes.

Voraussetzungen

• PrestaShop 8.0 bis 9.x
• PHP mindestens 7.4 (8.0 bis 8.3 unterstützt)
• Classic, Hummingbird oder ein individuelles Theme, das die Standard-Hooks aufruft
• Administratorzugang zum Backoffice

Installation

1. Im Backoffice zu Module → Modulmanager → Modul hochladen gehen.
2. Die Datei dffreeshipbar-2.1.0.zip hochladen.
3. Auf Installieren und anschließend auf Konfigurieren klicken.

Bei der Installation legt das Modul zwei Tabellen an und registriert seine Hooks:

• PREFIX_dffreeshipbar_country — Schwellenwerte auf Länderebene, mit einer Spalte id_shop.
• PREFIX_dffreeshipbar_state — Schwellenwerte auf Bundeslandebene, mit einer Spalte id_shop.

Registrierte Hooks: displayHeader, displayBanner, displayNav2, displayNavFullWidth, displayShoppingCartFooter, displayCheckoutSummaryTop, actionCarrierUpdate.

Allgemeine Einstellungen

Der Konfigurationsbildschirm findet sich unter Module → DataFirefly – Versandkostenfrei-Leiste → Konfigurieren. Er besteht aus drei Bereichen: allgemeine Einstellungen, Versandregeln und Schwellenwerte nach Gebiet.

Globaler Standardschwellenwert

Zwei verknüpfte Einstellungen:

• Globalen Standardschwellenwert verwenden: steht der Schalter auf Nein, erscheint die Leiste nur in ausdrücklich konfigurierten Gebieten. Steht er auf Ja, erhält jedes nicht konfigurierte Gebiet den unten eingetragenen Betrag.
• Globaler Standardschwellenwert: der Betrag, der als letzte Instanz greift.

Lassen Sie den Standardwert deaktiviert, wenn Ihr Gratisversand nur wenige Ziele abdeckt. Aktivieren Sie ihn, wenn er universell gilt und Ausnahmen selten sind.

Berechnungsgrundlage

• Bruttosummen vergleichen: legt fest, ob die Warenkorbsumme mit oder ohne Steuern bewertet wird. Diese Einstellung muss zur Grundlage Ihrer Versandstaffeln passen, sonst weichen Leiste und Kasse voneinander ab.
• Warenkorbregeln in die Summe einbeziehen: ist dies aktiv, werden Rabatte vor dem Vergleich mit dem Schwellenwert abgezogen. Ein Warenkorb über 70 € mit einem Gutschein über 10 € wird dann mit 60 € bewertet.

Die bewertete Summe entspricht einem nativen Aufruf:

Cart::getOrderTotal(
    $with_taxes = (bool) DFFREESHIPBAR_TAX_INCL,
    $type = DFFREESHIPBAR_INCLUDE_DISCOUNTS
        ? Cart::BOTH_WITHOUT_SHIPPING
        : Cart::ONLY_PRODUCTS
);

Versandkosten und Geschenkverpackung zählen nie zum Fortschritt.

Lieferadresse voraussetzen

Solange der Kunde keine Adresse eingegeben hat, ist das Ziel nur eine Schätzung und das Bundesland unbekannt. Drei Modi:

• Nie: die Leiste erscheint bereits beim Stöbern im Katalog, basierend auf dem vermuteten Land.
• Für Länder mit Bundesländern (empfohlen): die Leiste bleibt überall sichtbar, außer in Ländern, deren Bundesländer abweichende Bedingungen haben können. Ein in Belgien vermuteter Besucher sieht die Leiste; ein in Frankreich vermuteter Besucher erst nach Eingabe einer Adresse, da sein Bundesland den tatsächlichen Schwellenwert bestimmt.
• Immer: nichts, solange keine Adresse am Warenkorb hängt.

Positionen und Erscheinungsbild

• Oben auf der Seite anzeigen: seitenweit sichtbares Banner.
• Im Warenkorb und an der Kasse anzeigen: Block im Moment der Entscheidung.
• Animation aktivieren: animierte Streifen während des Fortschritts. Die Animation wird für Besucher mit prefers-reduced-motion automatisch unterdrückt.
• Vier Farben: Hintergrund, Leiste, Text und Erfolgsmeldung.

Für die freie Platzierung im Theme implementiert das Modul WidgetInterface:

{widget name='dffreeshipbar'}
{widget name='dffreeshipbar' position='cart'}

Schwellenwerte nach Gebiet

Das ist der Kern des Moduls. Die Tabelle listet alle aktiven Länder des Shops auf und darunter, eingerückt, die Bundesländer jedes Landes, das welche besitzt.

Auflösungsreihenfolge

Für eine gegebene Lieferadresse sucht das Modul in dieser Reihenfolge und hält beim ersten Treffer an:

1. Das Bundesland der Adresse, sofern dafür eine Regel besteht.
2. Das Land der Adresse, sofern dafür eine Regel besteht.
3. Der globale Standardwert, sofern aktiviert.

Ergibt keiner dieser drei Schritte einen Betrag, wird die Leiste nicht angezeigt.

Kontrollkästchen und Betragsfeld: zwei verschiedene Wirkungen

Das ist der wichtigste Punkt der Konfiguration und der am häufigsten missverstandene:

• Kästchen nicht markiert → die Leiste ist für dieses Gebiet ausgeblendet. Es erbt weder vom übergeordneten Land noch vom globalen Wert. Die Auflösung endet hier.
• Kästchen markiert, Betrag leer → die Regel wird gelöscht, das Gebiet erbt von der übergeordneten Ebene.
• Kästchen markiert, Betrag eingetragen → dieser Betrag gilt.

Beispiel: nur Mutterland

Häufiger Fall eines französischen Shops, der ab 65 € im Mutterland und auf Korsika versandkostenfrei liefert, in Übersee jedoch nicht:

• Frankreich: markiert, Betrag 65.
• Korsika: markiert, Betrag leer — erbt die 65 € Frankreichs.
• Guadeloupe, Martinique, Französisch-Guayana, La Réunion, Mayotte: Markierung entfernt. Keine Leiste an diesen Zielen.
• Globaler Standardwert: deaktiviert, damit kein anderes Land versehentlich eine Leiste erhält.

Ein Kunde in Guadeloupe sieht das Versprechen also nie, obwohl seine Adresse in PrestaShop zum Land „Frankreich“ gehört.

Filter und Suche

Das Suchfeld filtert Länder und Bundesländer nach Namen. Das Kästchen Nur konfigurierte Gebiete anzeigen reduziert die Tabelle auf Zeilen mit bestehender Regel — nützlich in einem Shop, der hundert Länder beliefert.

Die beiden Speicherschaltflächen sind unabhängig: Länder speichern und Bundesländer speichern.

Versandregeln

Wenn Ihren Gratisversand nur bestimmte Versanddienstleister gewähren, schränken Sie die Anzeige entsprechend ein. Drei Modi:

• Alle Versanddienstleister: keine Filterung.
• Nur für die unten markierten Versanddienstleister anzeigen: Positivliste.
• Für die unten markierten Versanddienstleister ausblenden: Negativliste.

Vor der Versandauswahl

Der Versanddienstleister steht erst im Lieferschritt fest. Die Einstellung Vor der Versandauswahl legt fest, was davor geschieht:

• Anzeigen: die Leiste erscheint in Katalog und Warenkorb und verschwindet, wenn der Kunde einen ausgeschlossenen Dienstleister wählt.
• Ausblenden: die Leiste erscheint erst nach Auswahl eines zulässigen Dienstleisters.

Aktualisierung in Echtzeit

Die Leiste wird serverseitig neu berechnet und ohne Seitenneuladen bei jedem Warenkorbereignis aktualisiert: Hinzufügen, Entfernen, Mengenänderung, Adressänderung, Wechsel des Kassenschritts.

Das Skript lauscht auf die PrestaShop-Ereignisse updatedCart, updateCart, updatedAddressForm, changedCheckoutStep und updateDeliveryForm. Eine manuelle Aktualisierung lässt sich aus eigenem Code auslösen:

document.dispatchEvent(new Event('dffreeshipbar:refresh'));

Über die Sichtbarkeit entscheidet der Server: qualifiziert sich Gebiet oder Versanddienstleister nicht mehr, wird die Leiste aus dem DOM entfernt, statt mit einem veralteten Wert stehen zu bleiben.

Multishop

Die Schwellenwerte werden mit einer Spalte id_shop gespeichert. Jeder Shop hat somit eigene Land- und Bundeslandregeln, unabhängig voneinander.

Um einen bestimmten Shop zu konfigurieren, wählen Sie oben im Backoffice dessen Kontext, bevor Sie den Konfigurationsbildschirm öffnen. Der Schwellenwertbereich zeigt zur Erinnerung den Namen des aktuellen Shops.

Übersetzungen

Das Modul wird übersetzt in Deutsch, Französisch, Englisch, Spanisch, Italienisch und Polnisch ausgeliefert.

Um die kundenseitigen Texte anzupassen, zu International → Übersetzungen gehen, „Modulübersetzungen“ wählen, dffreeshipbar und die Sprache auswählen und die Domäne Modules.Dffreeshipbar.Shop suchen. Verfügbare Zeichenketten:

• „Nur noch %amount% bis zum kostenlosen Versand!“ — laufender Warenkorb.
• „Kostenloser Versand ab %amount%.“ — leerer Warenkorb.
• „Glückwunsch! Ihre Bestellung wird versandkostenfrei geliefert.“ — Schwellenwert erreicht.

Der Platzhalter %amount% wird durch den gemäß aktiver Währung und Locale formatierten Betrag ersetzt. Behalten Sie ihn in Ihren Übersetzungen bei.

Aktualisierung von Version 1.0

Die Aktualisierung erfolgt automatisch beim Austausch des ZIP. Die Upgrade-Skripte führen Folgendes aus:

• Anlegen der Bundesland-Tabelle.
• Umbenennen der Spalte active in enabled in der Ländertabelle. Ihre bestehenden Schwellenwerte bleiben erhalten.
• Der globale Standardwert wird aktiviert, falls Sie in 1.0 einen hatten, damit sich für Ihre Kunden nichts ändert.
• Der Adresspflicht-Modus wird auf Nie gesetzt, was dem Verhalten von 1.0 entspricht. Wechseln Sie auf den empfohlenen Modus, wenn Sie es entscheiden.

Fehlerbehebung

Die Leiste erscheint nirgends

1. Ist das Modul aktiviert? (Schalter Modul aktivieren).
2. Haben Sie mindestens ein Gebiet konfiguriert oder den globalen Standardwert aktiviert? Ohne eines von beiden erscheint die Leiste nie.
3. Steht die Adresspflicht auf Immer, während Sie ohne Lieferadresse testen?
4. Sind die Positionen aktiviert? (Banner und/oder Warenkorb).
5. Ruft Ihr Theme die verwendeten Hooks auf? Prüfen unter Module → Positionen. Bei einem individuellen Theme besser das Widget nutzen.

Die Leiste erscheint, wo sie nicht sollte

Der typische Fall ist ein Gebiet, das erbt, obwohl es ausgeschlossen sein sollte. Prüfen Sie, ob dessen Kästchen tatsächlich nicht markiert ist und nicht bloß der Betrag geleert wurde — beide Aktionen wirken gegensätzlich.

Der angezeigte Schwellenwert passt nicht zur Kasse

• Prüfen, ob Bruttosummen vergleichen zur Grundlage Ihrer Versandstaffeln passt.
• Die Einstellung zu Warenkorbregeln prüfen: ein rabattierter Warenkorb kann unter den Schwellenwert fallen.
• Das Modul liest Ihre Versandstaffeln nicht. Haben Sie eine Staffel geändert, tragen Sie den neuen Wert ins Modul nach.

Die Leiste aktualisiert sich nach dem Hinzufügen nicht

Die Aktualisierung stützt sich auf die JavaScript-Ereignisse von PrestaShop. Manche Themes oder Warenkorbmodule von Drittanbietern senden sie nicht. Zwei Prüfungen:

• Meldet die Browser-Konsole einen JavaScript-Fehler bei einer anderen Ressource? Ein blockierender Fehler weiter oben verhindert das Einrichten des Listeners.
• Sendet Ihr Ajax-Warenkorbmodul tatsächlich prestashop.emit('updatedCart')? Falls nicht, lösen Sie dffreeshipbar:refresh aus Ihrem Code aus.

Versandregeln scheinen ignoriert zu werden

Prüfen Sie, ob der gewählte Versanddienstleister der ist, den Sie vermuten: nach einer Tarifänderung legt PrestaShop einen neuen an. Das Modul folgt der Referenz, die Regel sollte also mitwandern — wurde der Dienstleister jedoch von Grund auf neu angelegt statt bearbeitet, ist seine Referenz neu und muss erneut markiert werden.

Deinstallation

Zu Module → Modulmanager → DataFirefly – Versandkostenfrei-Leiste → Deinstallieren gehen. Die Deinstallation entfernt beide Schwellenwerttabellen und alle Konfigurationsschlüssel mit dem Präfix DFFREESHIPBAR_.

Kurze FAQ

• Liest das Modul PS_SHIPPING_FREE_PRICE? Nie. Sie können sie auf 0 belassen und den Gratisversand über Versandstaffeln steuern.
• Liest das Modul meine Versandstaffeln, um den Schwellenwert abzuleiten? Nein. Die Schwellenwerte werden manuell eingetragen. Eine automatische Synchronisation aus den Staffeln ist als Individualentwicklung möglich.
• Mein Gratisversand hängt auch vom Gewicht ab. Wird das berücksichtigt? Nein, das Modul misst nur einen Betrag. Eine Gewichtsbedingung ist Individualentwicklung.
• Kann ich die Leiste außerhalb der angebotenen Positionen anzeigen? Ja, über {widget name='dffreeshipbar'} in jedem Template.
• Funktioniert das Modul mit dem Hummingbird-Theme? Ja. Die Hooks displayNavFullWidth und displayCheckoutSummaryTop sind dafür registriert, und das Widget deckt individuelle Platzierungen ab.
• Sind die Schwellenwerte pro Shop unabhängig? Ja, jede Zeile trägt eine id_shop.

Support und Aktualisierungen

Das Modul umfasst 12 Monate Updates und Support ab Kaufdatum. E-Mail-Support auf Französisch oder Englisch, Antwort innerhalb von 24 Werkstunden.

Bei Fragen oder Auffälligkeiten wenden Sie sich an den DataFirefly-Support und geben Sie an:

• PrestaShop- und PHP-Version
• Installierte Modulversion
• Verwendetes Theme
• Betroffenes Gebiet und betroffener Versanddienstleister
• Beobachtetes gegenüber erwartetem Verhalten