Verkoopteller Shopware 6: installatie- en configuratiegids

Deze gids behandelt de installatie, configuratie en aanpassing van de plugin DfSalesCounter, die op elke productpagina toont hoe vaak een product al verkocht is, op basis van de echte bestellingen van uw Shopware 6 shop.

Vereisten

• Shopware 6.5.x, 6.6.x of 6.7.x in een zelfgehoste installatie. Shopware Cloud (SaaS) accepteert geen serverplugins.
• PHP 8.1 of hoger.
• Een storefront-thema afgeleid van het Storefront-thema van Shopware, of een aangepast thema dat de standaard Twig-blokken van het koopblok behoudt.
• Toegang tot de commandoregel wordt aanbevolen voor het compileren van het thema, maar installatie via de administration werkt eveneens.

Installatie

Via ZIP-upload vanuit de administration

1. Open in de Shopware-administration Extensies en daarna Mijn extensies.
2. Klik op Extensie uploaden en selecteer het bestand DfSalesCounter-1.0.0.zip.
3. Zodra de plugin in de lijst staat, klikt u op Installeren en activeert u hem met de schakelaar.
4. Compileer het thema opnieuw via Content, Thema’s, door uw thema te selecteren en daarna Thema opnieuw compileren te kiezen. Deze stap is eenmalig nodig, omdat de plugin een storefront-stylesheet levert.

Via de commandoregel

Plaats de map DfSalesCounter in custom/plugins/ van uw installatie en voer daarna uit:

bin/console plugin:refresh
bin/console plugin:install --activate DfSalesCounter
bin/console theme:compile
bin/console cache:clear

In een omgeving met een deploymentpipeline maakt het compileren van het thema meestal al deel uit van de standaardstappen.

Configuratie

De configuratiepagina vindt u onder Extensies, Mijn extensies, de knop … rechts van DataFirefly Sales Counter, en daarna Configureren. Met de keuzelijst bovenaan de pagina kiest u het verkoopkanaal waarop de configuratie van toepassing is: elk kanaal kan zijn eigen drempel, tekst en positie hebben.

Tabblad Algemeen

• Verkoopteller activeren: hoofdschakelaar. Uitgeschakeld wordt er geen enkele query uitgevoerd en geen badge gerenderd.
• Telmodus: Verkochte hoeveelheid telt alle bestelde hoeveelheden van het product bij elkaar op. Aantal bestellingen telt de afzonderlijke bestellingen waarin het product voorkwam. De eerste modus benadrukt het volume, de tweede het aantal verschillende overtuigde klanten.
• Meegetelde bestellingen: Alle bestellingen geeft het brutocijfer. Geannuleerde bestellingen uitsluiten laat bestellingen met de statusmachine cancelled buiten beschouwing. Alleen betaalde bestellingen behoudt enkel bestellingen met een transactie in de status paid of paid_partially.
• Minimale drempel vóór weergave: onder deze waarde verschijnt er geen badge. De standaardwaarde is 5. Een drempel van 0 wordt behandeld als 1, de badge wordt nooit getoond voor een product zonder verkopen.
• Periode in dagen: beperkt de telling tot de laatste X dagen, op basis van de besteldatum. De waarde 0 betekent een totaal sinds het begin.
• Verkopen van alle varianten optellen: telt de verkopen van het hoofdproduct en van al zijn varianten bij elkaar op. Aanbevolen bij een mode- of maatcatalogus, uit te schakelen als elke variant een afzonderlijk gebruik vertegenwoordigt.
• Alleen bestellingen van het huidige verkoopkanaal tellen: voorkomt dat een B2B-shop of een exportkanaal de cijfers op de consumentenshop opdrijft.

Tabblad Weergave

• Positie op de productpagina: Onder de productnaam, Onder de prijs, of Onder het koopblok, dus onderaan het blok, onder de knop toevoegen aan winkelwagen.
• Visuele stijl: Badge geeft een omlijnde pil, Platte tekst geeft een regel zonder omlijsting, Banner geeft een blok over de volle breedte met een gekleurde zijbalk.
• Icoon: vlam, winkelwagen, vinkje, of geen. De iconen zijn inline gerenderde SVG’s, er wordt geen icoonlettertype geladen.
• Accentkleur: als deze leeg blijft, wordt de primaire kleur van het thema gebruikt. Ingevuld voedt hij de CSS-variabele --df-sales-counter-accent op het element van de badge.
• Duizendtalscheidingsteken: smalle spatie, komma, punt of geen. Nuttig zodra de tellers boven de duizend uitkomen.
• Aangepaste tekst: zie het volgende hoofdstuk.
• Cacheduur in seconden: standaard 900. De waarde 0 schakelt de cache uit en bevraagt de database bij elke weergave van een productpagina.

De tekst aanpassen

Globale tekst vanuit de configuratie

Het veld Aangepaste tekst accepteert een zin met de markering %count% op de plek waar het aantal moet verschijnen. Voorbeeld: Dit model ging deze maand %count% keer over de toonbank. Deze tekst geldt voor alle talen van het verkoopkanaal. Hij wordt vóór het renderen opgeschoond, wat eenvoudige markup zoals <strong> toestaat maar elk script blokkeert.

Teksten per taal via de snippets

Laat het veld Aangepaste tekst leeg om de tekst per taal te sturen. Open Instellingen, Shop, Snippets, en zoek op dfSalesCounter. Er zijn vier sleutels beschikbaar:

• dfSalesCounter.badge.quantitySingular en dfSalesCounter.badge.quantityPlural, gebruikt in de modus verkochte hoeveelheid.
• dfSalesCounter.badge.ordersSingular en dfSalesCounter.badge.ordersPlural, gebruikt in de modus aantal bestellingen.

Elke waarde accepteert de markering %count%. De Franse, Engelse, Spaanse, Duitse en Italiaanse vertalingen worden met de plugin meegeleverd. Een in de snippetbeheerder gewijzigde waarde heeft voorrang op die van de plugin, ook na een update.

Hoe het cijfer wordt berekend

De plugin leest de bestelregels van het type product, gekoppeld aan de bestelling en haar status. De berekening gebeurt in één enkele geaggregeerde query, zonder achtergrondverwerking en zonder aparte tabel.

• In de modus hoeveelheid telt de query de kolom met hoeveelheden van de bestelregels op.
• In de modus bestellingen telt hij de afzonderlijke bestel-identificaties.
• Alleen de huidige versie van de bestellingen wordt meegenomen, de werkversies die bij een creditnota of een wijziging van een bestelling ontstaan, worden genegeerd.
• Met het optellen van varianten ingeschakeld bepaalt de plugin eerst de familie van het getoonde product, hoofdproduct en varianten, en filtert daarna op alle identificaties samen.

Als het resultaat onder de ingestelde drempel ligt, wordt er geen extensie aan het product toegevoegd en rendert het template niets. De badge bestaat dus niet in de HTML, wat elke resterende weergave via een CSS-regel van het thema uitsluit.

Cache en actualiteit van het cijfer

Het resultaat wordt opgeslagen in de applicatiecachepool van Symfony, onder een sleutel die de identificatie van het product, het verkoopkanaal en een signatuur van de opties die de berekening beïnvloeden combineert. Een wijziging van de telmodus, van de scope van de bestellingen, van de periode of van de opteloptie verandert deze signatuur en maakt de eerdere waarden dus automatisch ongeldig.

Bij elke geplaatste bestelling leegt de plugin de cache van de producten in die bestelling, evenals die van hun hoofdproduct. De teller weerspiegelt de verkoop dus zonder het verstrijken van de ingestelde duur af te wachten.

Bij een bescheiden catalogus kan de cacheduur zonder merkbare gevolgen op 0 worden gezet: de query gebruikt geïndexeerde kolommen. Bij een grote catalogus met veel verkeer houdt u beter een duur van enkele minuten aan.

Geavanceerde aanpassing van de weergave

De plugin breidt het buy widget van de productpagina uit en voegt zijn badge toe in drie standaard Twig-blokken, afhankelijk van de gekozen positie: het blok van de productnaam, het blok van de prijscontainer en het blok van de koopcontainer. De badge zelf wordt gerenderd door een eigen componenttemplate, storefront/component/df-sales-counter/badge.html.twig, dat twee overschrijfbare blokken beschikbaar stelt voor het icoon en voor de tekst.

Vanuit een thema of een plugin is de extensie in Twig beschikbaar op het product van de pagina onder de naam dfSalesCounter. Ze stelt het ruwe aantal, het geformatteerde aantal, de positie, de stijl, het icoon, de accentkleur, de aangepaste tekst en de telmodus beschikbaar. Zo kunt u de teller elders dan in het koopblok renderen, bijvoorbeeld in een tabblad met productinformatie, door de extensie op te halen en het component in te voegen.

De stijlen staan in Resources/app/storefront/src/scss/base.scss rond de klassen df-sales-counter, df-sales-counter__icon en df-sales-counter__text, met een modifier per visuele stijl. Elke regel van uw thema die na die van de plugin wordt gecompileerd, krijgt voorrang, zonder dat u de plugin hoeft te wijzigen.

Probleemoplossing

Er verschijnt geen badge

Controleer in deze volgorde: de plugin is geactiveerd, de activeringsschakelaar staat op ja voor het juiste verkoopkanaal, het product heeft de ingestelde drempel bereikt, en de gekozen scope van de bestellingen sluit niet al uw bestellingen uit. Een drempel van 5 met de scope Alleen betaalde bestellingen op een testshop waarvan de bestellingen nooit als betaald worden gemarkeerd, levert nooit een weergave op.

De badge verschijnt zonder opmaak

Het thema is na de activering niet opnieuw gecompileerd. Voer bin/console theme:compile uit of gebruik de knop voor hercompilatie in de administration.

Het cijfer lijkt vast te staan

De cacheduur loopt nog. Leeg de applicatiecache met bin/console cache:pool:clear cache.app, of zet de duur tijdelijk op 0 om de berekening te valideren.

De badge staat niet op de juiste plek

Een sterk aangepast thema kan de Twig-blokken van het koopblok hebben verwijderd of hernoemd. Probeer een andere positie in de configuratie, of voeg het component handmatig in uw template in door de extensie van het product op te halen.

Update en verwijdering

Een update voert u uit door de nieuwe ZIP te uploaden en op Bijwerken te klikken, gevolgd door een hercompilatie van het thema als de versie stijlwijzigingen bevat. De configuratie blijft behouden.

Bij het verwijderen biedt een selectievakje aan om de gebruikersgegevens te behouden. Uitgevinkt worden alle configuratiesleutels van de plugin verwijderd. De plugin maakt geen tabellen aan en voert geen migratie uit, dus laat de verwijdering buiten zijn configuratie niets achter in de database.

Overzicht van de configuratiesleutels

Alle sleutels beginnen met DfSalesCounter.config. en zijn te beheren via de Admin API of via het commando system:config:set:

• active, boolean
• countMode, waarden quantity of orders
• orderScope, waarden all, notCancelled of paid
• minThreshold, geheel getal
• periodDays, geheel getal
• aggregateVariants, boolean
• scopeToSalesChannel, boolean
• position, waarden afterName, afterPrice of afterBuy
• style, waarden badge, inline of banner
• icon, waarden none, flame, cart of check
• accentColor, hexadecimale tekenreeks
• thousandSeparator, waarden space, comma, dot of none
• customText, tekenreeks
• cacheTtl, geheel getal in seconden