Documentatie · Integratiehandleiding

Handleiding voor Template Overrides

Dit document legt uit hoe u de PHP-templates die door de ADP Car Market Hub-plugin worden gebruikt, veilig kunt aanpassen door override-bestanden in uw thema te maken, en hoe u deze overrides onderhoudbaar houdt bij plugin-updates.

Wanneer u dit document moet gebruiken

Gebruik dit document als u:

Een ontwikkelaar bent die de HTML-structuur van het voertuigarchief, de detailpagina van een enkel voertuig of de vergelijkingspagina wil wijzigen buiten wat de Design-instellingen en Custom CSS toestaan.
Een aangepast thema onderhoudt en voertuigpagina's naadloos wilt integreren in de eigen HTML-structuur van het thema.
Een site controleert na een plugin-update om te zien of bestaande overrides nog compatibel zijn.

Deze handleiding is bedoeld voor PHP-ontwikkelaars die bekend zijn met de ontwikkeling van WordPress-thema's. Als u alleen kleuren, lettertypen of marges wilt wijzigen, gebruik dan Car Market Hub → Design of het Custom CSS-veld — er is dan geen template override nodig. Zie de Custom CSS-handleiding.

Overzicht

De plugin biedt fallback PHP-templates voor voertuigpagina's in de map templates/. WordPress zoekt templates in een specifieke volgorde: bestanden in het actieve thema worden gecontroleerd vóór de bestanden van de plugin. De plugin maakt bewust gebruik van dit mechanisme via locate_template():

WordPress controleert de map van het actieve thema op een bestand met dezelfde naam.
Indien gevonden, wordt dat themabestand gebruikt.
Indien niet gevonden, wordt de eigen template van de plugin als fallback gebruikt.

Dit betekent dat u elke front-end template van de plugin kunt overschrijven door een bestand met dezelfde naam in de hoofdmap van uw thema te plaatsen. Het plugin-bestand wordt nooit gewijzigd en is tijdens updates veilig voor uw aanpassingen. Uw override-bestand blijft in het thema staan, dat onder uw eigen versiebeheer valt.

Templates die beschikbaar zijn voor overrides

De volgende templatebestanden worden via locate_template() geladen en kunnen worden overschreven:

Bestandsnaam template	Doel	Locatie in plugin
`single-as24ci_car.php`	Detailpagina van een enkel voertuig. Laadt de actieve lay-out (momenteel altijd `single-as24ci_car-classic.php`).	`templates/single-as24ci_car.php`
`archive-as24ci_car.php`	Voertuigarchief en overzichtspagina. Wordt ook gebruikt wanneer de shortcode `[as24ci_archive]` in template-modus wordt gerenderd.	`templates/archive-as24ci_car.php`

De vergelijkingspagina (page-as24ci_compare.php) en het zoekfilter-gedeelte (parts/search-filter.php) worden rechtstreeks door de plugin geladen en worden niet via locate_template() verwerkt. Ze kunnen niet met deze methode worden overschreven. Controleer dit gedrag in de huidige plugin-versie voordat u hierop vertrouwt.

Vereisten

Toegang tot de bestanden van het actieve thema (via FTP, SSH of de WordPress-bestandseditor).
Een child-theme wordt ten zeerste aanbevolen als u een commercieel of parent-theme gebruikt. Als u override-bestanden in een parent-theme plaatst, gaan deze verloren wanneer het parent-theme wordt bijgewerkt.
Bekendheid met PHP en WordPress template tags (get_header(), get_footer(), the_title() en dergelijke).

Stapsgewijze instructies

Een template override maken

Zoek het bronbestand. Zoek de template die u wilt aanpassen in de plugin-map, onder wp-content/plugins/adp-car-market-hub/templates/. Bijvoorbeeld archive-as24ci_car.php.
Kopieer het bestand — verplaats het niet. Kopieer het bestand naar de hoofdmap van uw (child-)thema. De bestandsnaam moet identiek zijn: - Voor het archief: wp-content/themes/your-theme/archive-as24ci_car.php - Voor de detailpagina: wp-content/themes/your-theme/single-as24ci_car.php
Breng uw wijzigingen aan in de themakopie. Bewerk de kopie in uw thema. Het originele bestand van de plugin blijft onaangeroerd.
Test op de front-end. Bezoek een voertuigarchief of de detailpagina van een voertuig en controleer of uw wijzigingen zijn toegepast.

Controleren welke template actief is

De WordPress Sitegezondheid-pagina en query monitor-plugins (bijvoorbeeld Query Monitor) kunnen tonen welk templatebestand voor een specifiek verzoek wordt gebruikt. U kunt ook tijdelijk een commentaarregel bovenaan uw override-bestand toevoegen en de broncode van de pagina bekijken om te controleren of het bestand wordt geladen.

Compatibel blijven na plugin-updates

Wanneer de plugin wordt bijgewerkt, kunnen de meegeleverde templates in templates/ veranderen. Uw override-bestand blijft in het thema staan en wordt nog steeds gebruikt — maar als de template-logica van de plugin is gewijzigd, kan uw override verouderd zijn.

Na elke plugin-update:

Vergelijk uw override-bestand met het bijbehorende bestand in de bijgewerkte plugin-map. Een diff-tool of code-editor met bestandsvergelijking kan hierbij helpen.
Voeg eventuele relevante wijzigingen uit de nieuwe versie van de plugin samen in uw override.
Test de voertuigpagina's op de front-end na het samenvoegen.

Door overrides minimaal te houden — en alleen de secties te bevatten die u daadwerkelijk moet wijzigen — vermindert u het werk dat nodig is bij het samenvoegen van updates.

Configuratiereferentie

Er is geen instellingenveld in de plugin dat template overrides rechtstreeks regelt. De logica voor het laden is onderdeel van het WordPress-hooksysteem en kan niet worden gewijzigd vanuit het plugin-beheer.

De Design-instellingen in Car Market Hub → Design blijven van toepassing, zelfs wanneer een template override wordt gebruikt, omdat de dynamische CSS via wp_head wordt uitgevoerd, ongeacht welk templatebestand wordt geladen.

Operationele opmerkingen

Vereiste voor child-theme. Als u een commercieel of parent-theme gebruikt, maak dan altijd een child-theme aan voordat u override-bestanden toevoegt. Bestanden die rechtstreeks aan een parent-theme worden toegevoegd, worden verwijderd wanneer het thema wordt bijgewerkt.
De override moet get_header() en get_footer() aanroepen. De eigen templates van de plugin roepen beide aan. Als uw override deze weglaat, wordt de pagina geladen zonder de navigatie en footer van het thema. Dit is bijna nooit de bedoeling.
Behoud de plugin-namespace. De templatebestanden van de plugin declareren namespace AS24CI; en verwijzen naar interne constanten zoals CPT::POST_TYPE and Options::DESIGN_SINGLE_LAYOUT. Als uw override een van deze gebruikt, behoud dan de namespace-declaratie of gebruik de volledige class-namen.
Shortcode render-modus. De archieftemplate ondersteunt twee render-modi die worden aangestuurd door de globale variabele $as24ci_render_mode: 'template' (wanneer geladen als een CPT-archiefpagina) en 'shortcode' (wanneer ingevoegd via de shortcode [as24ci_archive]). De template laat get_header() en get_footer() weg in de shortcode-modus. Uw override moet dit gedrag overnemen als u wilt dat de shortcode correct werkt naast de archieftemplate.
Stabiliteit van CSS-classes. De CSS van de plugin is afhankelijk van class-namen in de template-HTML (bijvoorbeeld .as24ci-page, .as24ci-page-classic, .as24ci-archive-list, .as24ci-archive-row). Als u deze classes in uw override verwijdert of hernoemt, zullen de stylesheet en Design-instellingen van de plugin niet meer werken voor die elementen. Wijzig class-namen alleen als u ook de bijbehorende CSS in het Custom CSS-veld of in de stylesheet van uw thema bijwerkt.
alignfull class. De plugin voegt de class alignfull toe aan de wrapper .as24ci-page, zodat blokthema's deze uitrekken tot de volledige breedte. Als u deze class in uw override verwijdert, zal het gedrag voor volledige breedte in blokthema's niet werken.
Vereisten voor PHP-versie en WordPress-versie. De templates van de plugin maken gebruik van PHP-functies die consistent zijn met de gestelde vereisten van de plugin. Zie PHP- en databasevereisten.

Probleemoplossing

Symptoom	Waarschijnlijke oorzaak	Wat te controleren
Override-bestand wordt niet gebruikt.	Het bestand staat in de verkeerde map, heeft een typfout in de bestandsnaam of bevindt zich in de hoofdmap van het parent-theme in plaats van het child-theme.	Controleer de exacte bestandsnaam en locatie. Gebruik Query Monitor of controleer de broncode van de pagina op een tijdelijke commentaarregel in het override-bestand.
Voertuigpagina's tonen een lege pagina of PHP-fout na het maken van de override.	Het override-bestand bevat een PHP-syntaxfout of mist een vereiste include.	Controleer het PHP-foutlogboek van de server. Controleer of het override-bestand de PHP-tags correct opent en sluit.
Plugin-CSS wordt niet toegepast op de overschreven template.	De wrapper-class `.as24ci-page` of `.as24ci-page-classic` ontbreekt in de output van de override.	Zorg ervoor dat de buitenste wrapper `<div class="as24ci-page as24ci-page-classic …">` aanwezig is in de override.
Design-instellingen (kleuren, typografie) hebben geen effect.	De dynamische CSS-output is afhankelijk van de wrapper-classes van de plugin. Als deze ontbreken, komen de specifieke CSS-regels niet overeen.	Herstel de wrapper-classes zoals hierboven beschreven.
De shortcode `[as24ci_archive]` toont geen header of footer van het thema wanneer de archief-override ook actief is.	De override roept altijd `get_header()` en `get_footer()` aan, ongeacht `$as24ci_render_mode`.	Voeg een controle toe voor `$as24ci_render_mode === 'template'` voordat u `get_header()` en `get_footer()` aanroept, analoog aan de eigen template-logica van de plugin.