Versandkostenfrei-Leiste (dffreeshipbar): vollständige Anleitung

Vollständige Anleitung zum Modul dffreeshipbar 2.3.0 für PrestaShop 8 und 9: Installation, Schwellenwerte pro Land und Bundesland, Anzeigepositionen (einschließlich Produktseite und Warenkorb-Seitenleiste von Creative Elements), Meldungen, Erscheinungsbild, Versanddienstleister, Mehrwährung und Fehlerbehebung.

Ü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 in eigenen Tabellen. Es liest die native Einstellung PS_SHIPPING_FREE_PRICE nie: Sie können sie auf 0 belassen und den Gratisversand konfliktfrei über Versandstaffeln steuern.

Seine Besonderheit ist die zweistufige Gebietsauflösung: Ein Schwellenwert lässt sich pro Land und pro PrestaShop-Bundesland festlegen. Gebiete, die demselben Land angehören, etwa die Überseedepartements Frankreichs, lassen sich so unterschiedlich behandeln.

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
• Creative Elements (optional) für die Position in der Warenkorb-Seitenleiste

Installation

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

Das Modul legt zwei Tabellen an (PREFIX_dffreeshipbar_country und PREFIX_dffreeshipbar_state, jeweils mit einer Spalte id_shop) und registriert die Hooks displayHeader, displayBanner, displayNav2, displayNavFullWidth, displayShoppingCartFooter, displayCheckoutSummaryTop, displayProductAdditionalInfo, displayCEShoppingCartFooter und actionCarrierUpdate.

Der Konfigurationsbildschirm

Der Bildschirm befindet sich unter Module → DataFirefly – Versandkostenfrei-Leiste → Konfigurieren. Oben zeigt eine Übersichtsleiste den Modulstatus, die Anzahl der Gebiete mit Schwellenwert und der ausgeschlossenen Gebiete, den Standardwert, die Versandfilterung und die aktiven Positionen. Jede Kachel öffnet den passenden Reiter.

Die Konfiguration verteilt sich auf fünf Reiter: Allgemein, Gebiete, Versanddienstleister, Meldungen und Erscheinungsbild. Der aktive Reiter bleibt nach dem Speichern erhalten.

Reiter Allgemein

Globaler Standardwert

• Globalen Standardschwellenwert verwenden: auf Nein erscheint die Leiste nur in konfigurierten Gebieten. Auf Ja erhält jedes nicht konfigurierte Gebiet den eingetragenen Betrag.
• Globaler Standardschwellenwert: der Betrag, der als letzte Instanz greift.

Mehrwährung

Alle Beträge des Moduls werden in der Standardwährung des Shops eingegeben. Für einen Besucher, der in einer anderen Währung zahlt, wird der Schwellenwert zum Wechselkurs von PrestaShop umgerechnet, bevor er mit seinem Warenkorb verglichen wird, und die angezeigten Beträge werden in seiner Währung formatiert.

Lieferadresse voraussetzen

Vor der Eingabe einer Adresse ist das Ziel nur eine Schätzung und das Bundesland unbekannt. Drei Modi:

• Nie: die Leiste erscheint schon beim Stöbern, 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; dort wartet sie auf die Adresse.
• Immer: nichts, solange keine Adresse am Warenkorb hängt.

Berechnungsgrundlage

• Bruttosummen vergleichen: muss zur Grundlage Ihrer Versandstaffeln passen, sonst weichen Leiste und Kasse voneinander ab.
• Warenkorbregeln in die Summe einbeziehen: ein Warenkorb über 70 € mit einem Gutschein über 10 € wird dann mit 60 € bewertet.

Versandkosten zählen nie zum Fortschritt.

Kundengruppen

Ohne markiertes Kästchen sehen alle Kunden die Leiste. Markieren Sie Gruppen, um sie ihnen vorzubehalten, etwa Privatkunden, wenn für Gewerbekunden andere Versandbedingungen gelten. Ein nicht angemeldeter Besucher gehört zur Gruppe „Besucher“.

Ausblenden, solange der Warenkorb leer ist

Die Leiste erscheint mit dem ersten hinzugefügten Artikel. Auf der Produktseite bleibt sie in jedem Fall, denn dort entscheidet der Kunde über das Hinzufügen.

Anzeigepositionen

• Seitenanfang: seitenweit sichtbares Banner.
• Produktseite: siehe eigener Abschnitt unten.
• Warenkorb und Kasse: Block auf der Warenkorbseite und im Bestellvorgang.
• Warenkorb-Seitenleiste von Creative Elements: siehe eigener Abschnitt unten.

Für die freie Platzierung implementiert das Modul WidgetInterface:

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

Die Leiste auf der Produktseite

Die Leiste erscheint unter der Schaltfläche „In den Warenkorb“ (Hook displayProductAdditionalInfo). Zusätzlich zum aktuellen Fortschritt zeigt eine Zeile die Wirkung des angezeigten Artikels:

• reicht der Artikel für den Schwellenwert: „Mit diesem Artikel wird Ihre Bestellung versandkostenfrei geliefert“;
• andernfalls: „Mit diesem Artikel fehlen nur noch 2,50 € bis zum kostenlosen Versand“.

Die Berechnung nutzt den Preis der gewählten Variante mal die eingegebene Menge, auf derselben Steuerbasis wie der Warenkorb und mit den spezifischen Preisen des Kunden. Sie läuft neu, wenn der Kunde Variante oder Menge ändert.

Die Warenkorb-Seitenleiste von Creative Elements

In einem Shop, dessen Header mit Creative Elements gebaut ist, fügt sich die Leiste in die Seitenleiste des Widgets Warenkorb im Skin Sidebar ein, über den Hook displayCEShoppingCartFooter, den dieses Widget ausführt. Der Skin Classic öffnet keine Seitenleiste.

Die Einstellung Position in der Warenkorb-Seitenleiste bietet drei Stellen: unter dem Titel, über der Zusammenfassung oder über den Bestellschaltflächen.

Die Leiste aktualisiert sich per Ajax bei jedem Hinzufügen und bei jedem Entfernen aus der Seitenleiste, ohne Neuladen, und der Balken gleitet vom vorherigen Wert. Creative Elements baut nur die Artikelliste und die Zusammenfassung neu auf: Die Leiste bleibt zwischen zwei Aktualisierungen an ihrem Platz.

Reiter Gebiete

Die Tabelle listet alle aktiven Länder des Shops und darunter, eingerückt, die Bundesländer jedes Landes, das welche besitzt. Ein Suchfeld und ein Filter für konfigurierte Gebiete erleichtern die Navigation. Die Beträge sind in der Standardwährung.

Auflösungsreihenfolge

Für eine Lieferadresse sucht das Modul in dieser Reihenfolge und hält beim ersten Treffer an: das Bundesland der Adresse, dann das Land, dann der globale Standardwert, sofern aktiviert. Ohne Treffer wird die Leiste nicht angezeigt.

Kontrollkästchen und Betrag: zwei verschiedene Wirkungen

• Kästchen nicht markiert: die Leiste ist für dieses Gebiet ausgeblendet, ohne Vererbung vom Land oder vom Standardwert.
• 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

• Frankreich: markiert, Betrag 65.
• Korsika: markiert, Betrag leer; es erbt die 65 €.
• Guadeloupe, Martinique, Französisch-Guayana, La Réunion, Mayotte: nicht markiert.
• Globaler Standardwert: deaktiviert.

Reiter Versanddienstleister

Drei Modi: alle Dienstleister, Anzeige nur für markierte Dienstleister oder Ausblenden für markierte Dienstleister. Die Regeln werden anhand der id_reference gespeichert: PrestaShop legt bei jeder Bearbeitung einen neuen Dienstleister an, die Referenz bleibt jedoch stabil.

Die Einstellung Vor der Versandauswahl legt fest, ob die Leiste in Katalog und Warenkorb erscheint, solange noch kein Dienstleister gewählt ist.

Reiter Meldungen

Fünf Meldungen lassen sich für jede aktive Sprache anpassen:

• Leerer Warenkorb (Standard: „Kostenloser Versand ab {threshold}.“)
• Warenkorb in Bearbeitung (Standard: „Nur noch {amount} bis zum kostenlosen Versand!“)
• Schwellenwert erreicht
• Produktseite: dieser Artikel schaltet den Gratisversand frei
• Produktseite: Restbetrag nach Hinzufügen des Artikels

Zwei Platzhalter stehen zur Verfügung: {amount} für den fehlenden Betrag und {threshold} für den Schwellenwert. Sie werden durch den in der Währung des Besuchers formatierten Betrag in Fettschrift ersetzt. Der Text wird unverändert angezeigt: eingegebenes HTML wird nicht interpretiert. Ein leeres Feld behält den mitgelieferten übersetzten Text.

Reiter Erscheinungsbild

• Farben: Hintergrund, Leiste, Text und Erfolgsmeldung, mit Farbwähler und synchronisiertem Hexadezimalfeld.
• Symbol: LKW, Paket, Geschenk oder keines. Die Symbole sind SVG, und ein Haken ersetzt das Symbol, sobald der Schwellenwert erreicht ist.
• Animation: bewegte Streifen während des Fortschritts, automatisch aus für Besucher, die in ihrem System reduzierte Bewegung eingestellt haben.
• Schließbares Banner: fügt dem Banner oben auf der Seite eine Schließen-Schaltfläche hinzu. Einmal geschlossen, bleibt es bis zum Schließen des Browsers ausgeblendet. Die übrigen Positionen sind nicht betroffen.

Eine Live-Vorschau zeigt Banner, Produktseite und erreichten Schwellenwert und aktualisiert sich bei jeder Änderung vor dem Speichern.

Aktualisierung in Echtzeit

Jede Position gibt einen Container aus, auch wenn die Leiste nichts anzuzeigen hat. Nach einem Ereignis zu Warenkorb, Adresse, Kassenschritt, Variante oder Menge holt eine einzige Anfrage die Leiste für alle Positionen der Seite, und jeder Container wird an Ort und Stelle gefüllt oder geleert. Eine beim Laden ausgeblendete Leiste kann so ohne Neuladen erscheinen und umgekehrt.

Das Skript lauscht auf die PrestaShop-Ereignisse updateCart, updatedCart, updatedAddressForm, changedCheckoutStep, updateDeliveryForm und updatedProduct. Eine Aktualisierung aus eigenem Code lösen Sie so aus:

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

Multishop und Übersetzungen

Die Schwellenwerte tragen eine id_shop: jeder Shop hat eigene Regeln. Wählen Sie oben im Backoffice den Shop-Kontext, bevor Sie die Konfiguration öffnen.

Das Modul wird übersetzt in Deutsch, Französisch, Englisch, Spanisch, Italienisch und Polnisch ausgeliefert. Für die kundenseitigen Texte genügt in den meisten Fällen der Reiter Meldungen.

Update von einer früheren Version

Der Austausch des ZIP führt die Migrationsskripte automatisch aus. Ihre Schwellenwerte bleiben erhalten. Die neuen Optionen starten in einem bestehenden Shop deaktiviert: Produktseite, Ausblenden bei leerem Warenkorb, schließbares Banner und Gruppeneinschränkung. Von früheren Versionen gespeicherte Farben werden auf #rrggbb normalisiert, und die Smarty- und Opcache-Caches werden geleert.

Fehlerbehebung

Die Leiste erscheint nirgends

1. Meldet die Übersichtsleiste, dass kein Gebiet einen Schwellenwert hat?
2. Sind das Modul und die gewünschten Positionen aktiviert?
3. Steht die Adresspflicht auf Immer, während Sie ohne Adresse testen?
4. Sind Kundengruppen markiert, zu denen Ihr Testkonto nicht gehört?
5. Ist „Ausblenden, solange der Warenkorb leer ist“ bei leerem Warenkorb aktiv?

Die Leiste erscheint, wo sie nicht sollte

Prüfen Sie, ob das Kästchen des Gebiets tatsächlich nicht markiert ist und nicht bloß der Betrag geleert wurde.

Nichts in der Seitenleiste von Creative Elements

• Das Warenkorb-Widget muss den Skin Sidebar verwenden.
• „In der Warenkorb-Seitenleiste von Creative Elements anzeigen“ muss aktiviert sein.
• Nach einem Update von 2.1.0 oder älter den Cache unter Erweiterte Einstellungen → Leistung leeren.

Der Betrag passt nicht zur Kasse

• Die Steuereinstellung muss zur Grundlage Ihrer Versandstaffeln passen.
• Ein Gutschein kann den Warenkorb wieder unter den Schwellenwert bringen.
• Das Modul liest Ihre Staffeln nicht: tragen Sie jede Staffeländerung im Modul nach.

Die Leiste aktualisiert sich nach dem Hinzufügen nicht

Die Aktualisierung stützt sich auf die JavaScript-Ereignisse von PrestaShop. Sendet ein Warenkorbmodul eines Drittanbieters sie nicht, lösen Sie dffreeshipbar:refresh aus dessen Code aus. Prüfen Sie auch die Konsole: Ein JavaScript-Fehler weiter oben verhindert das Einrichten des Listeners.

Deinstallation

Die Deinstallation entfernt beide Schwellenwerttabellen und alle Konfigurationsschlüssel mit dem Präfix DFFREESHIPBAR_, einschließlich der Meldungen. Exportieren Sie beide Tabellen, wenn Sie eine Neuinstallation planen.

Kurze FAQ

• Liest das Modul PS_SHIPPING_FREE_PRICE? Nie.
• Liest das Modul meine Versandstaffeln? Nein, die Schwellenwerte werden manuell eingetragen. Eine automatische Synchronisation ist als Individualentwicklung möglich.
• Mein Gratisversand hängt auch vom Gewicht ab. Wird das berücksichtigt? Nein, das Modul misst nur einen Betrag.
• Kann ich Fettschrift oder einen Link in eine Meldung setzen? Nein, der Text wird maskiert. Die Beträge der Platzhalter werden automatisch fett gesetzt.
• Kommt ein geschlossenes Banner zurück? Beim nächsten Öffnen des Browsers.

Support und Aktualisierungen

Das Modul umfasst 12 Monate Updates und Support. E-Mail-Support auf Französisch oder Englisch, Antwort innerhalb von 24 Werkstunden. Wenden Sie sich an den DataFirefly-Support mit Ihren Versionen von PrestaShop, PHP und Modul, dem verwendeten Theme sowie dem betroffenen Gebiet und Versanddienstleister.