Categoriebanner: volledige gids
Categoriebanners installeren, instellen en beheren: positie en formaat in het raster, mobiele afbeelding, link per taal, planning op datum in de tijd van de winkel, subcategorieën, Creative Elements, multishop en probleemoplossing voor PrestaShop 1.7, 8 en 9.
Overzicht en vereisten
Categoriebanner plaatst visuals in het productraster van uw categoriepagina’s, op de positie die u kiest. U geeft de categorie op, het productnummer waarna de banner moet verschijnen en de afbeelding per taal. De module doet de rest, ook na een facetfilter of een paginawissel.
- Compatibel met PrestaShop 1.7.6 tot 9.x, gecontroleerd op 1.7.8, 8.2.1 en 9.1.5: Classic- en Hummingbird-thema, afgeleide thema’s, overzichten van Creative Elements, CSS-grid-thema’s.
- PHP 7.4 tot 8.5.
- Multishop en meertalig (fr, en, es, de, it, nl, pl, pt).
- Geen override, geen templatewijziging, geen CRON-taak.
- De HTML van de banner wordt serverzijde opgebouwd met een Smarty-template; de JavaScript zet hem alleen op de juiste plek, zonder jQuery en zonder externe bibliotheek.
Geüploade afbeeldingen staan in /img/datafireflycategorybanner/, buiten de modulemap. Ze overleven dus module-updates.

Installatie
- Download het archief
datafireflycategorybanner.zipvanuit uw klantaccount. - Open in de beheeromgeving Modules > Modulebeheer.
- Klik op Een module uploaden en sleep het archief erin.
- Klik op Configureren om bij de bannerlijst te komen.
Bij de installatie maakt de module haar drie tabellen aan (banners, vertalingen, winkelkoppeling), maakt ze de map /img/datafireflycategorybanner/ aan en registreert ze haar hooks.

Een banner aanmaken
Klik op de configuratiepagina op Nieuwe banner toevoegen. Het formulier bundelt de volgende instellingen.
Targeting
- Categorie: de categorie waarin de banner verschijnt. De lijst volgt de winkelboom, met uitgeschakelde categorieën gemarkeerd.
- Toepassen op subcategorieën: breidt de banner uit naar alle subcategorieën van de gekozen categorie, ongeacht de diepte.
- Na productnummer: de banner wordt na dit product in de lijst geplaatst. De waarde 4 zet de banner na het vierde getoonde product.
- Alleen op de eerste pagina: toont de banner alleen op de eerste pagina van de lijst, zonder hem te herhalen op pagina 2, 3 enzovoort.

Weergave en link
- Bannerlink: doel-URL, absoluut (
https://…) of beginnend met een schuine streep (/nieuw). Laat leeg voor een banner zonder link. - Breedte in het raster: aantal productkolommen dat de banner beslaat, van 1 tot 4, of Volle rij. Op schermen met minder kolommen wordt de breedte automatisch beperkt.
- Hoogte in het raster: aantal productrijen dat de banner beslaat, van 1 tot 3. Beschikbaar bij overzichten met een CSS-grid (Creative Elements, de meeste recente thema’s).
- Weergave van de afbeelding: Bannervlak vullen snijdt de afbeelding bij tot de grootte van de cel, Verhoudingen van de afbeelding behouden toont haar volledig.
- CSS-klasse: extra klassen voor de bannercel. Leeg laten om de klassen van de productcellen van uw thema over te nemen. Met een breedte en hoogte van 1 blijft een formaatklasse van uw thema (bijvoorbeeld een die
grid-areainstelt) van toepassing. - Eigen CSS: declaraties die alleen voor deze banner gelden, bijvoorbeeld
border-radius: 12px; padding: 10px;.
Planning en status
- Startdatum en Einddatum: weergavevenster, in het formaat
JJJJ-MM-DD UU:MM:SS. Een leeg veld betekent geen grens aan die kant. - Actief: toont of pauzeert de banner zonder hem te verwijderen.
- Winkelkoppeling: vink in multishop de betreffende winkels aan.
Afbeeldingen per taal
De velden Bannerafbeelding, Mobiele afbeelding, Alt-tekst en Link voor deze taal bestaan voor elke actieve taal. De taalkeuze direct boven deze velden toont de velden van de gekozen taal. Is er al een afbeelding, dan verschijnt een voorbeeld met daarnaast een schakelaar Afbeelding verwijderen die alleen die taal raakt.
Toegestane formaten: JPG, PNG, GIF, WebP en SVG, tot 4 MB. Een breedte van 1200 px past bij de meeste rasters.

Hoe de positie wordt berekend
De positie wordt uitgedrukt in aantal producten en geldt voor elke pagina van de lijst. Een banner op 4 verschijnt na het vierde product van de huidige pagina, of de bezoeker nu op pagina 1 of pagina 3 zit.
Meerdere banners kunnen dezelfde categorie betreffen, elk op zijn eigen positie. Delen twee banners dezelfde positie, dan worden ze na elkaar geplaatst in de volgorde van opslaan. Overschrijdt de positie het aantal producten op de pagina, dan wordt de banner voor die pagina gewoon overgeslagen, zonder de andere te verschuiven.
Standaard neemt de banner de plaats van één productcel in. De velden Breedte in het raster en Hoogte in het raster maken hem groter, zoals hieronder uitgelegd.

Formaat van de banner in het raster
Elke banner beslaat een blok productcellen: standaard 1 × 1, tot 4 kolommen over 3 rijen, of de volle rij. De producten na de banner vullen de vrijgekomen cellen, zodat het raster geen gat houdt.
- Overzichten met een CSS-grid (Creative Elements, de meeste recente thema’s): breedte en hoogte gelden allebei. Een banner van 2 × 2 na het 4e product van een raster met vier kolommen beslaat de eerste twee kolommen van rij 2 en 3, en de producten 5 tot 8 staan ernaast.
- Bootstrap-rijen (Classic-thema): de breedte geldt, als deel van de rij. De hoogte volgt de afbeelding.
- Kleine schermen: de breedte wordt beperkt tot het aantal getoonde kolommen. Een banner van vier kolommen in een mobiel raster van twee kolommen gaat over de volle rij.
In de vulmodus bedekt de afbeelding het hele vlak, neemt ze de hoogte van de producten ernaast over en wordt ze vanuit het midden bijgesneden. Een banner over de volle rij behoudt altijd zijn verhoudingen, omdat er geen product naast staat dat hem een hoogte geeft: gebruik er een liggende afbeelding voor.
Bereid voor een banner van 2 × 2 in de vulmodus een afbeelding voor die iets hoger dan breed is, en houd de kernboodschap in het midden, want de randen kunnen worden bijgesneden.


Een actie plannen
Vul een startdatum en een einddatum in zodat een banner vanzelf verschijnt en verdwijnt. Dat is het juiste middel om uitverkoop, Black Friday of een eindejaarsactie weken vooruit voor te bereiden.
- Alleen startdatum: de banner verschijnt op die datum en blijft daarna zichtbaar.
- Alleen einddatum: de banner is meteen zichtbaar en stopt op die datum.
- Beide datums: de banner is alleen binnen dat venster zichtbaar.
- Geen datum: de banner is permanent.
De datums worden ingevoerd en vergeleken in de tijd van de winkel, dus in de tijdzone die is ingesteld onder Internationaal > Lokalisatie, niet in de tijd van de bezoeker. Een einddatum zonder tijdstip loopt tot 23:59:59.

Een hele boom afdekken
De optie Toepassen op subcategorieën bespaart u het opnieuw aanmaken van dezelfde banner in elke afdeling. Ingesteld op een bovenliggende categorie verschijnt de banner in die categorie en in al haar afstammelingen.
De bepaling steunt op de ingebouwde geneste boom van PrestaShop (kolommen nleft en nright) en kost dus geen extra query per pagina. Verplaatst u categorieën, dan herberekent PrestaShop die waarden en volgt het bereik automatisch.
Afbeeldingen en talen
Elke banner accepteert een beeld en een alt-tekst per taal, waarmee u een boodschap of een prijs per markt kunt aanpassen. Heeft een taal geen eigen beeld gekregen, dan toont de module dat van de standaardtaal van de winkel in plaats van de banner te verbergen. De eigen alt-tekst van de taal blijft behouden als die is ingevuld.
Elk beeld kan worden aangevuld met een optionele mobiele afbeelding: die wordt getoond op schermen van maximaal 767 px breed, met haar eigen afmetingen. Maak haar staand voor een banner over de volle rij.
De afmetingen van de afbeelding worden bij het uploaden uitgelezen en in de HTML-attributen width en height geschreven, wat layoutverschuiving bij het laden voorkomt. De banner die direct bij het openen van de pagina zichtbaar is, wordt met voorrang geladen (fetchpriority="high"), de andere uitgesteld (loading="lazy"). Bestanden krijgen een willekeurig achtervoegsel en worden opgeslagen in /img/datafireflycategorybanner/.
Alt-tekst wordt gelezen door zoekmachines en schermlezers. Beschrijf wat het beeld toont in plaats van de categorienaam te herhalen.

Multishop
Is de multishopfunctie actief, dan toont het formulier een blok Winkelkoppeling. Een banner verschijnt alleen in de aangevinkte winkels, en de lijst in de beheeromgeving toont enkel de banners die zichtbaar zijn in de huidige winkelcontext.
Vinkt u geen winkel aan, dan koppelt de module de banner aan de huidige context, zodat er nooit een banner zonder winkel ontstaat.
Facetfilters, sortering en paginering
In PrestaShop 8 en 9 herladen facetfilters, sortering en paginering de productlijst via AJAX zonder de pagina te herladen. De module houdt de lijst in de gaten: zodra er nieuwe productcellen verschijnen, na een filter, een paginawissel, een knop “meer laden” of oneindig scrollen, zet ze de banners terug op de juiste plek. Ze luistert ook naar het updateProductList-event van PrestaShop.
Het productraster wordt herkend aan de producten zelf (kenmerken data-id-product en product-miniature), niet aan de klassen van een bepaald thema. Dat dekt het Classic-thema, overzichten van Creative Elements en de meeste thema’s op maat.
CSS en JavaScript worden alleen op categoriepagina’s geladen, en alleen wanneer de huidige categorie minstens één actieve en toonbare banner heeft.
Instellingen: selector van het productraster
Onder de bannerlijst bevat het onderdeel Instellingen één veld, Selector van het productraster. Laat het leeg: het raster wordt automatisch herkend.
Alleen als de banners op een thema met een ongebruikelijke structuur nooit verschijnen, vult u de CSS-selector in van het element dat de productcellen direct bevat, bijvoorbeeld #js-product-list .products of .ce-products. Vindt de module het raster niet, dan schrijft ze een waarschuwing [DataFirefly Category Banner] in de browserconsole.
Nieuw in versie 1.3.0
Versie 1.3.0 verhelpt een aantal gebreken die bij een volledige controle op PrestaShop 1.7.8, 8.2.1 en 9.1.5 aan het licht kwamen, en voegt enkele instellingen toe.
- Mobiele afbeelding: elke taal accepteert een tweede afbeelding, die wordt getoond op schermen van maximaal 767 px breed. Handig voor een banner over de volle rij, die in liggend formaat op een telefoon slecht leesbaar is.
- Link per taal: een optionele link per taal vervangt de gemeenschappelijke link, zodat u kunt verwijzen naar een pagina met een vertaald adres, bijvoorbeeld
/en/content/1-delivery. - Alleen op de eerste pagina: de banner wordt niet meer herhaald op pagina 2, 3 enzovoort van de lijst. Hij verschijnt weer zodra de bezoeker terugkeert naar pagina 1 of een filter toepast.
- Datumkalender: de kalender in het formulier vult nu het juiste formaat in. Een einddatum zonder tijdstip loopt tot 23:59:59.
- Tijd van de winkel: de datums worden vergeleken met de tijd van de winkel. Voorheen verschoof de klok van de MySQL-server, vaak ingesteld op UTC, het begin en het einde met een tot twee uur.
- Core Web Vitals: de banners worden direct na het productraster ingevoegd (hook
displayFooterCategory), nog voor de eerste weergave, waardoor de layoutverschuiving (CLS) verdwijnt. De banner die bij het openen van de pagina zichtbaar is, wordt met voorrang geladen, de volgende uitgesteld. - Beveiliging van afbeeldingen: SVG’s met een script, een event handler of externe inhoud worden geweigerd, en de map
/img/datafireflycategorybanner/krijgt een eigen.htaccess(alleen afbeeldingen, SVG’s afgeschermd). Een geweigerde afbeelding levert geen lege banner meer op. - WebP op PrestaShop 1.7: WebP-afbeeldingen worden geaccepteerd en correct getoond.
- Lijst in de beheeromgeving: kolom Afbeeldingen met de talen die een beeld hebben, en vermelding van afgelopen of geplande banners.
Installeer voor de update het archief 1.3.0 via modulebeheer over de huidige versie heen. Uw banners en afbeeldingen blijven behouden. Leeg daarna de cache van PrestaShop en die van elke prestatiemodule.
Bijwerken naar versie 1.2.0
Installeer het archief 1.2.0 via de modulebeheerder over de vorige versie heen. Het updatescript voegt de kolommen voor formaat en beeldweergave toe, plus de instelling voor de rasterselector. Bestaande banners behouden hun huidige weergave: 1 × 1, verhoudingen van de afbeelding behouden. Bewerk een banner om hem een ander formaat te geven of naar de vulmodus te zetten.
Het frontscript verandert in deze versie. Leeg na de update de cache van PrestaShop en die van elke prestatiemodule (CCC, paginacache, minificatie), anders wordt het vorige script verder uitgeserveerd.
Bijwerken vanaf versie 1.0.0
Installeer het nieuwe archief gewoon over het oude heen vanuit modulebeheer. Het upgradescript zorgt voor:
- het toevoegen van de kolommen voor bereik, planning en afbeeldingsafmetingen;
- het aanmaken van de winkelkoppeltabel en het overnemen van de oorspronkelijke winkel van elke banner;
- het verplaatsen van bestaande afbeeldingen van
views/img/banners/naar/img/datafireflycategorybanner/en het uitlezen van hun afmetingen; - het verwijderen van een hook die niet meer nodig is.
Uw banners, hun posities en hun beelden blijven behouden.
FAQ en probleemoplossing
De banner verschijnt niet op de categoriepagina
Controleer op volgorde: de banner is actief; de datum van vandaag valt binnen het planningsvenster; de gekozen categorie is de bekeken categorie, of het subcategoriebereik staat aan; de getoonde taal heeft een afbeelding, of de standaardtaal heeft er een; in multishop is de huidige winkel aangevinkt. Leeg tot slot de PrestaShop-cache.
Bij een overzicht dat met Creative Elements of een andere paginabouwer is gemaakt, controleert u of de module op versie 1.2.0 of hoger staat: eerdere versies herkenden alleen het raster van het Classic-thema. Open daarna de browserconsole: een waarschuwing [DataFirefly Category Banner] betekent dat het raster niet is gevonden, zie het onderdeel Instellingen.
De banner staat op de verkeerde plek
De positie telt de producten van de huidige pagina. Toont uw lijst 12 producten per pagina, dan verschijnt een banner op positie 20 nergens. Verlaag de waarde of verhoog het aantal producten per pagina.
De banner breekt de rasterindeling
Stel het formaat in met de velden Breedte in het raster en Hoogte in het raster in plaats van met rasterklassen, en maak het veld CSS-klasse leeg tenzij uw thema een formaatklasse biedt. Meng geen klassen van verschillende rastersystemen.
De banner verdwijnt na filteren
Sinds versie 1.2.0 plaatst de module de banners terug zodra er nieuwe productcellen in de lijst verschijnen, welke filtermodule u ook gebruikt. Verdwijnt de banner toch, open dan de browserconsole: een waarschuwing [DataFirefly Category Banner] betekent dat het raster na de vernieuwing niet is gevonden. Vul dan de selector van het raster in bij Instellingen en neem contact op met de support als het probleem blijft.
De afbeelding wil niet uploaden
De module accepteert JPG, PNG, GIF, WebP en SVG tot 4 MB. Controleer ook of /img/datafireflycategorybanner/ beschrijfbaar is en of de PHP-instellingen upload_max_filesize en post_max_size groter zijn dan het bestand.
De bannerlink wordt geweigerd
Alleen URL’s die met http://, https:// of een schuine streep beginnen worden aanvaard. Dat beschermt tegen het injecteren van javascript: of data: adressen.
Wat gebeurt er bij het verwijderen van de module?
De module verwijdert haar tabellen en de map /img/datafireflycategorybanner/ met de beelden erin. Maak een back-up van uw afbeeldingen als u later opnieuw wilt installeren.