Pasek darmowej dostawy (dffreeshipbar): kompletny przewodnik

Kompletny przewodnik po module dffreeshipbar 2.3.0 dla PrestaShop 8 i 9: instalacja, progi dla krajów i regionów, pozycje wyświetlania (w tym strona produktu i wysuwany koszyk Creative Elements), komunikaty, wygląd, przewoźnicy, wiele walut i rozwiązywanie problemów.

Przegląd

dffreeshipbar wyświetla pasek postępu informujący klienta, ile jeszcze musi wydać, aby otrzymać darmową dostawę. Po osiągnięciu progu komunikat zmienia się w potwierdzenie.

Moduł działa na własnych progach, zapisanych we własnych tabelach. Nigdy nie odczytuje natywnej zmiennej PS_SHIPPING_FREE_PRICE: możesz zostawić ją na 0 i sterować darmową dostawą przez przedziały przewoźnika bez konfliktów.

Wyróżnikiem jest dwupoziomowe ustalanie progu według terytorium: próg można zdefiniować dla kraju i dla regionu PrestaShop. Terytoria przypisane do tego samego kraju, na przykład departamenty zamorskie Francji, można więc traktować odmiennie.

Wymagania

• PrestaShop od 8.0 do 9.x
• PHP minimum 7.4 (obsługiwane 8.0 – 8.3)
• Motyw Classic, Hummingbird lub motyw własny wywołujący standardowe hooki
• Creative Elements (opcjonalnie) dla pozycji wysuwanego koszyka

Instalacja

1. W panelu przejdź do Moduły → Menedżer modułów → Wgraj moduł.
2. Wgraj plik dffreeshipbar-2.3.0.zip.
3. Kliknij Zainstaluj, a następnie Konfiguruj.

Moduł tworzy dwie tabele (PREFIX_dffreeshipbar_country i PREFIX_dffreeshipbar_state, każda z kolumną id_shop) i rejestruje hooki displayHeader, displayBanner, displayNav2, displayNavFullWidth, displayShoppingCartFooter, displayCheckoutSummaryTop, displayProductAdditionalInfo, displayCEShoppingCartFooter oraz actionCarrierUpdate.

Ekran konfiguracji

Ekran znajduje się w Moduły → DataFirefly – Pasek darmowej dostawy → Konfiguruj. U góry pasek podsumowania pokazuje stan modułu, liczbę terytoriów z progiem i wykluczonych, próg zapasowy, filtrowanie przewoźników i aktywne pozycje. Każdy kafelek otwiera odpowiednią zakładkę.

Konfiguracja jest podzielona na pięć zakładek: Ogólne, Terytoria, Przewoźnicy, Komunikaty i Wygląd. Aktywna zakładka pozostaje wybrana po zapisaniu.

Zakładka Ogólne

Globalny próg zapasowy

• Użyj globalnego progu domyślnego: w pozycji Nie pasek pojawia się tylko w skonfigurowanych terytoriach. W pozycji Tak każde nieskonfigurowane terytorium otrzymuje wpisaną kwotę.
• Globalny próg domyślny: kwota stosowana w ostateczności.

Wiele walut

Wszystkie kwoty modułu wprowadza się w walucie domyślnej sklepu. Dla odwiedzającego płacącego w innej walucie próg jest przeliczany po kursie PrestaShop przed porównaniem z jego koszykiem, a wyświetlane kwoty są formatowane w jego walucie.

Wymagaj adresu dostawy

Przed podaniem adresu miejsce dostawy jest tylko szacunkiem, a region pozostaje nieznany. Trzy tryby:

• Nigdy: pasek pojawia się podczas przeglądania, na podstawie szacowanego kraju.
• Dla krajów z regionami (zalecane): pasek pozostaje widoczny wszędzie poza krajami, których regiony mogą mieć odmienne warunki; tam czeka na adres.
• Zawsze: nic, dopóki koszyk nie ma adresu.

Podstawa obliczeń

• Porównuj kwoty brutto: musi odpowiadać podstawie przedziałów przewoźnika, inaczej pasek i kasa będą się różnić.
• Uwzględnij reguły koszyka w sumie: koszyk o wartości 70 € z bonem 10 € jest wtedy liczony jako 60 €.

Koszty dostawy nigdy nie wliczają się do postępu.

Grupy klientów

Bez zaznaczonych pól wszyscy klienci widzą pasek. Zaznacz grupy, aby zarezerwować go dla nich, np. dla klientów indywidualnych, gdy firmy mają inne warunki dostawy. Niezalogowany odwiedzający należy do grupy „Gość”.

Ukryj, gdy koszyk jest pusty

Pasek pojawia się po dodaniu pierwszego produktu. Na stronie produktu jest widoczny zawsze, ponieważ tam klient decyduje o dodaniu.

Pozycje wyświetlania

• Góra strony: baner widoczny w całym serwisie.
• Strona produktu: zob. osobną sekcję poniżej.
• Koszyk i zamówienie: blok na stronie koszyka i w procesie zamówienia.
• Wysuwany koszyk Creative Elements: zob. osobną sekcję poniżej.

Do dowolnego umieszczenia moduł implementuje WidgetInterface:

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

Pasek na stronie produktu

Pasek pojawia się pod przyciskiem dodania do koszyka (hook displayProductAdditionalInfo). Oprócz bieżącego postępu linia informuje o wpływie dodania wyświetlanego produktu:

• jeśli produkt wystarcza do osiągnięcia progu: „Dodaj ten produkt, a dostawa będzie darmowa”;
• w przeciwnym razie: „Z tym produktem do darmowej dostawy zabraknie tylko 2,50 €”.

Obliczenie wykorzystuje cenę wybranego wariantu pomnożoną przez wpisaną ilość, na tej samej podstawie podatkowej co koszyk i z cenami specyficznymi klienta. Powtarza się przy zmianie wariantu lub ilości.

Wysuwany koszyk Creative Elements

W sklepie, którego nagłówek zbudowano w Creative Elements, pasek wpasowuje się w boczny koszyk widżetu Koszyk w skórce Sidebar, przez hook displayCEShoppingCartFooter wykonywany przez ten widżet. Skórka Classic nie otwiera bocznego koszyka.

Ustawienie Pozycja w wysuwanym koszyku oferuje trzy miejsca: pod tytułem, nad podsumowaniem lub nad przyciskami zamówienia.

Pasek aktualizuje się przez Ajax przy każdym dodaniu do koszyka i każdym usunięciu z bocznego koszyka, bez przeładowania, a wskaźnik przesuwa się od poprzedniej wartości. Creative Elements przebudowuje tylko listę produktów i podsumowanie: pasek pozostaje na miejscu między aktualizacjami.

Zakładka Terytoria

Tabela wymienia wszystkie aktywne kraje sklepu, a pod każdym krajem z regionami jego regiony z wcięciem. Pole wyszukiwania i filtr skonfigurowanych terytoriów ułatwiają nawigację. Kwoty są w walucie domyślnej.

Kolejność ustalania

Dla adresu dostawy moduł szuka w tej kolejności i zatrzymuje się na pierwszym trafieniu: region adresu, potem kraj, potem globalny próg zapasowy, jeśli jest włączony. Bez trafienia pasek nie jest wyświetlany.

Pole wyboru i kwota: dwa różne skutki

• Pole odznaczone: pasek jest ukryty dla tego terytorium, bez dziedziczenia z kraju ani z progu globalnego.
• Pole zaznaczone, kwota pusta: reguła zostaje usunięta, terytorium dziedziczy z wyższego poziomu.
• Pole zaznaczone, kwota podana: obowiązuje ta kwota.

Przykład: tylko Francja metropolitalna

• Francja: zaznaczona, kwota 65.
• Korsyka: zaznaczona, kwota pusta; dziedziczy 65 €.
• Gwadelupa, Martynika, Gujana Francuska, Reunion, Majotta: odznaczone.
• Globalny próg zapasowy: wyłączony.

Zakładka Przewoźnicy

Trzy tryby: wszyscy przewoźnicy, wyświetlanie tylko dla zaznaczonych przewoźników lub ukrywanie dla zaznaczonych przewoźników. Reguły zapisywane są na id_reference przewoźnika: PrestaShop tworzy nowego przewoźnika przy każdej edycji, ale referencja pozostaje stała.

Ustawienie Przed wyborem przewoźnika decyduje, czy pasek jest widoczny w katalogu i koszyku, dopóki nie wybrano przewoźnika.

Zakładka Komunikaty

Pięć komunikatów można dostosować dla każdego aktywnego języka:

• Pusty koszyk (domyślnie: „Darmowa dostawa od {threshold}.”)
• Koszyk w trakcie (domyślnie: „Brakuje tylko {amount} do darmowej dostawy!”)
• Próg osiągnięty
• Strona produktu: ten produkt odblokowuje darmową dostawę
• Strona produktu: kwota pozostała po dodaniu produktu

Dostępne są dwa znaczniki: {amount} dla brakującej kwoty i {threshold} dla progu. Są zastępowane kwotą sformatowaną w walucie odwiedzającego, pogrubioną. Tekst wyświetla się bez zmian: wpisany HTML nie jest interpretowany. Puste pole zachowuje tłumaczenie dostarczone z modułem.

Zakładka Wygląd

• Kolory: tło, pasek, tekst i komunikat potwierdzenia, z próbnikiem koloru i zsynchronizowanym polem szesnastkowym.
• Ikona: ciężarówka, paczka, prezent lub brak. Ikony są w formacie SVG, a po osiągnięciu progu zastępuje je znacznik wyboru.
• Animacja: ruchome paski podczas postępu, automatycznie wyłączane dla odwiedzających, którzy ograniczyli animacje w systemie.
• Zamykany baner: dodaje przycisk zamknięcia do banera u góry strony. Po zamknięciu pozostaje ukryty do zamknięcia przeglądarki. Pozostałe pozycje nie są objęte.

Podgląd na żywo pokazuje baner, stronę produktu i osiągnięty próg oraz aktualizuje się przy każdej zmianie przed zapisaniem.

Aktualizacja w czasie rzeczywistym

Każda pozycja wstawia kontener, nawet gdy pasek nie ma nic do pokazania. Po zdarzeniu koszyka, adresu, kroku zamówienia, wariantu lub ilości jedno zapytanie pobiera pasek dla wszystkich pozycji strony, a każdy kontener jest wypełniany lub opróżniany na miejscu. Pasek ukryty przy wczytaniu może więc pojawić się bez przeładowania, i odwrotnie.

Skrypt nasłuchuje zdarzeń PrestaShop updateCart, updatedCart, updatedAddressForm, changedCheckoutStep, updateDeliveryForm i updatedProduct. Aby wywołać odświeżenie z własnego kodu:

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

Wiele sklepów i tłumaczenia

Progi mają id_shop: każdy sklep ma własne reguły. Wybierz kontekst sklepu u góry panelu przed otwarciem konfiguracji.

Moduł dostarczany jest z tłumaczeniami na polski, francuski, angielski, niemiecki, hiszpański i włoski. Do tekstów widocznych dla klienta w większości przypadków wystarcza zakładka Komunikaty.

Aktualizacja z wcześniejszej wersji

Podmiana pliku ZIP automatycznie uruchamia skrypty migracji. Progi zostają zachowane. Nowe opcje startują wyłączone w istniejącym sklepie: strona produktu, ukrywanie przy pustym koszyku, zamykany baner i ograniczenie do grup. Kolory zapisane przez wcześniejsze wersje są normalizowane do formatu #rrggbb, a pamięci podręczne Smarty i opcache są czyszczone.

Rozwiązywanie problemów

Pasek nie pojawia się nigdzie

1. Czy pasek podsumowania sygnalizuje, że żadne terytorium nie ma progu?
2. Czy moduł i wybrane pozycje są włączone?
3. Czy wymóg adresu jest ustawiony na Zawsze, a testujesz bez adresu?
4. Czy zaznaczono grupy klientów, do których nie należy Twoje konto testowe?
5. Czy opcja ukrywania przy pustym koszyku jest aktywna przy pustym koszyku?

Pasek pojawia się tam, gdzie nie powinien

Sprawdź, czy pole terytorium jest faktycznie odznaczone, a nie tylko czy wyczyszczono kwotę.

Nic w wysuwanym koszyku Creative Elements

• Widżet Koszyk musi używać skórki Sidebar.
• Opcja „Pokaż w wysuwanym koszyku Creative Elements” musi być włączona.
• Po aktualizacji z wersji 2.1.0 lub starszej wyczyść pamięć podręczną w Zaawansowane → Wydajność.

Kwota nie zgadza się z kasą

• Ustawienie podatku musi odpowiadać podstawie przedziałów przewoźnika.
• Bon rabatowy może sprowadzić koszyk poniżej progu.
• Moduł nie odczytuje przedziałów: każdą zmianę przedziału przenieś do modułu.

Pasek nie aktualizuje się po dodaniu do koszyka

Odświeżanie opiera się na zdarzeniach JavaScript PrestaShop. Jeśli zewnętrzny moduł koszyka ich nie emituje, wywołaj dffreeshipbar:refresh z jego kodu. Sprawdź też konsolę: wcześniejszy błąd JavaScript uniemożliwia zainstalowanie nasłuchu.

Odinstalowanie

Odinstalowanie usuwa obie tabele progów i wszystkie klucze konfiguracji z przedrostkiem DFFREESHIPBAR_, łącznie z komunikatami. Jeśli planujesz ponowną instalację, wyeksportuj wcześniej obie tabele.

Szybkie FAQ

• Czy moduł odczytuje PS_SHIPPING_FREE_PRICE? Nigdy.
• Czy moduł odczytuje moje przedziały przewoźnika? Nie, progi wprowadza się ręcznie. Automatyczna synchronizacja jest możliwa jako rozwiązanie na zamówienie.
• Moja darmowa dostawa zależy też od wagi. Czy to jest obsługiwane? Nie, moduł mierzy wyłącznie kwotę.
• Czy mogę użyć pogrubienia lub linku w komunikacie? Nie, tekst jest zabezpieczany. Kwoty znaczników są pogrubiane automatycznie.
• Czy zamknięty baner wraca? Przy następnym otwarciu przeglądarki.

Wsparcie i aktualizacje

Moduł obejmuje 12 miesięcy aktualizacji i wsparcia. Wsparcie e-mailowe po francusku lub angielsku, odpowiedź w ciągu 24 godzin roboczych. Skontaktuj się ze wsparciem DataFirefly, podając wersje PrestaShop, PHP i modułu, używany motyw oraz terytorium i przewoźnika, których dotyczy problem.