Brand Carousel: dokumentacja karuzeli marek PrestaShop

Instalacja

W panelu administracyjnym otwórz Moduły > Menedżer modułów, kliknij „Załaduj moduł” i wyślij plik dfbrandcarousel-2.0.0.zip. Moduł działa z PrestaShop od 8.0 do 9.x.

Podczas instalacji moduł tworzy dwie tabele, hook displayDfBrandCarousel, folder /img/dfbrandcarousel/ na logo zastępcze oraz pierwszy blok: karuzelę marek na stronie głównej (displayHome) z tytułem „Nasze marki” przetłumaczonym na każdy zainstalowany język. Otwórz sklep, aby zobaczyć efekt, a następnie zmodyfikuj lub usuń ten blok.

Moduł obsługuje się przyciskiem „Konfiguruj” w Menedżerze modułów.

Aktualizacja z wersji 1.0.x

Wyślij ZIP 2.0.0 na zainstalowaną wersję. Skrypt aktualizacji tworzy nowe tabele i przenosi dotychczasową konfigurację do bloku o nazwie „Brand carousel” w tym samym hooku: tytuł, liczbę marek, kolumny, automatyczne przewijanie, prędkość, odstępy, strzałki, kropki, wybrane marki i kolejność losową. Marki bez produktów pozostają widoczne tak jak wcześniej. Stare ustawienia DFBC_* są następnie usuwane. Swiper nie jest już używany, co kończy konflikty z motywami i page builderami ładującymi własną wersję.

Lista bloków

Zakładka Bloki pokazuje bloki z ich trybem, hookiem i źródłem. Dla każdego bloku możesz:

• włączyć lub wyłączyć blok przełącznikiem,
• edytować blok w edytorze,
• zduplikować blok (kopia jest tworzona jako wyłączona),
• usunąć blok,
• przeciągać bloki, aby ustalić ich kolejność, gdy kilka korzysta z tego samego hooka.

Przycisk „Wyczyść pamięć podręczną” usuwa zapisane dane marek, liczników i sprzedaży (zob. Pamięć podręczna i wydajność).

Edytor bloku

Edytor pokazuje ustawienia po lewej, podzielone na 5 zakładek, i podgląd po prawej. Podgląd odświeża się przy każdej zmianie i można go przełączyć na szerokość komputera, tabletu lub telefonu. Używa neutralnej czcionki: w sklepie blok korzysta z czcionek motywu.

Górny pasek zawiera wewnętrzną nazwę bloku, przełącznik aktywności, wybór języka pól tłumaczonych i przycisk Zapisz. Wskaźnik sygnalizuje niezapisane zmiany, a Ctrl+S (Cmd+S na Macu) zapisuje bez opuszczania edytora.

Zakładka Treść

Nagłówek

• Tytuł i podtytuł: dla każdego języka. Zostaw tytuł pusty, aby go ukryć.
• Znacznik tytułu: H2 na stronie głównej, H3 na stronie, która ma już nagłówki H2, albo p i div dla tytułu bez roli nagłówka.
• Układ nagłówka: tytuł po lewej i link po prawej, wszystko do lewej lub wyśrodkowane. W dwóch ostatnich przypadkach link przechodzi pod logo.
• Link do wszystkich marek: tekst dla każdego języka i adres URL. Bez adresu link prowadzi do strony marek PrestaShop.

Marki do wyświetlenia

• Wszystkie aktywne marki sklepu.
• Wybór ręczny: dodaj marki z listy po lewej przyciskiem +, a następnie uporządkuj je przeciąganiem na liście po prawej. „Dodaj całą listę” dodaje marki z bieżącego wyszukiwania.
• Marki z kategorii: marki z co najmniej jednym widocznym produktem w wybranej kategorii lub jej podkategoriach.
• Marki bieżącej kategorii: na stronie kategorii marki tej kategorii, na karcie produktu marki jego głównej kategorii, w pozostałych miejscach wszystkie marki.

Te ustawienia uzupełniają źródło:

• Wykluczone marki: usuwane z listy, z wyjątkiem wyboru ręcznego.
• Sortowanie: Twoja kolejność (wybór ręczny), alfabetycznie, najwięcej produktów najpierw, najlepiej sprzedające się najpierw w okresie od 7 do 730 dni, najnowsze marki najpierw lub losowo przy każdej wizycie. Sortowanie alfabetyczne ignoruje akcenty i interpunkcję: L’Oréal jest sortowane jak „loreal”.
• Maksymalna liczba marek: 0 wyświetla wszystkie pasujące marki.
• Minimalna liczba produktów: domyślnie 1, aby nie kierować odwiedzającego na pustą stronę marki.
• Tylko marki z logo: filtr jest stosowany przed limitem, więc otrzymujesz żądaną liczbę marek.

Kolejność losowa jest ustalana w przeglądarce. Cache całych stron może serwować tę samą stronę wszystkim odwiedzającym, a kolejność i tak zmienia się przy każdej wizycie. W trybach przewijania ciągłego limit jest stosowany najpierw w kolejności alfabetycznej, a potem wybrane marki są mieszane.

Zakładka Układ

8 trybów wyświetlania

• Karuzela: logo przesuwane o stronę lub o jedno logo, w 1 do 3 rzędach, ze strzałkami, kropkami i automatycznym przewijaniem.
• Przewijanie ciągłe: logo przesuwające się bez przerwy w 1 do 4 rzędach.
• Przewijanie pionowe: 1 do 4 kolumn przesuwających się w górę lub w dół.
• Siatka: karty w kolumnach, z opcjonalnym wyszukiwaniem, filtrem liter i przyciskiem „Pokaż więcej”.
• Ściana logo: siatka bez kart, logo oddzielone cienkimi liniami.
• Rotująca ściana: stała siatka, w której logo zmieniają się po kolei.
• Etykiety: nazwy marek w kompaktowych etykietach, z opcjonalnym małym logo. Dobre do kolumny bocznej.
• Katalog A-Z: wszystkie marki pogrupowane według litery, z klikalnym paskiem liter i wyszukiwaniem.

Kolumny

Liczbę kolumn ustawia się osobno na komputer (1 do 12), tablet (1 do 8) i telefon (1 do 4). Progi zależą od szerokości dostępnej dla bloku, a nie od szerokości ekranu: blok w kolumnie bocznej korzysta z ustawienia dla telefonu nawet na dużym ekranie.

• Rzędy (karuzela i rotująca ściana): 1 do 3. W karuzeli logo wypełniają każdą kolumnę od góry do dołu, a potem rzędy przewijają się razem.
• Pokaż fragment następnego logo (karuzela): na tablecie i telefonie wystaje fragment kolejnego logo, co pokazuje, że listę można przesuwać. Boczne strzałki są wtedy ukrywane na telefonie.
• Rzędy przed Pokaż więcej (siatka i ściana logo): 0 wyświetla wszystko od razu.

Przewijanie ciągłe i pionowe

• Rzędy (lub kolumny w trybie pionowym): 1 do 4, nigdy więcej niż liczba marek.
• Różne marki w każdym rzędzie: marki są rozdzielane między rzędy. Po wyłączeniu każdy rząd pokazuje wszystkie marki z przesunięciem. Rozdzielanie wymaga co najmniej 3 marek na rząd, w przeciwnym razie moduł przesuwa rzędy.
• Szerokość logo (poziomo) lub Wysokość bloku (pionowo).

Wyszukiwanie i filtry

Pole wyszukiwania (siatka, ściana logo, katalog) filtruje marki podczas pisania, ignorując akcenty i interpunkcję. Filtr liter (siatka i ściana logo) pokazuje pasek 0-9, A do Z oraz # dla nazw, które nie zaczynają się ani od litery, ani od cyfry. Litery bez marek są wyszarzone. Katalog obsługuje od 1 do 6 kolumn i małe logo obok nazw.

Odstępy i szerokość

• Odstęp między logo i odstęp pionowy sekcji.
• Szerokość: szerokość położenia, tło na pełną szerokość (tło zajmuje cały ekran, treść zostaje w kolumnie motywu) lub pełna szerokość od krawędzi do krawędzi (przydatna dla przewijania ciągłego przez cały ekran).

Zakładka Styl

Karty marek

• Styl kart: wypełnione, obrys, cień lub bez stylu.
• Maksymalna wysokość logo, minimalna wysokość kart, wewnętrzny odstęp i zaokrąglenie narożników.
• Nazwa marki: tylko bez logo, zawsze pod logo lub po najechaniu.
• Krótki opis: pierwsze 160 znaków krótkiego opisu marki.

Logo

• Liczba produktów pod logo lub w etykiecie.
• Efekt logo: brak, skala szarości i kolor po najechaniu, zawsze w skali szarości, przygaszone i pełne po najechaniu.
• Efekt po najechaniu na kartę: uniesienie, powiększenie logo, obrys w kolorze akcentu lub brak.
• Usuń białe tła: stapia biel logo JPG z jasnymi kartami. Na ciemnym tle pozostaw wyłączone i użyj przezroczystych logo.
• Rozmiar obrazu: zalecany jest obraz oryginalny. Rozmiary PrestaShop często dodają białe marginesy wokół logo.

Kolory

Można ustawić sześć kolorów: akcent (strzałki, linki, aktywna litera), tło kart, obramowania, tło sekcji, tytuł i tekst. „Resetuj” oddaje kolor motywowi. Tekst na kolorze akcentu automatycznie zmienia się na biały lub czarny zależnie od kontrastu.

Zakładka Animacja

Karuzela

• Automatyczne przewijanie i pauza między stronami (od 1 do 15 sekund).
• Czas przejścia i krok: cała strona lub jedno logo.
• Powrót na początek po dojściu do końca: po ostatnim logo karuzela wraca do pierwszego. Aby uzyskać przewijanie bez końca, użyj trybu Przewijanie ciągłe.
• Strzałki: 4 style (wypełnione, obrys, kwadratowe, minimalne) i 4 położenia (na krawędziach wystające, wewnątrz krawędzi, w nagłówku, pod logo).
• Kropki paginacji.

Karuzelę obsługuje się też klawiaturą (strzałki w lewo i w prawo), palcem i przeciąganiem myszą.

Przewijanie ciągłe i pionowe

• Kierunek: w lewo lub w prawo, w górę lub w dół.
• Naprzemienne rzędy: co drugi rząd przewija się w przeciwną stronę.
• Prędkość: od 5 do 400 pikseli na sekundę, taka sama niezależnie od długości rzędu.
• Po najechaniu: zwolnij, zatrzymaj lub kontynuuj. Zwalnianie jest stopniowe.
• Rozmyj krawędzie: logo pojawiają się i znikają płynnie na krawędziach.

Rotująca ściana

Ustaw liczbę rzędów i czas między zmianami (od 0,8 do 20 sekund). Przy każdej zmianie jedno logo siatki jest zastępowane marką, która nie jest jeszcze widoczna.

Dostępność

Przycisk pauzy, zalecany przez kryterium WCAG 2.2.2 dla treści poruszających się dłużej niż 5 sekund, pojawia się w nagłówku lub pod logo. Animacje zatrzymują się też po najechaniu, przy fokusie klawiatury, gdy karta przeglądarki jest ukryta i gdy blok opuszcza ekran. Dla odwiedzających, którzy ograniczyli animacje w systemie, przewijanie ciągłe staje się nieruchomym rzędem przewijanym ręcznie, a karuzela przestaje przesuwać się sama.

Zakładka Wyświetlanie

Położenie

Pole Hook proponuje 14 pogrupowanych położeń:

• Strona główna: displayHome.
• Wszystkie strony: displayWrapperTop, displayWrapperBottom, displayContentWrapperTop, displayContentWrapperBottom, displayNavFullWidth, displayFooterBefore, displayFooterAfter.
• Kolumny: displayLeftColumn, displayRightColumn.
• Wybrane strony: displayFooterProduct, displayFooterCategory, displayShoppingCartFooter.
• Integracja: displayDfBrandCarousel lub „Brak” dla bloku wyświetlanego tylko przez widget lub shortcode.

„Inny hook” przyjmuje dowolną nazwę zaczynającą się od display (litery, cyfry i podkreślenia). Moduł rejestruje się w nim przy zapisie. Motyw musi następnie wywoływać ten hook.

Strony i urządzenia

Strony ogranicza blok do wybranych typów stron: strona główna, kategorie, produkty, marki, strony CMS, wyszukiwanie, koszyk i zamówienie, inne strony. Nic nie zaznaczono: wszystkie strony, na których istnieje hook. Urządzenia ukrywa blok na komputerze (od 992 px), tablecie (od 576 do 991 px) lub telefonie (poniżej 576 px).

Statystyki

Z opcją „Wysyłaj kliknięcia do Google Analytics” każde kliknięcie marki wysyła zdarzenie dfbc_brand_click z parametrami dfbc_block, brand_id i brand_name. Zdarzenie trafia do dataLayer, jeśli obecny jest Google Tag Manager, w przeciwnym razie do gtag. W GTM utwórz regułę „Zdarzenie niestandardowe” dla dfbc_brand_click.

Umieszczanie bloku w innym miejscu

Zakładka Integracja modułu i sekcja „Wstaw ten blok w innym miejscu” każdego zapisanego bloku podają kody do skopiowania. Zastąp 3 numerem bloku.

• W szablonie motywu: {widget name='dfbrandcarousel' id_block=3} wyświetla ten blok niezależnie od jego hooka.
• Przez hook modułu: {hook h='displayDfBrandCarousel'} wyświetla wszystkie bloki przypisane do tego hooka, {hook h='displayDfBrandCarousel' id_block=3} konkretny blok.
• Na stronie CMS: wklej [dfbrandcarousel id="3"] w treść. Shortcode jest zastępowany blokiem, nawet gdy stoi sam w akapicie.
• Treści AJAX lub page builder: jeśli blok zostanie wstawiony po załadowaniu strony, wywołaj window.DFBC.init(kontener). window.DFBC.destroy(kontener) czysto zatrzymuje bloki przed usunięciem ich HTML.

Gdy blok pojawia się na stronie, na której moduł nie załadował swoich plików (widget w szablonie, własny hook), blok dodaje je sam, raz na stronę.

Logo marek

Zakładka Logo marek zawiera wszystkie aktywne marki z ich logo PrestaShop i liczbą produktów.

• Alternatywne logo: prześlij plik PNG, JPG, WebP, GIF lub SVG do 2 MB. Zastępuje ono logo PrestaShop we wszystkich blokach. „Usuń” przywraca oryginalne logo.
• Własny link: pełny adres URL (https://…) lub ścieżka zaczynająca się od /. Link do innej witryny otwiera się w nowej karcie. Pusty prowadzi do strony marki.

Pliki SVG zawierające skrypty, atrybuty zdarzeń, osadzone obiekty lub linki zewnętrzne są odrzucane: wyeksportuj je ponownie jako prosty SVG. Pliki trafiają do /img/dfbrandcarousel/, którego plik .htaccess blokuje wykonywanie skryptów i nakłada politykę bezpieczeństwa na pliki SVG.

Jeśli moduł optymalizacji obrazów utworzył wersje .webp lub .avif obok logo PrestaShop w /img/m/, są one automatycznie serwowane zgodnym przeglądarkom.

Dostosowanie HTML

Skopiuj modules/dfbrandcarousel/views/templates/hook/dfbrandcarousel.tpl do themes/twoj-motyw/modules/dfbrandcarousel/views/templates/hook/dfbrandcarousel.tpl i edytuj kopię. Aktualizacje modułu jej nie nadpisują. Wszystkie wartości w szablonie są już zabezpieczone przez moduł, stąd użycie nofilter.

Każdy blok jest generowany w elemencie <section class="dfbc dfbc--TRYB"> z identyfikatorem dfbc-NUMER-N. Do celowanego CSS używaj raczej klas, na przykład:

.dfbc--marquee .dfbc-card { border-radius: 999px; }

Multisklep i języki

Bloki zarządza się osobno dla każdego sklepu: przed edycją wybierz sklep w selektorze panelu. Logo zastępcze i własne linki są wspólne dla wszystkich sklepów. Tytuł, podtytuł i tekst linku wpisuje się dla każdego języka. Moduł jest przetłumaczony na angielski, francuski, hiszpański, niemiecki, włoski, niderlandzki, polski i portugalski oraz obsługuje języki pisane od prawej do lewej.

Pamięć podręczna i wydajność

Moduł nie ładuje jQuery, Swipera ani żadnej zewnętrznej biblioteki. Jego CSS i JavaScript ważą po kompresji około 5 KB i 7 KB i są ładowane tylko na stronach, na których może pojawić się blok: blok w displayHome nie ładuje niczego na kartach produktów.

Lista marek jest przechowywana w pamięci podręcznej przez 6 godzin, liczba produktów na markę przez 1 godzinę, a sprzedaż przez 12 godzin, w var/cache/. Pamięć ta jest czyszczona przy każdym zapisie w module oraz przy dodaniu, zmianie lub usunięciu marki albo produktu. PrestaShop uruchamia te wyzwalacze tylko dla pracowników z prawem podglądu modułu: jeśli katalog zmienia osoba bez tego prawa, użyj przycisku „Wyczyść pamięć podręczną”.

Najczęstsze pytania

Blok się nie wyświetla

Sprawdź, czy blok jest aktywny, czy motyw wywołuje jego hook i czy filtry Strony i Urządzenia dopuszczają bieżącą stronę. Następnie sprawdź, czy zostały marki do wyświetlenia: podgląd w edytorze podaje liczbę wybranych marek i wyświetla komunikat, gdy żadna nie pasuje (źródło, minimalna liczba produktów, filtr logo).

Logo mają białe prostokąty

Logo PrestaShop to pliki JPG na białym tle. Włącz „Usuń białe tła” na jasnych kartach lub prześlij przezroczyste logo w zakładce Logo marek.

Logo są rozmyte

Wybierz „Obraz oryginalny” w Rozmiarze obrazu albo prześlij logo zastępcze jako SVG lub PNG w wysokiej rozdzielczości.

Przewijanie się nie porusza

Mógł zostać naciśnięty przycisk pauzy albo system odwiedzającego wymaga ograniczenia animacji. W tym drugim przypadku moduł celowo pokazuje nieruchome logo.

Brakuje marki

Marka musi być aktywna, przypisana do sklepu i mieć co najmniej minimalną liczbę widocznych produktów. Sprawdź też listę wykluczonych marek i opcję „Tylko marki z logo”.

Odinstalowanie

Odinstalowanie usuwa tabele modułu, folder /img/dfbrandcarousel/ z logo zastępczymi oraz pamięć podręczną modułu.