Gratisverzendingsbalk (dffreeshipbar) — Complete handleiding

Complete handleiding voor de module dffreeshipbar voor PrestaShop 8 en 9: installatie, drempels per land en per staat, filtering per vervoerder, weergaveposities, multistore en probleemoplossing. Alle resolutieregels worden gedetailleerd behandeld, inclusief de randgevallen.

Overzicht

dffreeshipbar toont een voortgangsbalk die de klant laat zien hoeveel hij nog moet besteden om gratis verzending te krijgen. Zodra de drempel is bereikt, schakelt het bericht over op een bevestiging.

De module werkt met haar eigen drempels, opgeslagen in haar tabellen. Ze raadpleegt op geen enkel moment de native variabele PS_SHIPPING_FREE_PRICE: u kunt die op 0 laten staan en uw franco verzending via vervoerderstranches sturen zonder enig conflict.

Het bijzondere aan de module is haar territoriale resolutie op twee niveaus. Een drempel kan op landniveau worden gedefinieerd, maar ook op het niveau van de PrestaShop-staat, wat het mogelijk maakt om gebieden die administratief bij hetzelfde land horen verschillend te behandelen, zoals de Franse overzeese departementen die bij Frankrijk horen.

Vereisten

• PrestaShop 8.0 tot 9.x
• Minimaal PHP 7.4 (8.0 tot 8.3 ondersteund)
• Classic-thema, Hummingbird of aangepast thema dat de standaardhooks aanroept
• Beheerderstoegang tot de backoffice

Installatie

1. Ga in de backoffice naar Modules → Modulebeheer → Een module uploaden.
2. Upload het bestand dffreeshipbar-2.1.0.zip.
3. Klik op Installeren en vervolgens op Configureren.

Bij de installatie maakt de module twee tabellen aan en registreert haar hooks:

• PREFIX_dffreeshipbar_country: drempels op landniveau, met een kolom id_shop.
• PREFIX_dffreeshipbar_state: drempels op staatniveau, met een kolom id_shop.

Geregistreerde hooks: displayHeader, displayBanner, displayNav2, displayNavFullWidth, displayShoppingCartFooter, displayCheckoutSummaryTop, actionCarrierUpdate.

Algemene configuratie

Het configuratiescherm vindt u in Modules → DataFirefly – Gratisverzendingsbalk → Configureren. Het bestaat uit drie panelen: algemene instellingen, vervoerdersregels, drempels per gebied.

Globale fallbackdrempel

Twee gekoppelde instellingen:

• Een globale standaarddrempel gebruiken: staat deze schakelaar op Nee, dan verschijnt de balk alleen in expliciet geconfigureerde gebieden. Staat hij op Ja, dan krijgt elk niet-geconfigureerd gebied het hieronder ingevoerde bedrag.
• Globale standaarddrempel: het bedrag dat in laatste instantie wordt toegepast.

Laat de fallback uitgeschakeld als uw franco verzending slechts enkele bestemmingen dekt. Schakel hem in als uw franco universeel is en de uitzonderingen zeldzaam zijn.

Berekeningsbasis

• Totalen inclusief btw vergelijken: bepaalt of het winkelwagentotaal inclusief of exclusief btw wordt beoordeeld. Deze instelling moet overeenkomen met de basis van uw vervoerderstranches, anders tonen de balk en het bestelproces afwijkende resultaten.
• Kortingsbonnen meenemen in het totaal: wanneer deze schakelaar actief is, worden de winkelwagenkortingen afgetrokken vóór de vergelijking met de drempel. Een winkelwagen van 70 € met een bon van 10 € wordt dan beoordeeld op 60 €.

Het beoordeelde totaal komt overeen met een native aanroep:

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

De verzendkosten en de cadeauverpakking worden nooit in de voortgang meegeteld.

Een verzendadres vereisen

Zolang de klant geen adres heeft ingevuld, is de bestemming slechts een schatting en blijft de staat onbekend. Drie modi:

• Nooit: de balk verschijnt al bij het browsen door de catalogus, op basis van het geschatte land.
• Voor landen met staten (aanbevolen): de balk blijft overal zichtbaar, behalve in landen waarvan de staten verschillende voorwaarden kunnen hebben. Een bezoeker die in België wordt geschat ziet de balk; een bezoeker die in Frankrijk wordt geschat ziet haar pas na het invoeren van een adres, aangezien zijn staat de werkelijke drempel bepaalt.
• Altijd: niets zolang er geen adres aan de winkelwagen is gekoppeld.

Posities en uiterlijk

• Bovenaan de pagina tonen: banner zichtbaar op de hele site.
• Tonen op winkelwagen en bestelling: blok getoond op het beslismoment.
• Animatie inschakelen: geanimeerde strepen op de balk tijdens de voortgang. De animatie wordt automatisch uitgeschakeld voor bezoekers met prefers-reduced-motion.
• Vier kleuren: achtergrond, balk, tekst, succesboodschap.

Voor een vrije plaatsing in uw thema implementeert de module WidgetInterface:

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

Drempels per gebied

Dit is het hart van de module. De tabel toont alle actieve landen van de winkel, en onder elk land met staten diens staten ingesprongen.

Resolutievolgorde

Voor een gegeven verzendadres zoekt de module in deze volgorde en stopt bij het eerste resultaat:

1. De staat van het adres, als er een regel voor bestaat.
2. Het land van het adres, als er een regel voor bestaat.
3. De globale fallbackdrempel, als die is ingeschakeld.

Als geen van deze drie stappen een bedrag oplevert, wordt de balk niet getoond.

Selectievakje en bedragveld: twee verschillende effecten

Dit is het belangrijkste punt van de configuratie, en het meest misbegrepen:

• Vakje uitgevinkt → de balk wordt voor dit gebied verborgen. Het erft niet van het bovenliggende land en niet van de globale drempel. De resolutie stopt daar.
• Vakje aangevinkt, bedrag leeg → de regel wordt verwijderd, het gebied erft van het hogere niveau.
• Vakje aangevinkt, bedrag ingevuld → dat bedrag is van toepassing.

Voorbeeld: franco alleen op het vasteland

Veelvoorkomend geval van een Franse winkel die vanaf 65 € gratis verzendt op het vasteland en Corsica, maar niet overzee:

• Frankrijk: vakje aangevinkt, bedrag 65.
• Corsica: vakje aangevinkt, bedrag leeg: erft de 65 € van Frankrijk.
• Guadeloupe, Martinique, Guyana, Réunion, Mayotte: vakjes uitgevinkt. Geen balk voor deze bestemmingen.
• Globale fallbackdrempel: uitgeschakeld, zodat geen enkel ander land per ongeluk een balk krijgt.

Een klant uit Guadeloupe ziet de francobelofte dus nooit, hoewel zijn adres in PrestaShop aan het land “Frankrijk” is gekoppeld.

Filter en zoeken

Het zoekveld filtert landen en staten op naam. Het vakje Alleen geconfigureerde gebieden tonen beperkt de tabel tot de regels die al een regel hebben, handig voor een winkel die in honderd landen levert.

De twee opslagknoppen zijn onafhankelijk: Landen opslaan en Staten opslaan.

Vervoerdersregels

Als uw franco alleen door bepaalde vervoerders wordt aangeboden, beperkt u de weergave dienovereenkomstig. Drie modi:

• Alle vervoerders: geen filtering.
• Alleen tonen voor de aangevinkte vervoerders: whitelist.
• Verbergen voor de aangevinkte vervoerders: blacklist.

Vóór de keuze van de vervoerder

De vervoerder is pas bekend bij de verzendstap. De instelling Vóór selectie van de vervoerder bepaalt wat er vóór dat moment gebeurt:

• Tonen: de balk verschijnt op de catalogus en de winkelwagen, en verdwijnt als de klant een uitgesloten vervoerder kiest.
• Verbergen: de balk verschijnt pas zodra een in aanmerking komende vervoerder is geselecteerd.

Realtime bijwerking

De balk wordt aan serverzijde herberekend en zonder paginaherlading ververst bij elke winkelwagengebeurtenis: toevoegen, verwijderen, hoeveelheidswijziging, adreswijziging, stapwijziging in het bestelproces.

Het script luistert naar de PrestaShop-events updatedCart, updateCart, updatedAddressForm, changedCheckoutStep en updateDeliveryForm. U kunt vanuit uw eigen code een handmatige verversing triggeren:

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

De server beslist over de zichtbaarheid: als het gebied of de vervoerder niet meer kwalificeert, wordt de balk uit de DOM verwijderd in plaats van met een verouderde waarde te blijven staan.

Multistore

De drempels worden opgeslagen met een kolom id_shop. Elke winkel heeft dus haar eigen land- en staatregels, onafhankelijk van elkaar.

Om een bepaalde winkel te configureren, selecteert u haar context bovenaan de backoffice voordat u het configuratiescherm opent. Het drempelpaneel toont ter herinnering de naam van de huidige winkel.

Vertalingen

De module wordt geleverd met vertalingen in het Frans, Engels, Duits, Spaans, Italiaans en Pools.

Om de aan klantzijde getoonde teksten aan te passen, gaat u naar Internationaal → Vertalingen, selecteert u “Modulevertalingen”, kiest u dffreeshipbar en de taal, en zoekt u het domein Modules.Dffreeshipbar.Shop. De beschikbare strings:

• “Nog %amount% te gaan voor gratis verzending!”: winkelwagen in opbouw.
• “Gratis verzending vanaf %amount%.”: lege winkelwagen.
• “Gefeliciteerd! Uw bestelling komt in aanmerking voor gratis verzending.”: drempel bereikt.

Het token %amount% wordt vervangen door het bedrag, geformatteerd volgens de actieve valuta en locale. Behoud het in uw vertalingen.

Updaten vanaf versie 1.0

De update verloopt automatisch bij het vervangen van de ZIP. De upgradescripts voeren de volgende operaties uit:

• Aanmaken van de statentabel.
• Hernoemen van de kolom active naar enabled in de landentabel. Uw bestaande drempels blijven behouden.
• De globale fallbackdrempel wordt ingeschakeld als u er in 1.0 een had, om niet te wijzigen wat uw klanten zien.
• De adresvereistemodus wordt op Nooit gezet, wat overeenkomt met het gedrag van versie 1.0. Zet hem op de aanbevolen modus wanneer u dat wilt.

Probleemoplossing

De balk verschijnt nergens

1. Is de module ingeschakeld? (schakelaar Module inschakelen).
2. Hebt u minstens één gebied geconfigureerd, of de globale fallbackdrempel ingeschakeld? Zonder het een of het ander verschijnt de balk nooit.
3. Staat de adresvereistemodus op Altijd terwijl u zonder verzendadres test?
4. Zijn de posities ingeschakeld? (banner en/of winkelwagen).
5. Roept uw thema de gebruikte hooks aan? Controleer in Modules → Posities. Gebruik bij een aangepast thema liever de widget.

De balk verschijnt waar ze niet zou moeten

Het typische geval is een gebied dat erft terwijl het uitgesloten zou moeten zijn. Controleer of het vakje van het gebied daadwerkelijk is uitgevinkt, en niet alleen dat het bedrag is leeggemaakt: de twee acties hebben tegengestelde effecten.

De getoonde drempel komt niet overeen met de checkout

• Controleer of de instelling Totalen inclusief btw vergelijken overeenkomt met de basis van uw vervoerderstranches.
• Controleer de instelling voor kortingsbonnen: een winkelwagen met korting kan onder de drempel zakken.
• De module leest uw vervoerderstranches niet. Als u een tranche hebt gewijzigd, neem de nieuwe waarde dan over in de module.

De balk wordt niet bijgewerkt na een toevoeging aan de winkelwagen

De verversing steunt op de JavaScript-events van PrestaShop. Sommige thema’s of winkelwagenmodules van derden sturen ze niet uit. Twee controles:

• Meldt de browserconsole een JavaScript-fout op een andere resource? Een blokkerende fout stroomopwaarts verhindert dat de listener wordt geïnstalleerd.
• Stuurt uw ajax-winkelwagenmodule daadwerkelijk prestashop.emit('updatedCart') uit? Zo niet, trigger dan dffreeshipbar:refresh vanuit uw code.

De vervoerdersregels lijken genegeerd te worden

Controleer of de geselecteerde vervoerder daadwerkelijk degene is die u denkt: na een tariefwijziging maakt PrestaShop een nieuwe vervoerder aan. De module volgt de referentie, dus de regel zou moeten meegaan, maar als de vervoerder van nul opnieuw is aangemaakt in plaats van gewijzigd, is zijn referentie nieuw en moet u hem opnieuw aanvinken.

Deïnstallatie

Ga naar Modules → Modulebeheer → DataFirefly – Gratisverzendingsbalk → Deïnstalleren. De deïnstallatie verwijdert de twee drempeltabellen en alle configuratiesleutels met het voorvoegsel DFFREESHIPBAR_.

Snelle FAQ

• Leest de module PS_SHIPPING_FREE_PRICE? Nee, nooit. U kunt haar op 0 laten staan en uw franco via vervoerderstranches beheren.
• Leest de module mijn vervoerderstranches om er de drempel uit af te leiden? Nee. De drempels worden handmatig ingevoerd. Een automatische synchronisatie vanuit de tranches is mogelijk als maatwerkontwikkeling.
• Mijn franco hangt ook af van het gewicht. Wordt dat ondersteund? Nee, de module meet alleen een bedrag. Een gewichtsvoorwaarde valt onder maatwerkontwikkeling.
• Kan ik de balk elders tonen dan op de voorgestelde posities? Ja, via {widget name='dffreeshipbar'} in elk template.
• Werkt de module met het Hummingbird-thema? Ja. De hooks displayNavFullWidth en displayCheckoutSummaryTop zijn ervoor geregistreerd, en de widget dekt de aangepaste plaatsingen.
• Zijn de drempels onafhankelijk per winkel? Ja, elke regel draagt een id_shop.

Support en updates

De module bevat 12 maanden updates en support vanaf de aankoopdatum. Support per e-mail in het Frans of het Engels, antwoord binnen 24 werkuren.

Neem voor vragen of problemen contact op met de DataFirefly-support en vermeld:

• Versie van PrestaShop en PHP
• Geïnstalleerde moduleversie
• Gebruikt thema
• Gebied en vervoerder waarop het waargenomen gedrag betrekking heeft
• Beschrijving van het waargenomen versus het verwachte gedrag