Moduł Quick View PrestaShop 8/9: dokumentacja

Wprowadzenie

DF Quick View zastępuje natywny szybki podgląd Twojego motywu PrestaShop nowoczesnym oknem modalnym: pełna galeria zdjęć, wybór wariantów na żywo, wskaźnik stanu magazynowego, selektor ilości i dodanie do koszyka przez AJAX. Dzięki wstępnemu wczytywaniu przy najechaniu okno otwiera się natychmiast, a klient przez całą ścieżkę pozostaje na stronie kategorii.

Moduł nie nadpisuje żadnego szablonu motywu: podpina się standardowym hookiem actionFrontControllerSetMedia i pracuje po stronie przeglądarki na istniejących miniaturach produktów. JavaScript jest natywny, bez jQuery i bez zewnętrznych zależności.

Wymagania

• PrestaShop 8.0 do 9.x
• PHP 7.4 lub nowszy
• Motyw wyświetlający miniatury produktów na stronach list (motyw Classic i motywy z niego wywodzone działają bez żadnych ustawień)

Instalacja

1. Pobierz archiwum dfquickview-1.0.0.zip ze swojego konta klienta DataFirefly.
2. W panelu administracyjnym przejdź do Moduły > Menedżer modułów, kliknij Wgraj moduł i wskaż archiwum.
3. Kliknij Zainstaluj, a następnie Konfiguruj.

W bazie nie jest tworzona żadna tabela: moduł przechowuje wyłącznie swoje ustawienia w tabeli konfiguracji PrestaShop. Deinstalacja jest czysta i usuwa wszystkie jego klucze.

Konfiguracja

Tryb wyzwalania

Trzy tryby określają, jak otwiera się okno modalne:

• Przechwytywanie: moduł przechwytuje linki szybkiego podglądu Twojego motywu (elementy z klasami .quick-view, .js-quick-view albo z atrybutem data-link-action="quickview") i otwiera zamiast nich własne okno. Zachowanie natywne zostaje wyłączone.
• Wstrzykiwanie: moduł dodaje własny przycisk nałożony na każdą miniaturę produktu. Przydatne, jeżeli Twój motyw w ogóle nie oferuje szybkiego podglądu.
• Oba (zalecane, wartość domyślna): oba mechanizmy działają jednocześnie.

Selektor CSS miniatur produktów

Moduł musi wiedzieć, które elementy strony odpowiadają miniaturze produktu. Wartość domyślna, .product-miniature, .js-product-miniature, obejmuje motyw Classic i zdecydowaną większość motywów potomnych.

Jeżeli Twój motyw używa innej struktury, otwórz stronę kategorii, sprawdź kontener produktu w narzędziach deweloperskich przeglądarki i wpisz tutaj jego klasę. Moduł szuka następnie identyfikatora produktu w atrybucie data-id-product wewnątrz miniatury, a w razie jego braku wyprowadza go z adresu linku do produktu.

Inteligentne wstępne wczytywanie

Włączone domyślnie. Gdy kursor zatrzyma się nad miniaturą produktu na czas opóźnienia wstępnego wczytywania (domyślnie 120 ms), moduł pobiera dane produktu w tle i wczytuje jego pierwsze zdjęcie. W chwili kliknięcia wszystko jest już w pamięci: okno otwiera się bez opóźnienia.

Na urządzeniach mobilnych wstępne wczytywanie uruchamia się przy pierwszym dotknięciu miniatury.

Na każdy produkt wysyłane jest tylko jedno zapytanie, nawet jeżeli odwiedzający najedzie na tę samą miniaturę kilka razy. Jeżeli obawiasz się obciążenia serwera, zwiększ opóźnienie (300 do 500 ms odfiltrowuje przypadkowe najazdy) albo wyłącz tę funkcję: okno będzie się wtedy ładowało po kliknięciu, z animowanym szkieletem ładowania.

Czas życia cache po stronie klienta

Pobrane dane produktu są przechowywane w sesji przeglądarki przez podany czas (domyślnie 300 sekund). Odwiedzający, który ponownie otworzy to samo okno, nie wywoła żadnego nowego zapytania.

Cache jest rozdzielony według języka, waluty, sklepu i grupy klientów: odwiedzający nigdy nie zobaczy ceny wyliczonej dla innej grupy. Ustaw wartość 0, aby całkowicie wyłączyć cache sesji (cache pamięciowy strony pozostaje aktywny).

Wyświetlana treść

• Pokazuj krótki opis: wyświetla streszczenie produktu w oknie (ukrywane na mobile, aby oszczędzić miejsce).
• Pokazuj referencję produktu: wyświetla referencję produktu albo wybranego wariantu, jeżeli ten ma własną.
• Pokazuj link „Zobacz kartę produktu”: dodaje link do pełnej karty pod przyciskiem dodania do koszyka.

Wczytuj na wszystkich stronach

Domyślnie zasoby modułu są wczytywane tylko na stronach list: strona główna, kategorie, wyszukiwanie, marki, dostawcy, promocje, nowości i bestsellery. Włącz tę opcję, jeżeli wyświetlasz miniatury produktów gdzie indziej: na stronach CMS, w blokach niestandardowych, w modułach zewnętrznych.

Kolor akcentu

Określa kolor przycisków, obramowań zaznaczenia i stanów aktywnych w oknie. Wpisz kolor szesnastkowy zgodny z Twoją identyfikacją wizualną.

Jak działa okno modalne

Galeria

Okno wyświetla wszystkie zdjęcia produktu: zdjęcie główne, klikalne miniatury poniżej, strzałki wstecz i dalej. Obsługiwana jest nawigacja klawiaturą (strzałki w lewo i w prawo zmieniają zdjęcie, klawisz Esc zamyka okno), a na urządzeniach mobilnych działa przesuwanie palcem.

Jeżeli wybrany wariant ma przypisane zdjęcia w PrestaShop, galeria automatycznie ogranicza się do tych zdjęć. W przeciwnym razie pozostają wyświetlone wszystkie zdjęcia produktu.

Warianty

Grupy atrybutów są renderowane zgodnie z ich typem ustawionym w PrestaShop:

• Próbnik koloru: grupy oznaczone jako grupy koloru wyświetlają okrągły próbnik, z teksturą, jeżeli dla atrybutu istnieje plik tekstury, a w przeciwnym razie z kolorem szesnastkowym.
• Lista rozwijana: grupy typu „lista rozwijana” wyświetlają menu.
• Przycisk: pozostałe grupy wyświetlają klikalne prostokątne próbniki.

Przy każdej zmianie wyboru moduł przelicza odpowiadającą kombinację i aktualizuje cenę, cenę przekreśloną, procent rabatu, referencję, stan magazynowy, ilość minimalną i zdjęcia.

Dwa stany wizualne sygnalizują ślepe uliczki:

• Wyszarzony: atrybut w połączeniu z bieżącym wyborem nie odpowiada żadnemu istniejącemu wariantowi.
• Przygaszony: kombinacja istnieje, ale jest niedostępna, a produkt nie pozwala na zamawianie przy braku stanu.

Stan magazynowy i ilość

W zależności od dostępności wybranego wariantu wyświetlane są trzy stany: dostępny, w trakcie uzupełniania (zamawianie przy braku stanu dozwolone) albo wyprzedany (przycisk dodania jest wtedy nieaktywny).

Selektor ilości respektuje ilość minimalną ustawioną na produkcie lub na wariancie: startuje od tej wartości i nie pozwala zejść poniżej.

Dodanie do koszyka

Dodanie jest wysyłane przez AJAX do natywnego kontrolera koszyka PrestaShop. Po powodzeniu moduł emituje zdarzenie updateCart frameworku frontowego: blok koszyka w nagłówku aktualizuje się automatycznie, bez przeładowania.

Błędy zwracane przez sklep, takie jak brak stanu, nieosiągnięta ilość minimalna czy niedostępny produkt, są wyświetlane w oknie, pod przyciskiem.

Produkty z obowiązkowymi polami personalizacji nie mogą być dodane do koszyka z poziomu okna: moduł wyświetla komunikat i zachęca klienta do otwarcia pełnej karty produktu.

Zgodność z nawigacją fasetową

Gdy klient zastosuje filtr, PrestaShop podmienia listę produktów bez przeładowania strony. Moduł nasłuchuje zdarzenia updateProductList, a także obserwuje zmiany w dokumencie: jego przyciski są automatycznie wstrzykiwane na nowe miniatury, bez żadnej ingerencji z Twojej strony.

Rozwiązywanie problemów

Na miniaturach nie pojawia się żaden przycisk

Sprawdź najpierw, czy tryb wyzwalania obejmuje wstrzykiwanie („Wstrzykiwanie” albo „Oba”). Następnie sprawdź selektor CSS miniatur: otwórz stronę kategorii, obejrzyj kontener produktu i potwierdź, że odpowiada skonfigurowanemu selektorowi. Na koniec upewnij się, że miniatura rzeczywiście zawiera atrybut data-id-product albo link do karty produktu.

Okno nie otwiera się po kliknięciu szybkiego podglądu motywu

Tryb wyzwalania musi obejmować przechwytywanie („Przechwytywanie” albo „Oba”). Niektóre motywy używają niestandardowych klas dla swojego przycisku: w takim wypadku przełącz się na tryb „Wstrzykiwanie” i ukryj natywny przycisk motywu regułą CSS we własnym arkuszu stylów.

Zasoby nie wczytują się na konkretnej stronie

Moduł wczytuje swoje zasoby wyłącznie na standardowych stronach list. Jeżeli wyświetlasz miniatury produktów na stronie CMS albo w module zewnętrznym, włącz opcję Wczytuj na wszystkich stronach.

Zmiany konfiguracji nie są widoczne

Wyczyść cache PrestaShop (Ustawienia zaawansowane > Wydajność > Wyczyść pamięć podręczną) i przeładuj stronę z wymuszonym odświeżeniem przeglądarki. Jeżeli zmieniłeś czas życia cache po stronie klienta, odwiedzający będący już w sesji zachowują swoje dane do momentu wygaśnięcia.

Cena w oknie nie zgadza się z ceną na liście

Ceny w oknie są wyliczane po stronie serwera tą samą metodą co na karcie produktu, z uwzględnieniem grupy klientów, waluty i podatków. Jeżeli różnica się utrzymuje, sprawdź, czy Twój motyw nie stosuje własnego sposobu wyświetlania cen na miniaturach, i wyczyść cache klienta, ustawiając tymczasowo jego czas życia na 0.

Deinstalacja

W menedżerze modułów wybierz Odinstaluj. Wszystkie klucze konfiguracji modułu zostaną usunięte. Żadne dane produktów ani zamówień nie są naruszane.