Joomla template overrides: pas output aan zonder core hacks

1. De basis

1.1 Wat is een template override?

Wanneer Joomla een pagina rendert, komt elk stuk uitvoer uit een klein PHP-bestand: een artikel uit de artikel-layout van com_content, een menu uit de layout van mod_menu, een paginering uit een gedeeld layout-bestand. Een template override is een kopie van zo'n bestand in de map html/ van je template. Bestaat de kopie, dan gebruikt Joomla die en negeert het origineel. Zo niet, dan draait het origineel.

components/com_content/tmpl/article/default.php     het origineel (core)
templates/cassiopeia/html/com_content/article/default.php   jouw override

Dat is het hele mechanisme. Geen configuratie, geen registratie, geen databaseregel - het bestaan van het bestand is de override.

1.2 Waarom overrides bestaan

• Updates blijven veilig: core-bestanden worden bij elke Joomla-update vervangen; je map html/ wordt niet aangeraakt.
• Elke markup wordt van jou: je bepaalt elke class, tag en elk attribuut zonder iets te hacken.
• Ze zijn eerlijk: wie de site doorlicht, vindt alle aanpassingen op een voorspelbare plek.

1.3 Wat je kunt overriden

Cassiopeia levert zelf overrides mee - kijk in templates/cassiopeia/html/ en je vindt mod_menu-layouts (de metismenu-dropdowns), een banner-layout voor mod_custom, en twee chromes (card.php, noCard.php). Het core-template gebruikt hetzelfde mechanisme dat jij gaat gebruiken.

Het mechanisme dekt ook extensies van derden: een goed gebouwde shop-, blog- of evenementencomponent override je als html/com_huncomponent/... en hun modules als html/mod_hunmodule/, precies zoals de core. Of een extensie netjes te overriden is, is een nuttige kwaliteitstest voordat je haar in gebruik neemt.

Een ding dat op een override-onderwerp lijkt maar het niet is: systeem-e-mails. Registratiemails, wachtwoordresets en andere meldingen pas je aan via de component Mail-templates in de backend - zie het Focus On-artikel over mail-templates - niet via bestanden in html/.

3. Hoe Joomla het juiste bestand vindt

3.1 De zoekvolgorde

Voor elke view en module loopt Joomla een kort lijstje locaties af en gebruikt het eerste bestand dat het vindt:

1. templates/{child}/html/...      het actieve child template (indien aanwezig)
2. templates/{parent}/html/...     het parent template
3. {extensie}/tmpl/...             de eigen layout van de extensie (de standaard)

Deze volgorde verklaart twee belangrijke gedragingen: een child template kan de overrides van zijn parent overriden, en de eigen layout van een extensie is simpelweg het laatste redmiddel. De actieve template-stijl bepaalt welk template (en dus welke set overrides) in gebruik is - een site kan zelfs verschillende templates op verschillende menu-items gebruiken.

3.2 Naamgeving is alles

Overrides worden puur op pad en bestandsnaam gematcht. html/com_content/article/default.php werkt; html/com_content/Article/default.php of html/content/article/default.php doet stilletjes niets. Als een override "niet werkt", is in negen van de tien gevallen de naam of de map fout.

3.3 Sublayouts: de bestanden met underscore

Kijk in components/com_content/tmpl/article/ en je vindt default.php plus default_links.php. De underscore-bestanden zijn sublayouts, geladen vanuit het hoofdbestand met $this->loadTemplate('links'). Je overridet ze precies zoals het hoofdbestand - en ze laten je een fragment van een view overriden in plaats van het geheel. Zit jouw wijziging in een sublayout, kopieer dan alleen dat bestand en laat default.php met rust: een bestand minder te onderhouden.

5. Layout-overrides (JLayout)

5.1 De gedeelde layouts

Naast componenten en modules heeft Joomla een bibliotheek van gedeelde layouts in de map layouts/ in de root: paginering, weergave van aangepaste velden, formulieronderdelen, knoppen, iconen. Core-code rendert ze via de klasse LayoutHelper:

use Joomla\CMS\Layout\LayoutHelper;

echo LayoutHelper::render('joomla.content.info_block.author', ['item' => $this->item]);

5.2 Een gedeelde layout overriden

De puntnotatie vertaalt naar een pad, en de override spiegelt het onder html/layouts/:

layouts/joomla/content/info_block/author.php                    origineel
templates/{template}/html/layouts/joomla/content/info_block/author.php   override

Layout-overrides zijn krachtig omdat gedeelde layouts overal opduiken: override de layout voor aangepaste velden een keer (layouts/joomla/content/fields.php en verwanten) en elke component die velden rendert, pikt hem op. Diezelfde reikwijdte vraagt extra zorg - test meer dan een paginatype na het wijzigen van een gedeelde layout.

5.3 Het juiste niveau kiezen

Dezelfde visuele wijziging kan vaak in een component-override, een module-override of een layout-override. Vuistregel: override op het smalste niveau dat je doel dekt. Een artikel-view? Component-override. Een module-instantie? Een layout met eigen naam. Een patroon dat over de hele site terugkeert (paginering, velduitvoer)? Daar zijn layout-overrides voor.

7. Overrides in child templates

7.1 Waarom overrides in een child horen

Sinds Joomla 4.1 kunnen templates child templates hebben, en Cassiopeia ondersteunt ze standaard. De parent levert de machinerie; het child bevat jouw wijzigingen: stijlinstellingen, eigen CSS en overrides. Wordt het parent template bijgewerkt, dan overleeft je child - en elke override erin - onaangeraakt. Bouw je vandaag op Cassiopeia, zet je overrides dan in een child, niet in Cassiopeia zelf.

7.2 Hoe de zoekvolgorde met children omgaat

Zoals sectie 3 liet zien, wordt de map html/ van het child voor die van de parent bekeken. De praktische gevolgen:

• Een child-override wint van dezelfde override in de parent.
• Het child heeft alleen de bestanden nodig die jij wijzigt; al het andere valt terug op de parent en daarna op de core.
• Een bestaande site naar een child template verhuizen is vooral de map html/ en de eigen CSS verplaatsen.

7.3 Assets wonen in media/

Sinds Joomla 4.1 staan template-assets (CSS, JS, afbeeldingen) onder media/templates/site/{template}/ in plaats van in de templatemap zelf. Overrides die assets laden, gebruiken het beste de Web Asset Manager of HTMLHelper::_('stylesheet', ...) met relatieve paden, zodat de child/parent-terugval ook voor de assets zelf werkt.

9. Updates overleven: override-onderhoud

9.1 De kosten waar niemand het over heeft

Een override is een momentopname van een core-bestand. Wanneer een Joomla-update het origineel verbetert - een bugfix, een toegankelijkheidsverbetering, een beveiligingsrelevante escape-aanroep - blijft jouw override de oude code draaien. Overrides breken niet bij updates; ze lopen stilletjes achter, en dat is erger, want niets ziet er kapot uit.

9.2 Joomla houdt dit voor je bij

Weinig mensen weten dat Joomla precies dit registreert. Na een update markeert de tabel #__template_overrides de override-bestanden waarvan het origineel veranderde, en het templatebeheer toont ze als bijgewerkte bestanden ("Updated files to check") met de datum van de wijziging. De werkwijze:

1. Open na elke core-update Systeem → Site-templates → je template.
2. Bekijk de lijst bijgewerkte bestanden.
3. Vergelijk per bestand jouw override met het nieuwe origineel (een diff-tool maakt dit snel) en neem de relevante wijzigingen over in je override.
4. Markeer de regel als gecontroleerd (Mark Checked), zodat de lijst betekenisvol blijft.

9.3 Maak toekomstige diffs makkelijk

• Houd overrides minimaal: hoe minder regels afwijken van het origineel, hoe sneller elke diff.
• Zet commentaar bij je wijzigingen (// gewijzigd: auteursregel verplaatst), zodat toekomstige-jij weet wat behouden moet blijven.
• Houd de site - of minstens de templatemap - in versiebeheer. git diff na een update beantwoordt de meeste vragen meteen.
• Verwijder overrides die je niet meer nodig hebt. Het beste onderhoud gaat over bestanden die niet bestaan.

11. Overrides en de Web Services API

Overrides zijn presentatie, en de Web Services API slaat presentatie volledig over: een API-verzoek om een artikel geeft ruwe data uit het model terug, dus geen component-override, chrome of layout-override beinvloedt de API-uitvoer. Heeft een headless frontend andere "markup" nodig, dan woont die markup in de afnemende applicatie, niet in Joomla-overrides.

De API raakt templates op een punt: template-stijlen zijn via REST te beheren (v1/templates/styles/site en v1/templates/styles/administrator), dus provisioning-tools kunnen de actieve stijl van een site omschakelen - en daarmee welke override-set van welk template in gebruik is. De override-bestanden zelf zijn bestandssysteem-artefacten: zet ze uit met je normale deploymentproces (git, rsync), niet via een API.

13. Veelvoorkomende fouten en valkuilen

13.1 Het core-bestand zelf bewerken

Symptoom: een aanpassing verdween na de laatste Joomla-update.

Oplossing: de wijziging is gemaakt in het eigen tmpl-bestand van de extensie. Doe hem opnieuw als override in de map html/ van het template, waar updates niet bij kunnen - dat is het hele punt van het mechanisme.

13.2 De override die niets doet

Symptoom: het override-bestand bestaat, maar de pagina negeert het.

Oplossing: controleer, in volgorde: de exacte map- en bestandsnaam (sectie 3.2), of de actieve template-stijl het template is dat je bewerkte (op dit menu-item kan een andere stijl staan), of een override in het child template wint, en leeg als laatste de cache.

13.3 Alles overriden "nu je toch bezig bent"

Symptoom: de lijst bijgewerkte bestanden toont na een core-update veertig regels; niemand durft er nog aan te komen.

Oplossing: verwijder elke override die identiek is aan het origineel (een diff laat dat in seconden zien). Houd alleen echte wijzigingen, en kies sublayout- en layout-overrides boven kopieen van complete views.

13.4 Achtergebleven overrides na updates

Symptoom: een bug of toegankelijkheidsprobleem dat Joomla maanden geleden oploste, staat nog steeds op jouw site.

Oplossing: je override bevat nog de oude code. Neem de werkwijze van sectie 9 over: bekijk na elke update de bijgewerkte bestanden en neem wijzigingen over in je overrides. Bij fixes met beveiligingsimpact is dit urgent, geen cosmetica.

13.5 Businesslogica in de override

Symptoom: een override draait databasequery's of roept modellen aan, en de site wordt traag of breekt wanneer een extensie updatet.

Oplossing: verplaats de logica naar waar ze hoort - een plugin, een module of het model - en laat de override alleen de data opmaken die de view al heeft.

13.6 Verloren escaping

Symptoom: na het herstijlen van een override rendert door gebruikers aangeleverde content als rauwe HTML.

Oplossing: herstel de $this->escape()- / htmlspecialchars()-aanroepen uit het originele bestand. Stijlwijzigingen mogen nooit uitvoer-escaping verwijderen.

15. In het kort

PADEN        component  html/com_content/article/default.php
             module     html/mod_menu/default.php
             layout     html/layouts/joomla/content/info_block/author.php
             chrome     html/layouts/chromes/mijnchrome.php

ZOEKEN       child html/ > parent html/ > extensie tmpl/
             gematcht op exact pad + bestandsnaam, eerste hit wint

AANMAKEN     Systeem > Site-templates > template > Overrides aanmaken
             handmatig: cp van tmpl/ naar gespiegeld pad in html/

SUBLAYOUT    default_links.php  = loadTemplate('links')
             override fragmenten, geen complete views

ALTERNATIEF  kopie met nieuwe naam (mycard.php) = kiesbare layout
             + mycard.xml met metadata = menu-itemtype

CHROME       core: none, html5, outline, table
             cassiopeia: card, noCard
             eigen chrome-bestand = nieuwe "Modulestijl"-optie

ONDERHOUD    na elke update: template > bijgewerkte bestanden
             (#__template_overrides volgt gewijzigde originelen)
             diff override vs nieuw origineel > overnemen > Mark Checked

REGELS       alleen weergavecode - geen query's, geen modellen
             $this->escape() intact houden
             cache legen voor je aan het pad twijfelt

API          overrides raken API-uitvoer niet (ruwe data)
             v1/templates/styles/site beheert alleen de actieve stijl

DEV          tmpl/ + default.xml + sublayouts + LayoutHelper
             = je extensie is volledig overridebaar