dfvariantswatch: próbki wariantów ze zdjęciem i stanem magazynowym

Wprowadzenie

dfvariantswatch zastępuje listy rozwijane wariantów na kartach produktu PrestaShop klikalnymi miniaturami (zdjęcia, kolory albo tekst), pokazuje podgląd wariantu w głównej galerii po najechaniu kursorem i wyświetla stan magazynowy każdego wariantu bezpośrednio na miniaturze.

Moduł działa, wzbogacając natywne widżety PrestaShop przez JavaScript: nie podmienia żadnego szablonu motywu, dzięki czemu jest zgodny z Classic, Hummingbird i większością motywów premium.

Instalacja

1. Panel administracyjny → Moduły → Menedżer modułów → Wgraj moduł
2. Przeciągnij i upuść archiwum dfvariantswatch.zip, a następnie kliknij Zainstaluj
3. Kliknij Konfiguruj, aby przejść do ustawień

Instalacja tworzy tabelę df_variant_swatch, katalog zdjęć img/dfvariantswatch/ oraz domyślne wartości konfiguracji. Żadna modyfikacja motywu nie jest potrzebna.

Jak powstają miniatury

Dla każdego atrybutu moduł wybiera źródło miniatury w następującej kolejności:

1. Obraz wgrany w panelu administracyjnym dla tego atrybutu (zakładka Miniatury według atrybutu)
2. Szesnastkowy kod koloru zdefiniowany w panelu administracyjnym
3. Obraz wyprowadzony automatycznie z pierwszej kombinacji używającej tego atrybutu
4. Natywny kolor PrestaShop przypisany atrybutowi (pole koloru w grupie)
5. Etykieta tekstowa z nazwą atrybutu

Zabezpieczenie dla grup bez zróżnicowania

Automatyczne wyprowadzanie obrazu jest zachowywane tylko wtedy, gdy zdjęcia faktycznie różnią się między atrybutami grupy albo gdy grupa jest oznaczona w PrestaShop jako grupa kolorów. W praktyce: przy produkcie z grupą Rozmiar (S, M, L, XL), w której wszystkie kombinacje mają te same zdjęcia, rozmiary pozostają etykietami tekstowymi zamiast wyświetlać cztery razy to samo zdjęcie.

Konfiguracja

Ustawienia ogólne

• Włącz moduł: wyłącza rendering na sklepie bez deinstalacji
• Najechanie zmienia galerię: podgląd wariantu po najechaniu na miniaturę
• Pokaż plakietkę stanu: informacja o dostępności pod każdą miniaturą
• Ukryj warianty niedostępne: całkowicie ukrywa wyczerpane miniatury zamiast je przekreślać
• Kształt: okrągły, kwadratowy albo pigułka; Rozmiar w pikselach
• Próg niskiego stanu: poniżej tej wartości plakietka przechodzi w stan niskiego zapasu
• Etykiety stanu magazynowego: trzy teksty można dowolnie zmieniać i tłumaczyć w Lokalizacja → Tłumaczenia
• Tryb wczytywania danych: Inline (zalecany) albo AJAX, opisane niżej
• Grupy bez próbek: wybrane grupy zachowują swój natywny widżet

Miniatury według atrybutu

Ta zakładka wypisuje wszystkie grupy atrybutów w sklepie. Dla każdej wartości możesz wgrać obraz (jpg, png, webp lub gif, maksymalnie 2 MB, zalecane 200 na 200 pikseli) albo wpisać kod koloru w formacie #RRGGBB, podejrzeć bieżącą miniaturę oraz usunąć istniejącą próbkę.

Tryby wczytywania

Inline (domyślny, zalecany): dane wariantów są osadzane w stronie w chwili renderowania. Brak wywołań AJAX przy wczytywaniu, natychmiastowe wyświetlenie miniatur, maksymalna niezawodność.

AJAX: dane są pobierane osobnym wywołaniem po wczytaniu strony. Ten tryb zarezerwuj dla sklepów za agresywnym cache pełnostronicowym, gdzie aktualność pokazywanego stanu magazynowego jest ważniejsza od szybkości wyświetlenia.

Dostępność z klawiatury

Selektor implementuje wzorzec WAI-ARIA radiogroup: klawisz Tab ustawia fokus na wybranym wariancie grupy (jeden punkt tabulacji na grupę), strzałki nawigują i wybierają w obrębie grupy, zapętlając się i pomijając warianty niedostępne, a Spacja lub Enter zatwierdza miniaturę z fokusem. Stany są komunikowane czytnikom ekranu przez aria-checked, a dymki podpowiedzi respektują prefers-reduced-motion.

Personalizacja CSS

Udostępnione zmienne CSS pozwalają dostosować wygląd z poziomu arkusza stylów motywu potomnego, bez ingerencji w moduł:

.dfvs-swatch {
    --dfvs-size: 56px;   /* rozmiar miniatur */
}
.dfvs-swatch.dfvs-active {
    box-shadow: 0 0 0 2px #b8860b; /* obwódka aktywnego wariantu */
}

Aby wyłączyć podgląd po najechaniu na konkretnym produkcie, dodaj w szablonie produktu element z atrybutem data-dfvs-disable-hover.

Rozwiązywanie problemów

Miniatury się nie pojawiają

• Sprawdź, czy moduł jest włączony w swojej konfiguracji
• Otwórz konsolę przeglądarki: moduł loguje kolejne kroki z prefiksem [dfvariantswatch], zobaczysz tam liczbę wyrenderowanych grup albo powód braku renderowania
• Produkt musi mieć warianty. Produkt prosty nie wyświetla niczego i jest to zachowanie prawidłowe

Rozmiary wyświetlają się jako tekst, a nie jako zdjęcia

To oczekiwane działanie zabezpieczenia: wartości grupy współdzielą te same zdjęcia kombinacji. Jeśli chcesz mieć wizualizacje, wgraj dedykowane obrazy dla poszczególnych rozmiarów w zakładce Miniatury według atrybutu (na przykład piktogramy sylwetek).

Natywny blok wraca po kliknięciu

Moduł ponownie ukrywa natywny widżet po każdej aktualizacji AJAX w PrestaShop. Jeśli mocno przerobiony motyw omija standardowe zdarzenia, skontaktuj się ze wsparciem, podając adres URL danej karty produktu.

Deinstalacja

Deinstalacja usuwa tabelę modułu, obrazy wgrane do img/dfvariantswatch/ oraz wszystkie klucze konfiguracji. Zdjęcia Twoich kombinacji pozostają oczywiście nienaruszone.