Documentatie DfStreamCategoryTree voor Shopware 6

DfStreamCategoryTree voegt een veld Category (including subcategories) toe aan de conditiebouwer van de dynamische productgroepen van Shopware 6. Filteren op een bovenliggende categorie neemt dan alle producten mee die in de onderliggende categorieën zijn ondergebracht, ongeacht de diepte.

Het probleem dat de plugin oplost

De native conditiebouwer biedt een veld Categories dat de relatie product.categoriesRo bevraagt. Die relatie bevat alleen de categorieën waaraan een product expliciet is gekoppeld op zijn tabblad Categories.

Een goed geordende catalogus plaatst zijn producten in de eindcategorieën. Een sneakermodel wordt toegewezen aan Heren / Schoenen / Sneakers, niet aan Heren. Een filter op Heren levert dus alleen de zeldzame producten op die rechtstreeks op dat niveau zijn toegewezen, vaak helemaal niets.

De native oplossing bestaat erin elke subcategorie handmatig aan te vinken en de configuratie van de stream opnieuw te openen bij elke wijziging van de boomstructuur. Deze plugin maakt dat onderhoud overbodig.

Hoe het werkt

Shopware onderhoudt voor elk product al een JSON-veld categoryTree dat de identificatie bevat van alle categorieën in het pad, van de wortel tot de categorie van toewijzing. Dat veld wordt door de native CategoryIndexer herberekend bij elke verplaatsing van een categorie en bij elke wijziging van een producttoewijzing.

Een equalsAny-filter op dat veld met de identificatie van een bovenliggende categorie haalt dus alle producten op waarvan het pad daarlangs loopt. Het veld bestaat en werkt perfect in de DAL, maar de administration toont het niet in de kiezer van de conditiebouwer: het staat niet in de toegestane lijst van de service productStreamConditionService.

De plugin voegt een item aan die toegestane lijst toe en levert de bijbehorende vertaalde labels. Hij introduceert geen servicedecorator, geen listener op productevents, geen tabel en geen migratie.

Vereisten

• Shopware 6.7.x, zelfgehost
• PHP 8.2 of hoger
• Toegang tot de commandoregel of een deploymentpijplijn die de administration opnieuw kan compileren

De plugin werkt niet op Shopware Cloud, omdat de door Shopware gehoste SaaS-versie de installatie van serverplugins niet toestaat.

Installatie

Via ZIP-upload

1. Open in de administration Extensies en daarna Mijn extensies
2. Klik op Extensie uploaden en selecteer het archief DfStreamCategoryTree-1.0.0.zip
3. Installeer en activeer de plugin
4. Compileer de administration opnieuw (zie het volgende hoofdstuk)

Door de map te plaatsen

Pak het archief uit in de map met eigen plugins van uw instantie en voer daarna uit:

bin/console plugin:refresh
bin/console plugin:install --activate DfStreamCategoryTree
bin/console cache:clear

De administration opnieuw compileren

De plugin wijzigt het gedrag van de administratie-interface. Na de installatie is één hercompilatie van de adminbundel nodig, anders verschijnt het nieuwe veld niet in de conditiekiezer.

bin/console bundle:dump
./bin/build-administration.sh
bin/console cache:clear

In een productieomgeving die door een deploymentpijplijn wordt beheerd, maakt deze stap meestal al deel uit van het standaardproces. Leeg daarna de cache van uw browser of open de administration in een privévenster om zeker de bijgewerkte bundel te laden.

Gebruik

Een recursieve dynamische groep aanmaken

1. Open Catalogi en daarna Dynamic product groups
2. Maak een nieuwe groep aan of open een bestaande groep
3. Klap in de conditiebouwer de veldkiezer uit
4. Kies Category (including subcategories), net boven het oorspronkelijke item Categories
5. Kies de operator Is equal to any of
6. Selecteer een of meer bovenliggende categorieën in het waardeveld
7. Sla op en open daarna het tabblad Preview om het aantal teruggegeven producten te controleren

Beschikbare operatoren

• Is equal to any of: het product hoort bij de substructuur van ten minste één van de geselecteerde categorieën
• Is not equal to any of: het product hoort bij de substructuur van geen enkele geselecteerde categorie, nuttig om een hele afdeling van een actie uit te sluiten

Combineren met andere condities

Het veld gedraagt zich als elke andere conditie van de stream. Het combineert vrij met de fabrikant, de prijs, de voorraadstatus, de eigenschappen en de tags, en werkt in de geneste AND- en OR-groepen van de bouwer.

Typisch voorbeeld voor een uitverkoopactie: Category (including subcategories) is equal to any of Heren, EN Stock is greater than 0, EN Price is greater than 50.

Waar de groep bruikbaar is

• Navigatiecategoriepagina die door een dynamische groep wordt gevoed
• Productblokken in de Shopping Experiences
• Condities van promotieregels
• Automatische cross-selling op de productpagina
• Elke integratie die een product stream gebruikt via de Admin API of de Store API

Gebruik via de Admin API

Omdat het veld native is in de DAL, werkt een conditie die rechtstreeks via de API wordt gezet ook zonder de plugin. De plugin dient om dat filter zichtbaar en bewerkbaar te maken in de interface, wat telt zodra een marketingteam de groepen beheert zonder via de API te gaan.

POST /api/product-stream
{
  "name": "De hele afdeling Heren",
  "filters": [
    {
      "type": "equalsAny",
      "field": "product.categoryTree",
      "value": "01920f7c8a3d71c2b4e5f6a7b8c9d0e1"
    }
  ]
}

Zonder de plugin blijft een stream met dit filter aan DAL-zijde werken, maar het veld is dan niet zichtbaar in de conditiebouwer.

Probleemoplossing

Het veld verschijnt niet in de kiezer

In de overgrote meerderheid van de gevallen is de administration na de installatie niet opnieuw gecompileerd. Draai de reeks bundle:dump, build-administration en daarna cache:clear opnieuw, en herlaad de administration met een lege browsercache. Controleer ook of de plugin actief is onder Extensies en daarna Mijn extensies.

De groep geeft nog steeds niet de juiste producten terug

Controleer of u het nieuwe veld hebt gekozen en niet het oorspronkelijke item Categories, want beide staan naast elkaar in de kiezer. Controleer daarna op de kaart van een verwacht product of dat aan een subcategorie van de gekozen ouder is toegewezen, en of het actief en zichtbaar is op het betreffende verkoopkanaal.

Een recent verplaatst product komt niet naar boven

Het veld categoryTree wordt door de native CategoryIndexer herberekend. Loopt de berichtenwachtrij achter of is de indexering gepauzeerd, forceer dan een herindexering:

bin/console dal:refresh:index --only=product.indexer,category.indexer

Opnieuw instellen na een grote Shopware-update

Compileer na een minor versie-upgrade van Shopware de administration opnieuw zodat de plugin zijn item in de toegestane lijst opnieuw registreert. Verdere actie is niet nodig, want de plugin slaat geen gegevens op.

Verwijderen

Deactiveer en verwijder de plugin via Extensies of vanaf de commandoregel. De plugin maakt geen tabel aan en slaat geen configuratie op, dus het verwijderen is volledig neutraal.

bin/console plugin:deactivate DfStreamCategoryTree
bin/console plugin:uninstall DfStreamCategoryTree

Dynamische groepen die al met het filter zijn ingesteld, blijven werken: de conditie staat in de database als een standaard DAL-filter en wordt door de native engine geëvalueerd. Alleen de weergave van het veld in de conditiebouwer verdwijnt, waardoor het filter niet meer via de interface aanpasbaar is zolang de plugin niet opnieuw is geactiveerd. Er gaan geen gegevens verloren.

Bekende beperkingen

• De plugin geldt niet voor de listingfilters van de storefront en evenmin voor de facetnavigatie, die op een apart mechanisme berusten
• Hij wijzigt het indexeringsalgoritme van de categorieën niet, hij gebruikt het veld dat Shopware al produceert
• Hij werkt niet op Shopware Cloud