Joomla breadcrumbs instellen

2. Breadcrumbs op je site tonen

2.1 Publiceer de Breadcrumbs-module

Breadcrumbs verschijnen pas als je de Breadcrumbs-module publiceert. Om hem toe te voegen ga je naar:

Systeem → Sitemodules → Nieuw → Breadcrumbs

Stel daarna drie dingen in:

• Titel: bijvoorbeeld "Breadcrumbs". Je kunt de titel op de frontend verbergen.
• Positie: kies een templatepositie boven de inhoud, zoals breadcrumbs in het standaard Cassiopeia-template.
• Status: zet deze op Gepubliceerd.

2.2 Kies waar hij verschijnt

Net als elke module heeft de Breadcrumbs-module een tabblad Menutoewijzing. Daar bepaal je waar het spoor verschijnt:

• Op alle pagina's (de gebruikelijke keuze).
• Op alle pagina's behalve de homepage (heel gebruikelijk, want een spoor op de homepage heeft geen zin).
• Alleen op geselecteerde pagina's.

Een nette standaard is "Op alle pagina's" gecombineerd met het verbergen van de Home-kruimel, of "Alle pagina's behalve Home".

2.3 Controleer of de templatepositie bestaat

Als je de module publiceert maar niets ziet, bestaat de gekozen positie misschien niet in je template. Je kunt posities bekijken door Modulepositie voorbeeld in te schakelen bij de Templates opties en daarna ?tp=1 aan een frontend-URL toe te voegen (spoiler: je kunt er alles achter typen behalve 0, ?tp=peter werkt ook!). Het Cassiopeia-template heeft een speciale breadcrumbs-positie voor precies dit doel.

4. Hoe het spoor wordt opgebouwd: het Pathway

4.1 Het Pathway-object

Achter elke frontend-pagina bewaart Joomla een Pathway-object. Dit is een eenvoudige lijst. Elk item heeft twee velden:

naam   -- het zichtbare label van de broodkruimel
  link   -- de interne URL waarnaar de broodkruimel verwijst, bijv. index.php?option=...&Itemid=...
            (leeg voor koppen, scheidingstekens en broodkruimels die zonder link zijn toegevoegd)

De link wordt opgeslagen als een niet-SEF interne URL. De Breadcrumbs-module zet deze om in een SEF-URL wanneer het spoor wordt weergegeven.

De laatste kruimel wordt altijd als platte tekst weergegeven, ongeacht of deze een link bevat. Wanneer de huidige pagina een menu-item is, bevat de bijbehorende kruimel nog steeds een link in de Pathway: alleen de lay-out laat deze weg. Wanneer een component de huidige pagina zelf toevoegt, zoals een artikeltitel, is de link meestal leeg.

De klasse bevindt zich in Joomla\CMS\Pathway\Pathway, en de frontend gebruikt de subklasse Joomla\CMS\Pathway\SitePathway. Je bereikt de actieve instantie vanuit de applicatie:

$pathway = $app->getPathway();

4.2 De menustructuur vult de basis

Wanneer een pagina wordt geladen, kijkt Joomla naar het actieve menu-item. Elk menu-item kent zijn voorouders via een tree-eigenschap: de keten van bovenliggende items, van boven naar beneden tot aan het item zelf. SitePathway doorloopt die boomstructuur en voegt één broodkruimel toe per menu-item daarin, inclusief het actieve item zelf. Elke broodkruimel gebruikt de titel van het menu-item als label.

Een belangrijk detail: als het actieve item de startpagina is, voegt Joomla niets toe. De trail-body blijft leeg en alleen de optionele ‘Home’-broodkruimel uit de module blijft over.

Op andere pagina’s verschijnt het ‘Home’-item normaal gesproken niet in het navigatiepad, omdat het meestal een item op het hoogste niveau is en geen bovenliggend item van andere items. Als u wel menu-items onder het ‘Home’-item plaatst, wordt het ‘Home’-item onderdeel van hun boomstructuur en verschijnt het als een navigatiekruimel. De standaardlay-out verwijdert het dan wanneer het direct volgt op de ‘Home’-navigatiekruimel, zodat het navigatiepad niet ‘Home → Home’ weergeeft.

4.3 Bijzondere menu-itemtypen

Niet elk menu-item wordt een klikbare kruimel. SitePathway behandelt sommige typen anders:

Daarom verschijnt een Kop die als dropdown-ouder wordt gebruikt in het spoor als platte tekst: hij heeft geen echte pagina om naar te linken.

6. Breadcrumbs en de Itemid

6.1 De Itemid bepaalt het startpunt

Elke frontend-pagina is via de parameter Itemid aan een menu-item gekoppeld. De Pathway gebruikt het actieve menu-item als basis, dus de Itemid bepaalt rechtstreeks:

• Welke menu-items als navigatietraject worden weergegeven: het actieve menu-item en de bovenliggende items.
• Waar het componenttraject begint.
• Of het pad leeg blijft. Bij het menu-item ‘Home’ voegt Joomla helemaal geen menukruimels toe. De ‘Home’-kruimel zelf verschijnt nog steeds als de optie Home (showHome) is ingeschakeld, omdat de module deze toevoegt, niet het pad.

6.2 Wat er misgaat zonder een duidelijke Itemid

Als een link naar een artikel geen Itemid heeft, raadt de router van Joomla er een. Een verkeerde gok geeft:

• Een spoor dat in de verkeerde menutak begint.
• Ontbrekende of dubbele kruimels.
• Een ander spoor voor hetzelfde artikel, bereikt vanaf twee plekken.

6.3 Hoe je het inspecteert

Voordat SEF-herschrijving hem verbergt, is de Itemid het laatste getal in de query string:

index.php?option=com_content&view=article&id=42&Itemid=123

Als een breadcrumb-spoor er verkeerd uitziet, controleer dan eerst de Itemid. De oplossing is meestal om naar de inhoud te linken via het juiste menu-item, of om een eigen menu-item voor die pagina te maken.

8. Onder de motorkap (ontwikkelaarsweergave)

8.1 De Pathway-API

Het Pathway biedt een kleine, stabiele API. Je kunt het spoor lezen of wijzigen vanuit een plugin of een eigen component:

use Joomla\CMS\Factory;

$app     = Factory::getApplication();
$pathway = $app->getPathway();

// Lezen
$items = $pathway->getPathway();        // array van objecten met name + link
$names = $pathway->getPathwayNames();    // array met alleen de namen

// Schrijven
$pathway->addItem('Downloads', 'index.php?option=com_downloads&view=list&Itemid=55');
$pathway->setItemName(2, 'Hernoemde kruimel');
$pathway->setPathway($newArrayOfItems); // vervang het hele spoor

Elk item is een eenvoudige stdClass met een name en een link. Een lege link betekent dat de kruimel als tekst wordt weergegeven, niet als hyperlink.

8.2 Waar SitePathway de basis opbouwt

De frontend-subklasse Joomla\CMS\Pathway\SitePathway bouwt het basisspoor op in zijn constructor. Hij leest het actieve menu-item, slaat het home-item over en doorloopt de tree-eigenschap, waarbij hij per itemtype een link kiest (scheidingsteken, kop, url, alias of component). Alles daarna wordt door componenten toegevoegd via addItem().

8.3 Een voorbeeld van een plug-in

Een systeemplug-in kan het navigatiepad aanpassen nadat de component zijn eigen broodkruimels heeft toegevoegd. Gebruik daarvoor de gebeurtenis onAfterDispatch: deze wordt uitgevoerd nadat de component is uitgevoerd en voordat de sjabloon de modules weergeeft. In Joomla 6 schrijft een plug-in zich in voor gebeurtenissen via SubscriberInterface:

use Joomla\CMS\Event\Application\AfterDispatchEvent;
  use Joomla\CMS\Plugin\CMSPlugin;
  use Joomla\Event\SubscriberInterface;

  final class SpecialOffer extends CMSPlugin implements SubscriberInterface
  {
      public static function getSubscribedEvents(): array
      {
          return [‘onAfterDispatch’ => ‘onAfterDispatch’];
      }

      public function onAfterDispatch(AfterDispatchEvent $event): void
      {
          $app = $event->getApplication();

          if (!$app->isClient(‘site’)) {
              return;
          }

          $app->getPathway()->addItem(‘Special Offer’, ‘’);
      }
  }

Let goed op de timing. Bij onAfterRoute is de component nog niet uitgevoerd, dus een crumb die je daar toevoegt, komt vóór de crumbs van de component terecht, midden in het pad. Om een crumb op een specifieke plaats in te voegen, lees je de lijst met getPathway(), wijzig je de array en schrijf je deze terug met setPathway().

Zo voegen extensies van derden hun eigen crumbs in zonder de kernbestanden aan te raken.

8.4 Er is geen breadcrumbs-tabel

Het spoor wordt nooit opgeslagen. Het wordt bij elke aanvraag opnieuw opgebouwd uit de live menustructuur en de huidige inhoud. Breadcrumbs hebben daarom geen eigen databasetabel. In plaats daarvan leunt de module op een handvol kerntabellen. De volgende paragrafen noemen de tabellen die ertoe doen.

8.5 De #__menu-tabel

Dit is de belangrijkste tabel, omdat deze de menustructuur bevat die de basis vormt van elk parcours. De relevante kolommen zijn:

id             -- ID van het menu-item, gebruikt als Itemid
  title          -- de titel van het menu-item, gebruikt als het crumb-label
  parent_id      -- het bovenliggende menu-item
  level          -- diepte in de boomstructuur
  lft, rgt       -- grenzen van het Nested Set Model
  path           -- het aliaspad (ouder/kind/kleinkind)
  alias          -- het URL-segment
  type           -- component | url | alias | separator | heading
  component_id   -- de gekoppelde component
  link           -- de onderliggende query index.php?option=...
  home           -- markeert het standaard (home) menu-item, per taal
  published, access, language
                 -- alleen gepubliceerde items die de bezoeker mag zien, worden gebruikt

Joomla voert niet voor elke crumb een query uit op deze tabel. Bij elk frontend-verzoek laadt het alle gepubliceerde menu-items van de site in één query, gesorteerd op lft. Het slaat die lijst op in de cache wanneer caching is ingeschakeld. Vervolgens bouwt het de boom van elk item (de keten van bovenliggende ID’s tot aan het item zelf) op in PHP, op basis van parent_id.

De kolommen lft en rgt implementeren het Nested Set Model. Sorteren op lft garandeert dat elke bovenliggende het item vóór zijn onderliggende items komt, zodat elk item eenvoudig de boom van zijn bovenliggende item kan kopiëren en zijn eigen id kan toevoegen. Het broodkruimelspoor hoeft vervolgens alleen maar die kant-en-klare boom te doorlopen, en daarom gaat het opbouwen ervan zo snel.

De kolommen lft en rgt implementeren het Nested Set Model. Het bereik van een ouder omvat altijd zijn kinderen, zodat Joomla een hele tak voorouders in een query kan ophalen, zonder recursie. Dat maakt het opbouwen van het spoor uit de menuboom snel.

8.6 De tabellen #__modules en #__modules_menu

De Breadcrumbs-module zelf is een gewone module, dus zijn configuratie staat in #__modules:

De bijbehorende tabel #__modules_menu koppelt elke module aan de menu-items waarop hij verschijnt. Voor breadcrumbs is dit wat je keuze bij Menutoewijzing wegschrijft:

moduleid   -- welke module
menuid     -- welk menu-item (Itemid)
             positief = "toon op dit item"
             negatief = "toon op alle behalve deze items"
             0        = "alle pagina's"

Dus "Alle pagina's behalve Home" wordt hier opgeslagen als een negatieve rij voor het home-menu-item.

8.7 Ondersteunende tabellen

• #__extensions: registreert mod_breadcrumbs als een geïnstalleerde extensie. Bij het laden van modules gebruikt Joomla alleen modules waarvan de extensie hier is ingeschakeld. De instellingen van de module worden hier niet opgeslagen: deze staan in de kolom params van #__modules, en de standaardinstellingen komen uit het XML-bestand van de module.
• #__viewlevels: definieert de toegangsniveaus (Openbaar, Geregistreerd, enzovoort). De kolom access in #__modules verwijst hier naar een niveau. Joomla laadt de Breadcrumbs-module alleen voor bezoekers die dat toegangsniveau hebben.
• #__assets: bevat de ACL-toegangsregels, zoals wie de module in de back-end mag bewerken, verwijderen of de status ervan mag wijzigen. Deze regels bepalen niet wie de module op de frontend ziet.

Geen van deze slaat het navigatiepad zelf op. Samen beschrijven ze de menustructuur, de module en wie deze mag zien, en Joomla bouwt op basis daarvan bij elk verzoek de breadcrumbs opnieuw op.

10. Template-overrides en styling

10.1 De standaardopmaak

De standaardlay-out van Joomla 6 genereert semantische, toegankelijke opmaak op basis van Bootstrap-klassen. Met de standaardinstellingen (“U bent hier” ingeschakeld, Startpagina ingeschakeld, Laatste ingeschakeld) ziet een kort navigatiepad er als volgt uit:

<nav class="mod-breadcrumbs__wrapper" aria-label=“Breadcrumbs”>
    <ol class="mod-breadcrumbs breadcrumb px-3 py-2">
      <li class="mod-breadcrumbs__here float-start">
        U bent hier: &#160;
      </li>
      <li class="mod-breadcrumbs__item breadcrumb-item">
        <a href="/" class="pathway"><span>Home</span></a>
      </li>
      <li class="mod-breadcrumbs__item breadcrumb-item active">
        <span>Huidige pagina</span>
      </li>
    </ol>
  </nav>

Wanneer “U bent hier” is uitgeschakeld, krijgt de eerste <li> in plaats daarvan de klasse mod-breadcrumbs__divider en bevat deze een locatiepictogram in plaats van de tekst.

De <nav>-wrapper met een aria-label geeft aan schermlezers door dat dit een navigatie-oriëntatiepunt is. De aria-label is de moduletitel, dus “Breadcrumbs” hierboven is gewoon de titel van deze voorbeeldmodule. Geef de module een duidelijke titel, zelfs als je deze op de frontend verbergt.

Het laatste navigatie-element krijgt de active-klasse. Als je een nog duidelijker signaal voor toegankelijkheid wilt, kun je via een override aria-current=“page” aan het laatste navigatie-element toevoegen.

10.2 Een override maken

Bewerk om de markup te wijzigen nooit de module. Maak in plaats daarvan een template override. Voor het Cassiopeia-template:

templates/cassiopeia/html/mod_breadcrumbs/default.php

Kopieer het origineel modules/mod_breadcrumbs/tmpl/default.php naar dat pad en bewerk daarna je kopie. Joomla laadt de override automatisch. De Templates-beheerder heeft een ingebouwde editor die deze override voor je maakt:

Systeem → Sitetemplates → [jouw template] → Overrides maken → mod_breadcrumbs

10.3 Opmaak zonder override

Voor eenvoudige visuele aanpassingen heb je helemaal geen override nodig. De standaardlay-out genereert al zijn eigen klassen, dus je kunt deze rechtstreeks in de CSS van je sjabloon aanpassen. In Cassiopeia plaats je je regels in user.css. Je kunt dat bestand aanmaken in de sjabloonbeheerder, waarna Cassiopeia het automatisch laadt.

.mod-breadcrumbs { font-size: 0.9rem; }
  .mod-breadcrumbs__item.active span { color: #666; }
  .mod-breadcrumbs { --breadcrumb-divider: “→”; }

Cassiopeia tekent de scheidingslijn tussen de breadcrumbs op basis van de CSS-variabele --breadcrumb-divider, met / als standaardwaarde. Het instellen van de variabele is voldoende: je hoeft de ::before regel niet te overschrijven.

Je hebt hiervoor het Module Class Suffix niet nodig. De lay-out geeft het niet weer, en in de breadcrumbs-positie van Cassiopeia heeft de module geen wrapper, dus het achtervoegsel verschijnt nooit. Gebruik het alleen wanneer je een andere opmaak nodig hebt voor een tweede Breadcrumbs-module, en kies dan ook een module-stijl zoals html5 op het tabblad ‘Geavanceerd’ van de module, zodat het achtervoegsel op een wrapper-element wordt weergegeven.

12. Meertalige breadcrumbs

12.1 De ‘Home’-breadcrumb per taal

Op een meertalige site heeft elke taal zijn eigen standaard (home) menu-item. De Breadcrumbs-module vraagt om het standaarditem van de huidige taal:

$home = $menu->getDefault($app->getLanguage()->getTag());

Een Nederlandse pagina koppelt de Home-breadcrumb dus aan de Nederlandse startpagina, en een Engelse pagina aan de Engelse startpagina. Dit werkt alleen als elke actieve taal een eigen standaardmenu-item heeft. Als een taal er geen heeft, valt Joomla terug op het Home-item voor Alle talen, en de ‘Home’-crumb verwijst dan naar de verkeerde startpagina.

In de lijst met menu-items kun je het startpagina-item van een taal herkennen aan de taalvlag in de kolom ‘Home’ (of een taalcodebadge als er geen vlag is ingesteld). Het startpagina-item voor Alle talen toont een huisje-icoontje.

12.2 Dubbele Home-items voorkomen

Op meertalige sites kan het home-menu-item twee keer verschijnen: een keer uit de Home-kruimel en een keer uit de menustructuur. De standaardlayout detecteert dit en verwijdert het dubbele tweede item, zodat het spoor netjes blijft.

12.3 Vertaalde labels

Elke kruimelpadnaam is afgeleid van de titel van het menu-item, de categorie of het artikel dat de bezoeker op dat moment bekijkt. Op een meertalige site heeft elke taal zijn eigen menu-items en inhoud, elk met een eigen titel. Een Nederlandse pagina stelt zijn navigatiepad dus samen op basis van Nederlandse titels, en een Engelse pagina op basis van Engelse titels. Hiervoor zijn geen koppelingen nodig: die koppelen vertalingen aan elkaar, bijvoorbeeld voor de taalkeuzeschakelaar, maar ze veranderen het navigatiepad niet.

De vaste woorden komen uit het taalbestand van de module: „Home“ (MOD_BREADCRUMBS_HOME) en „Je bent hier:“ (MOD_BREADCRUMBS_HERE). Joomla vertaalt deze automatisch voor elke geïnstalleerde taal. Als je de optie homeText invult, vervangt die tekst “Home” in elke taal. Maak in dat geval per taal een aparte Breadcrumbs-module aan, elk met een eigen homeText, en stel het veld “Taal” van elke module in. De eenvoudigste optie is om homeText leeg te laten en het aan de taalbestanden over te laten, of de bewoording te wijzigen met een taaloverride.

14. Veelvoorkomende fouten en valkuilen

14.1 Er verschijnen geen breadcrumbs

Symptoom: er is nergens op de site een spoor.

Oplossing: publiceer de Breadcrumbs-module, zet hem op een echte templatepositie (zoals breadcrumbs in Cassiopeia) en wijs hem toe aan de juiste pagina's.

14.2 Het spoor begint in de verkeerde tak

Symptoom: een artikel toont Home → Verkeerde sectie → Artikel.

Oplossing: de verkeerde Itemid is actief. Link naar de inhoud via het juiste menu-item, of geef de pagina een eigen menu-item. Controleer ook de categorieboom, want artikelkruimels volgen de bovenliggende categorieën.

14.3 Dubbele Home op meertalige sites

Symptoom: het spoor toont Home → Home → ....

Oplossing: dit gebeurt wanneer het home-item zowel in de Home-kruimel als in de menustructuur voorkomt. Modern Joomla verwijdert het dubbele item automatisch; gebruik je een eigen override, zorg dan dat die de ontdubbel-logica uit de standaardlayout behoudt.

14.4 Een kop-kruimel heeft geen link

Symptoom: een tussenliggende kruimel is platte tekst, geen link.

Oplossing: dit is correct gedrag. Menu-items van het type Kop of Scheidingsteken hebben geen pagina, dus Joomla geeft ze als tekst weer. Heb je daar een link nodig, gebruik dan een echt menu-itemtype.

14.5 De laatste kruimel herhaalt de paginatitel

Symptoom: het spoor eindigt met dezelfde tekst als de paginakop, wat overbodig aanvoelt.

Oplossing: zet de optie Laatste (showLast) uit om het spoor bij de bovenliggende pagina te laten eindigen.

14.6 De module bewerkt in plaats van een override

Symptoom: aangepaste breadcrumb-markup verdwijnt na een Joomla-update.

Oplossing: bewerk nooit bestanden in modules/mod_breadcrumbs/. Zet je wijzigingen in een template-override op templates/[template]/html/mod_breadcrumbs/default.php.

16. In het kort

BREADCRUMBS WEERGEVEN      mod_breadcrumbs publiceren in een sjabloonpositie
VERBERGEN OP STARTPAGINA   Menutoewijzing → Alle pagina’s behalve Startpagina
“U BEVINDT ZICH HIER”      Optie showHere (uit = locatieconfict)
BREADCRUMB STARTPAGINA     Optie showHome (homeText overschrijft het woord)
LAATSTE BROODKRUMBEL       Optie showLast (uit = eindigt bij bovenliggende)
GEGEVENSBRON               $app->getPathway() (Pathway-object, geen tabel)
BASIS VAN HET PAD          Actief menu-item + de bovenliggende items (de tree-eigenschap)
EXTRA BROODKRUMBELS        Componenten roepen $pathway->addItem(name, link) aan
EEN CRUMB TOEVOEGEN (PHP)  $app->getPathway()->addItem(‘Label’, ‘index.php?...’)
PLUGIN-GEBEURTENIS         onAfterDispatch (na de crumbs van de component)
PIPELINE                   Router → Menu-item → Pathway → Component → Module → Lay-out
DB-TABELEN                 #__menu (boom), #__modules, #__modules_menu, #__viewlevels
MARKUP OVERSCHRIJVEN       templates/[tpl]/html/mod_breadcrumbs/default.php
GESTRUCTUREERDE GEGEVENS   schema.org BreadcrumbList JSON-LD, automatisch 
                           (Home en laatste crumb inbegrepen, zelfs wanneer verborgen)
CACHING                    Standaard: geen caching; houd dit uitgeschakeld 
                           (modus itemid: één gecachete breadcrumb per menu-item, niet per URL)
VEROUDERDE API             BreadcrumbsHelper::getList()/getHome() (gebruik getBreadcrumbs()/getHomeItem())