Problemen Oplossen met Cross-Linking

Symptomen:

• Keyword bestaat in de content maar er wordt geen link gegenereerd
• Pagina rendert normaal zonder cross-links

Oplossing:

1. Controleer of de module is ingeschakeld via Algemeen → Ingeschakeld
2. Controleer of het entity type is ingeschakeld (bijv. Products → Inschakelen voor Products)
3. Controleer of de cross-link regel Actief is en het keyword correct is
4. Bevestig dat de Store Views van de regel de store bevat die je bekijkt
5. Leeg alle caches: bin/magento cache:flush
6. Schakel debug mode in en controleer var/log/debug.log voor berichten

Preventie:

• Leeg altijd de cache na het maken van configuratie- of regelwijzigingen
• Controleer store view toewijzingen dubbel bij het aanmaken van regels

Symptomen:

• Cross-links werken op productpagina's en CMS pagina's, maar niet op de Hyva standaard homepage
• Content die gerenderd wordt door .phtml templates krijgt geen cross-links

Oplossing: Dit is verwacht gedrag, geen bug. De module vervangt keywords in content die door Magento's CMS template filter gaat:

• Productbeschrijvingen (gerenderd via Magento\Catalog\Helper\Output)
• Categoriebeschrijvingen (gerenderd via Magento\Catalog\Helper\Output)
• CMS pagina- en block-content (gerenderd via Magento\Cms\Model\Template\Filter)

Content die hardcoded in .phtml templates staat (zoals de Hyva standaard homepage hero-sectie) gaat niet door deze filters en kan niet verwerkt worden.

Workaround:

• Verplaats content van .phtml templates naar CMS blocks of CMS pagina's
• Gebruik CMS block widgets in je layout XML in plaats van hardcoded templates

Symptomen:

• Een keyword wordt vaker vervangen dan verwacht
• Een keyword wordt maar één keer vervangen terwijl je meer verwachtte

Oplossing:

1. Controleer de Max Replacements instelling van de regel — dit beperkt vervangingen per keyword per pagina
2. Controleer de Max Links Per Pagina instelling van het entity type — dit beperkt het totaal aantal links over alle regels
3. Een Max Replacements van 0 betekent ongelimiteerd (tot aan het pagina-niveau maximum)
4. Vergeet niet dat regels met hogere priority het pagina-niveau limiet als eerste verbruiken

Preventie:

• Stel duidelijke max replacements in per regel (1 is aanbevolen voor de meeste gevallen)
• Stel redelijke paginalimieten in (5-10 voor de meeste pagina's)

Symptomen:

• Regel voor "yoga mats" bestaat maar "yoga" wordt in plaats daarvan gelinkt
• Korter keyword krijgt voorrang boven langer, specifieker keyword

Oplossing:

1. Stel een hogere priority in op het langere/specifiekere keyword
2. De module verwerkt regels op priority DESC, daarna keyword-lengte DESC
3. "yoga mats" met priority 10 zal matchen vóór "yoga" met priority 5
4. Bij gelijke priority matchen langere keywords automatisch als eerste

Preventie:

• Geef langere, specifiekere keywords altijd gelijke of hogere priority dan kortere
• Controleer regelprioriteiten bij het toevoegen van nieuwe keywords die overlappen met bestaande

Symptomen:

• Link wordt ingevoegd binnen een attribute waarde
• Paginalayout breekt na het inschakelen van cross-links

Oplossing: De module gebruikt woordgrens-matching en slaat content binnen HTML tags en bestaande <a> tags over. Als je kapotte HTML ziet:

1. Controleer of het keyword in een ongebruikelijke context voorkomt (bijv. binnen inline JavaScript of CSS)
2. Controleer of de content geen misvormde HTML heeft die de parser verwart
3. Schakel de regel tijdelijk uit en controleer of de pagina correct rendert

Preventie:

• Vermijd keywords die vaak in code of attribute waarden voorkomen
• Gebruik meervoudige woordcombinaties in plaats van korte generieke woorden

Symptomen:

• Instellingen gewijzigd maar de pagina toont nog het oude gedrag

Oplossing:

1. Leeg de full page cache: bin/magento cache:flush full_page
2. Leeg de block HTML cache: bin/magento cache:flush block_html
3. Of leeg alle caches: bin/magento cache:flush
4. Forceer een browserverversing (Ctrl+Shift+R / Cmd+Shift+R)

Preventie:

• Leeg altijd de cache na elke configuratiewijziging
• Vergeet niet dat Varnish of CDN caches mogelijk ook geleegd moeten worden

Symptomen:

• Links verschijnen op de standaard store maar niet op een secundaire store view
• Hetzelfde keyword werkt voor de ene store maar wordt genegeerd op een andere

Oplossing:

1. Controleer de Store Views instelling van de regel — deze kan toegewezen zijn aan specifieke stores
2. Controleer of het entity type is ingeschakeld voor de betreffende store view (configuratie is per-store)
3. Controleer of de content het keyword daadwerkelijk bevat op de andere store (vertaalde content matcht niet met Engelstalige keywords)
4. Leeg de cache voor alle store views: bin/magento cache:flush

Preventie:

• Gebruik "All Store Views" voor universele regels (merknamen, productcodes)
• Maak aparte regels per store view voor vertaalde keywords
• Gebruik het CLI preview commando met --store-id om per store te testen:

bin/magento magmodules:crosslinking:preview --entity-type=product --entity-id=42 --store-id=2

Symptomen:

• Cross-links werkten eerder maar zijn gestopt na het updaten van de module
• Geen foutmeldingen in logs

Oplossing:

1. Voer bin/magento setup:upgrade uit om eventuele database-wijzigingen toe te passen
2. Voer bin/magento setup:di:compile uit om dependency injection te regenereren
3. Leeg alle caches: bin/magento cache:flush
4. Controleer de configuratie — nieuwe versies kunnen instellingen toevoegen die geconfigureerd moeten worden (bijv. per-entity-type enable toggles)

Preventie:

• Voer altijd setup:upgrade uit na het updaten van een Magento module
• Controleer de CHANGELOG op breaking changes voordat u update

Navigeer naar: Winkels → Configuratie → Magmodules → Cross-Linking → Debug & Logging

Stel Debug Mode in op Ja en sla op.

Debug logs: var/log/debug.log Error logs: var/log/error.log

Wanneer debug mode is ingeschakeld, logt de module:

• Welke keywords vervangen zijn en hoe vaak
• Op welke store view de vervanging plaatsvond
• Eventuele fouten bij het laden van cross-link regels

Voorbeeld logmelding:

[Replacer] Replaced "yoga" 1 time(s) in store 1

Als je geen logmeldingen ziet wanneer je een pagina bezoekt met matchende keywords, wordt het filter van de module niet getriggerd voor dat contenttype.

Gebruik de ingebouwde self-test via Debug & Logging → Self-Test om te controleren:

• Module ingeschakeld status
• PHP-versie compatibiliteit
• Magento-versie compatibiliteit