Spis treści

1. Po co moduł powstał
2. Co robi moduł
3. Proces zwrotu – krok po kroku
4. Dlaczego tyle hooków
5. Integracja z Design Cart pFooter
6. Integracja z Design Cart pMenu
7. Wymagania
8. Instalacja
9. Konfiguracja
10. Lista dostępnych hooków
11. Dedykowana strona zwrotu
12. Dokumentacja techniczna
13. Rozwiązywanie problemów
14. Podsumowanie

1. Po co moduł powstał

Standardowy mechanizm zwrotów w PrestaShop działa poprawnie w panelu administracyjnym i na koncie klienta, ale na froncie sklepu często jest ukryty lub niewygodny:

• klient musi się zalogować i szukać opcji w „Moje konto”,
• gość nie ma prostego wejścia do formularza zwrotu,
• link do zwrotów trzeba ręcznie dodawać w menu lub stopce,
• różne motywy (Classic, Hummingbird, Design Cart) mają inną strukturę nagłówka i stopki,
• właściciel sklepu nie chce modyfikować kodu szablonu przy każdym wdrożeniu.

Design Cart Szybki zwrot powstał po to, aby dać klientowi szybki, czytelny formularz zwrotu – w modalu lub na osobnej stronie – przy jednoczesnym wykorzystaniu natywnego mechanizmu OrderReturn PrestaShop. Moduł nie zastępuje logiki zwrotów w back office; tworzy wygodną warstwę frontową nad tym, co sklep już obsługuje.

Moduł jest częścią ekosystemu Design Cart dla PrestaShop i został zaprojektowany tak, aby współpracować z rozbudowanymi modułami nawigacji i stopki – szczególnie z Design Cart pFooter oraz Design Cart pMenu.

Zobacz wideo:

2. Co robi moduł

Moduł udostępnia klientowi formularz zwrotu produktów w czterech etapach:

1. Zamówienie – klient podaje numer zamówienia i e-mail (gość) lub wybiera zamówienie z listy (zalogowany).
2. Produkty – wybór pozycji do zwrotu, ilości oraz opcjonalnych uwag.
3. Podsumowanie – przegląd wybranych produktów i uwag; możliwość cofnięcia się i zmiany wyboru.
4. Potwierdzenie – komunikat o przyjęciu wniosku wraz z numerem zwrotu.

Dodatkowo moduł oferuje:

• Modal na froncie – otwierany linkiem w stopce, nagłówku lub innym miejscu (wg konfiguracji hooków),
• Dedykowaną stronę pod przyjaznym adresem /zwrot-produktow,
• Konfigurowalną etykietę linku (np. „Zwrot produktów”, „Szybki zwrot”),
• Wybór miejsc wyświetlania linku – przełączniki dla wielu hooków motywu,
• Style niezależne od motywu – formularz ma własny CSS, nie psuje się przy zmianie szablonu,
• Obsługę gości i zalogowanych – bez wymuszania konta użytkownika,
• Pełną integrację z OrderReturn – zwrot trafia do standardowej listy zwrotów w BO.

Moduł nie wymaga edycji rdzenia PrestaShop ani modyfikacji plików motywu – pozycję linku ustawiasz z panelu modułu i ewentualnie w Projekt → Pozycje.

3. Proces zwrotu – krok po kroku

3.1. Klient niezalogowany

1) Klika link „Zwrot produktów” (stopka, menu itd.) lub wchodzi na /zwrot-produktow.

2) Podaje numer zamówienia i adres e-mail użyty przy zakupie.

3) Klika Dalej – moduł pobiera zamówienie przez AJAX.

4) Zaznacza produkty, wybiera ilość, opcjonalnie wpisuje uwagi.

5) Klika Przejdź do podsumowania.

6) Sprawdza listę, w razie potrzeby wraca do wyboru produktów.

7) Klika Wyślij wniosek o zwrot.

8) Otrzymuje komunikat o przyjęciu wniosku i numer zwrotu (np. #ZW000001).

3.2. Klient zalogowany

Zamiast ręcznego wpisywania danych klient wybiera zamówienie z listy rozwijanej (tylko zamówienia spełniające warunki zwrotu). Reszta procesu jest identyczna.

3.3. Warunki, które musi spełniać zamówienie

Moduł respektuje natywne reguły PrestaShop (Order::isReturnable()):

• w sklepie muszą być włączone zwroty towarów (BO → Obsługa klienta → Zwroty produktów),
• zamówienie musi mieć status opłacone i wysłane (np. „Dostarczone”),
• musi być w terminie zwrotu (domyślnie liczba dni od daty dostawy – ustawienie PS_ORDER_RETURN_NB_DAYS),
• w zamówieniu muszą być produkty jeszcze niezwrócone (dostępna ilość > 0).

Jeśli warunek nie jest spełniony, moduł wyświetla konkretny komunikat (np. brak statusu dostawy, minął termin, brak produktów do zwrotu) – zamiast ogólnego błędu.

4. Dlaczego tyle hooków

PrestaShop nie ma jednego uniwersalnego miejsca na link pomocniczy. Każdy motyw (Classic, Hummingbird, Design Cart, motywy agencyjne) renderuje nawigację i stopkę w innych hookach:

• Classic umieszcza „Kontakt z nami” w displayNav1,
• Design Cart podpina menu pod displayTop,
• stopka może korzystać z displayFooterBefore, displayFooter lub displayFooterAfter,
• konto klienta ma własne hooki (displayCustomerAccount, displayMyAccountBlock).

Zamiast zgadywać, gdzie w danym sklepie powinien być link, moduł daje panel z przełącznikami (switch) dla każdego sensownego hooka. Włączasz tylko te miejsca, które pasują do Twojego motywu.

Ważne zasady:

• Modal formularza ładuje się raz (hook systemowy displayBeforeBodyClosingTag) – niezależnie od liczby włączonych pozycji linku.
• Link może być w wielu hookach jednocześnie (np. stopka + nagłówek + konto klienta).
• Kolejność modułów w danym hooku ustawiasz w Projekt → Pozycje (np. link zwrotu tuż pod „Kontakt z nami”).
• Domyślnie włączony jest tylko displayFooter – reszta jest wyłączona do czasu świadomej konfiguracji.

Dzięki temu jeden moduł obsługuje wdrożenia od prostego Classic po rozbudowane sklepy z własnym layoutem – bez forkowania kodu pod każdy szablon.

5. Kompatybilność z Design Cart pFooter

Design Cart pFooter to moduł do budowy stopki z wierszy i kolumn. Nie ma między nim a Szybkim zwrotem żadnej dedykowanej integracji – moduły się nie „łączą” przez API ani wspólne hooki specjalnego typu.

Są po prostu kompatybilne, bo każdy rozwiązuje inną część tego samego wdrożenia:

• pFooter – układ i treść stopki; w konfiguracji możesz dodać dowolny link URL (CMS, kategorie, własny adres itd.).
• Szybki zwrot – formularz zwrotu i opcjonalnie własny link w hookach PrestaShop albo strona /zwrot-produktow.

Jak to zwykle łączy się w praktyce:

1. Link tylko z pFooter – w pFooter dodajesz pozycję z adresem /zwrot-produktow (skopiowanym z panelu Szybkiego zwrotu). Hooki stopki w Szybkim zwrocie możesz wyłączyć, żeby nie dublować linku.
2. Link tylko z Szybkiego zwrotu – włączasz np. displayFooter w konfiguracji modułu; pFooter buduje resztę stopki obok.
3. Oba naraz – możliwe, ale uważaj na dwa linki do tego samego w stopce. To kwestia konfiguracji, nie automatycznej współpracy modułów.

Modal po kliknięciu linku działa tylko wtedy, gdy link pochodzi z Szybkiego zwrotu (przycisk z data-dc-ocr-open). Zwykły link URL w pFooter prowadzi na stronę /zwrot-produktow – ten sam formularz, bez okna modalnego.

6. Kompatybilność z Design Cart pMenu

Design Cart pMenu to mega menu z pozycjami typu URL, kategoria, CMS i dropdown. Tak jak w przypadku pFooter – brak specjalnej integracji ze Szybkim zwrotem.

Moduły są kompatybilne, ponieważ:

• pMenu pozwala dodać w menu dowolny link (np. do /zwrot-produktow),
• Szybki zwrot może niezależnie wyświetlić własny link w hookach nagłówka (displayNav1, displayTop itd.) albo udostępnić tylko stronę zwrotu.

Typowe ustawienia:

• Link „Zwrot produktów” w pMenu jako pozycja URL → strona /zwrot-produktow.
• Albo link z Szybkiego zwrotu w innym hooku niż menu (np. displayNav1 obok kontaktu) – bez dodawania pozycji w pMenu.
• Nie włączaj jednocześnie dwóch linków w tym samym miejscu – to nie jest wymagane i tylko myli klienta.

pMenu, pFooter i Szybki zwrot można używać w jednym sklepie, bo każdy robi co innego: nawigacja, stopka, formularz zwrotu. Kompatybilność sprowadza się do tego, że pMenu i pFooter przyjmują zwykłe adresy URL, a Szybki zwrot taki adres udostępnia.

7. Wymagania

• PrestaShop 8.0.0 lub nowszy (w tym PrestaShop 9).
• Włączone zwroty towarów w ustawieniach sklepu.
• Moduł skopiowany do /modules/dc_one_click_return/ i zainstalowany z panelu.
• PHP z obsługą JSON, sesji i standardowych klas PrestaShop (OrderReturn, Order).
• Dla modala i AJAX – JavaScript włączony po stronie klienta.

8. Instalacja

1. Skopiuj katalog modułu do /modules/dc_one_click_return/ na serwerze sklepu.
2. Zaloguj się do panelu administracyjnego PrestaShop.
3. Przejdź do Moduły → Menedżer modułów.
4. Wyszukaj Design Cart Szybki zwrot (lub dc_one_click_return).
5. Kliknij Instaluj.
6. Po instalacji moduł:
   • zarejestruje hooki systemowe i pozycyjne,
   • ustawi domyślną etykietę linku: „Zwrot produktów”,
   • włączy link w hooku displayFooter,
   • utworzy przyjazny URL strony: /zwrot-produktow.
7. Włącz zwroty w sklepie: Obsługa klienta → Zwroty produktów → zapisz ustawienia (włącz funkcję, ustaw liczbę dni na zwrot).
8. Otwórz konfigurację modułu i dostosuj hooki oraz etykietę linku do swojego motywu.
9. Wyczyść cache sklepu (Zaawansowane → Wydajność) po pierwszym wdrożeniu.

Przy odinstalowaniu moduł usuwa wpisy konfiguracyjne DC_OCR_LINK_LABEL i DC_OCR_ENABLED_HOOKS. Same zwroty utworzone wcześniej w systemie PrestaShop pozostają w bazie.

9. Konfiguracja

Konfiguracja dostępna jest w Moduły → Design Cart Szybki zwrot → Konfiguruj.

9.1. Etykieta linku

Tekst wyświetlany na przycisku lub linku otwierającym formularz (np. „Zwrot produktów”, „Szybki zwrot”, „Zwróć towar”). Pole jest wymagane.

9.2. Pozycje wyświetlania linku (hooki)

Formularz zawiera przełączniki pogrupowane w sekcje:

• Nagłówek sklepu – displayNav1, displayNav2, displayTop, displayNavFullWidth, displayBanner
• Stopka – displayFooterBefore, displayFooter, displayFooterAfter
• Konto klienta – displayCustomerAccountTop, displayCustomerAccount, displayMyAccountBlock
• Inne – displayOrderDetail, kolumny boczne, displayWrapperTop, displayWrapperBottom

Włącz tylko te pozycje, które odpowiadają strukturze Twojego motywu. Po zapisie ustaw kolejność w Projekt → Pozycje, jeśli link ma być w konkretnym miejscu (np. pod modułem kontaktu).

9.3. Panel z adresami URL

W konfiguracji modułu znajdziesz:

• Przyjazny URL – /zwrot-produktow (zalecany do wklejenia w pFooter, pMenu lub CMS),
• Standardowy URL modułu – adres z parametrami fc=module (zapasowy).

9.4. Ostrzeżenia w panelu

Moduł informuje w BO, gdy:

• zwroty towarów są wyłączone w PrestaShop – link i formularz nie będą działać,
• żaden hook nie jest włączony – link nie pojawi się na froncie (strona /zwrot-produktow nadal może działać).

10. Lista dostępnych hooków

Hooki systemowe (nie konfigurowane przełącznikami): displayHeader, actionFrontControllerSetMedia, displayBeforeBodyClosingTag, moduleRoutes.

11. Dedykowana strona zwrotu

Moduł rejestruje trasę przyjazną:

/zwrot-produktow

Strona wyświetla ten sam formularz co modal, ale w trybie pełnoekranowym (bez okna dialogowego). Przydatne, gdy:

• linkujesz ze stopki pFooter jako zwykły URL,
• dodajesz pozycję w pMenu typu „strona funkcjonalna” lub własny URL,
• chcesz udostępnić zwrot w regulaminie lub mailu transakcyjnym jednym stałym adresem.

12. Dokumentacja techniczna

12.1. Główne pliki

• dc_one_click_return.php – klasa modułu, instalacja, hooki, konfiguracja BO, ładowanie assetów.
• classes/DcOneClickReturnService.php – logika zwrotów: walidacja zamówienia, lista produktów, tworzenie OrderReturn.
• classes/DcOneClickReturnPlacements.php – definicja hooków pozycyjnych i zapis konfiguracji.
• controllers/front/ajax.php – endpoint AJAX (akcje: orders, order, submit).
• controllers/front/return.php – kontroler strony /zwrot-produktow.
• views/templates/hook/ – szablony linku, modala i widgetu formularza.
• views/js/front.js – logika kroków formularza po stronie klienta.
• views/css/front.css – style scoped (#dc-ocr-modal, .dc-ocr-page).

12.2. Endpoint AJAX

Adres: module/dc_one_click_return/ajax (z parametrem ajax=1).

Wymagany token: Tools::getToken(false) – przekazywany w obiekcie dcOneClickReturn na froncie.

12.3. Konfiguracja w bazie

• DC_OCR_LINK_LABEL – etykieta linku.
• DC_OCR_ENABLED_HOOKS – JSON z listą włączonych hooków pozycyjnych.

12.4. Zgodność z PrestaShop 9

Moduł korzysta z API zgodnego z PS 9, m.in.:

• Tools::getContextLocale()->formatPrice() zamiast usuniętego Tools::displayPrice(),
• Tools::displayDate($date, false) – poprawna sygnatura w PS 9,
• natywne OrderReturn::add() i addReturnDetail().

12.5. Hook dla deweloperów

Po utworzeniu zwrotu wywoływany jest standardowy hook PrestaShop:

Hook::exec('actionOrderReturn', ['orderReturn' => $orderReturn]);

13. Rozwiązywanie problemów

Link nie widać na stronie

• Sprawdź, czy w konfiguracji modułu włączony jest co najmniej jeden hook.
• Sprawdź, czy zwroty są włączone w Obsługa klienta → Zwroty produktów.
• Wyczyść cache PrestaShop i przeglądarki.
• W Projekt → Pozycje upewnij się, że moduł nie jest wyłączony w danym hooku.

„Tego zamówienia nie można zwrócić” lub podobny komunikat

• Ustaw status zamówienia na Dostarczone (opłacone + wysłane).
• Sprawdź datę dostawy i limit dni na zwrot w ustawieniach sklepu.
• Upewnij się, że produkty nie zostały już w całości zwrócone.

Formularz nie reaguje na „Dalej”

• Twarde odświeżenie strony (Ctrl+Shift+R).
• Sprawdź w konsoli przeglądarki, czy załadował się front.js (wersja 1.2.0+).
• Upewnij się, że moduł jest poprawnie zainstalowany (hooki zarejestrowane).

Brak stylów / surowy HTML

• Moduł ładuje CSS inline w displayHeader oraz przez registerStylesheet.
• Po aktualizacji plików wyczyść cache i sprawdź, czy hook displayHeader jest aktywny.

14. Podsumowanie

Design Cart Szybki zwrot to moduł frontowy, który upraszcza zwroty dla klienta, nie rezygnując z natywnej obsługi PrestaShop. Daje konfigurowalne miejsca linku dzięki wielu hookom, przejrzysty czterokrokowy formularz oraz dedykowaną stronę /zwrot-produktow.

Najlepiej sprawdza się w sklepach opartych o ekosystem Design Cart – zwłaszcza razem z Design Cart pFooter (elastyczna stopka) i Design Cart pMenu (mega menu). Stopka i menu konfigurujesz wizualnie; Szybki zwrot dostarcza gotowy, bezpieczny proces zwrotu zgodny z mechanizmem sklepu.