Documentation · Guide d'intégration

Guide de surcharge des modèles

Ce document explique comment personnaliser en toute sécurité les modèles PHP utilisés par l'extension ADP Car Market Hub en créant des fichiers de surcharge dans votre thème, et comment maintenir ces surcharges lors des mises à jour de l'extension.

Quand utiliser ce document

Utilisez ce document si vous êtes :

Un développeur qui doit modifier la structure HTML de l'archive des véhicules, de la page de détails d'un véhicule ou de la page de comparaison au-delà de ce que permettent les réglages de Design et le CSS personnalisé.
En train de maintenir un thème personnalisé et souhaitez intégrer les pages de véhicules de manière transparente dans la structure HTML de votre propre thème.
En train de réviser un site après une mise à jour de l'extension pour vérifier si les surcharges existantes sont toujours compatibles.

Ce guide est destiné aux développeurs PHP à l'aise avec le développement de thèmes WordPress. Si vous avez uniquement besoin de modifier les couleurs, les polices ou les espacements, utilisez plutôt Car Market Hub → Design ou le champ CSS personnalisé — aucune surcharge de modèle n'est nécessaire. Voir le Guide du CSS personnalisé.

Aperçu

L'extension fournit des modèles PHP de secours pour les pages de véhicules dans son répertoire templates/. WordPress localise les modèles dans un ordre spécifique : les fichiers du thème actif sont vérifiés avant les fichiers de l'extension. L'extension utilise ce mécanisme intentionnellement via locate_template() :

WordPress vérifie le répertoire du thème actif pour y trouver un fichier portant le même nom.
S'il est trouvé, ce fichier de thème est utilisé.
S'il n'est pas trouvé, le propre modèle de l'extension est utilisé en dernier recours.

Cela signifie que vous pouvez surcharger n'importe quel modèle frontal de l'extension en plaçant un fichier du même nom dans le répertoire racine de votre thème. Le fichier de l'extension n'est jamais modifié et reste à l'abri de vos personnalisations lors des mises à jour. Votre fichier de surcharge reste dans le thème, qui est sous votre propre contrôle de version.

Modèles disponibles pour la surcharge

Les fichiers de modèles suivants sont résolus via locate_template() et peuvent être surchargés :

Nom du fichier de modèle	Objectif	Emplacement dans l'extension
`single-as24ci_car.php`	Page de détails d'un véhicule unique. Charge la mise en page active (actuellement toujours `single-as24ci_car-classic.php`).	`templates/single-as24ci_car.php`
`archive-as24ci_car.php`	Page d'archive et de listes de véhicules. Également utilisé lorsque le code court `[as24ci_archive]` est rendu en mode modèle.	`templates/archive-as24ci_car.php`

La page de comparaison (page-as24ci_compare.php) et le modèle partiel du filtre de recherche (parts/search-filter.php) sont chargés directement par l'extension et ne sont pas résolus via locate_template(). Ils ne peuvent pas être surchargés à l'aide de cette méthode. Vérifiez ce comportement dans la version actuelle de l'extension avant de vous y fier.

Prérequis

Accès aux fichiers du thème actif (via FTP, SSH ou l'éditeur de fichiers WordPress).
Un thème enfant est fortement recommandé si vous utilisez un thème commercial ou un thème parent. Placer des fichiers de surcharge dans un thème parent signifie qu'ils seront perdus lors de la mise à jour de ce dernier.
Familiarité avec PHP et les balises de modèle WordPress (get_header(), get_footer(), the_title(), et similaires).

Instructions étape par étape

Créer une surcharge de modèle

Localisez le fichier source. Trouvez le modèle que vous souhaitez personnaliser dans le répertoire de l'extension, sous wp-content/plugins/adp-car-market-hub/templates/. Par exemple, archive-as24ci_car.php.
Copiez — ne déplacez pas — le fichier. Copiez le fichier dans le répertoire racine de votre thème (enfant). Le nom du fichier doit être identique : - Pour l'archive : wp-content/themes/your-theme/archive-as24ci_car.php - Pour le véhicule unique : wp-content/themes/your-theme/single-as24ci_car.php
Effectuez vos modifications dans la copie du thème. Modifiez la copie dans votre thème. Le fichier d'origine de l'extension reste intact.
Testez sur le site. Visitez une archive de véhicules ou une page de détails de véhicule et confirmez que vos modifications sont appliquées.

Vérifier quel modèle est actif

La page Santé du site de WordPress et les extensions de surveillance des requêtes (par exemple Query Monitor) peuvent afficher quel fichier de modèle est utilisé pour chaque requête. Alternativement, ajoutez un commentaire temporaire en haut de votre fichier de surcharge et vérifiez le code source de la page pour confirmer que le fichier est bien chargé.

Rester compatible après les mises à jour de l'extension

Lorsque l'extension est mise à jour, les modèles inclus dans templates/ peuvent changer. Votre fichier de surcharge reste dans le thème et continue d'être utilisé — mais si la logique de modèle de l'extension a changé, votre surcharge peut être obsolète.

Après chaque mise à jour de l'extension :

Comparez votre fichier de surcharge avec le fichier correspondant dans le répertoire de l'extension mise à jour. Un outil de comparaison de fichiers (diff) ou un éditeur de code peut vous aider.
Fusionnez toutes les modifications pertinentes de la nouvelle version de l'extension dans votre surcharge.
Testez les pages de véhicules sur le site après la fusion.

Garder les surcharges minimales — en ne contenant que les sections que vous devez réellement modifier — réduit le travail requis lors de la fusion des mises à jour.

Référence de configuration

Il n'y a aucun champ de réglage de l'extension qui contrôle directement les surcharges de modèles. La logique de résolution fait partie du système de crochets de WordPress et ne peut pas être modifiée depuis l'administration de l'extension.

Les réglages de Design dans Car Market Hub → Design s'appliquent toujours même lorsqu'une surcharge de modèle est utilisée, car le CSS dynamique est généré via wp_head quel que soit le fichier de modèle servi.

Notes opérationnelles

Exigence de thème enfant. Si vous utilisez un thème commercial ou un thème parent, créez toujours un thème enfant avant d'ajouter des fichiers de surcharge. Les fichiers ajoutés directement à un thème parent sont supprimés lors des mises à jour du thème.
La surcharge doit appeler get_header() et get_footer(). Les propres modèles de l'extension appellent les deux. Si votre surcharge les omet, la page sera servie sans la navigation et le pied de page du thème. Ce n'est presque jamais le comportement souhaité.
Conserver l'espace de noms de l'extension. Les fichiers de modèles de l'extension déclarent namespace AS24CI; et font référence à des constantes internes telles que CPT::POST_TYPE et Options::DESIGN_SINGLE_LAYOUT. Si votre surcharge utilise l'une d'entre elles, conservez la déclaration de l'espace de noms ou qualifiez complètement les noms de classes.
Mode de rendu du code court. Le modèle d'archive prend en charge deux modes de rendu contrôlés par la variable globale $as24ci_render_mode : 'template' (lorsqu'il est servi en tant que page d'archive de CPT) et 'shortcode' (lorsqu'il est inclus par le code court [as24ci_archive]). Le modèle omet get_header() et get_footer() en mode code court. Votre surcharge doit reproduire ce comportement si vous souhaitez que le code court fonctionne correctement aux côtés du modèle d'archive.
Stabilité des classes CSS. Le CSS de l'extension dépend des noms de classes dans le HTML du modèle (par exemple .as24ci-page, .as24ci-page-classic, .as24ci-archive-list, .as24ci-archive-row). Si vous supprimez ou renommez ces classes dans votre surcharge, la feuille de style de l'extension et les réglages de Design cesseront de fonctionner pour ces éléments. Ne modifiez les noms de classes que si vous mettez également à jour le CSS correspondant dans le champ CSS personnalisé ou dans la feuille de style de votre thème.
Classe alignfull. L'extension ajoute la classe alignfull au conteneur .as24ci-page afin que les thèmes basés sur des blocs l'étendent sur toute la largeur. Si vous supprimez cette classe dans votre surcharge, le comportement de pleine largeur du thème basé sur des blocs ne s'appliquera pas.
Configuration requise pour la version PHP et la version de WordPress. Les modèles de l'extension utilisent des fonctionnalités PHP conformes aux exigences déclarées de l'extension. Voir la Configuration requise pour PHP et la base de données.

Dépannage

Symptôme	Cause probable	Ce qu'il faut vérifier
Le fichier de surcharge n'est pas utilisé.	Le fichier est dans le mauvais répertoire, comporte une faute de frappe dans le nom du fichier, ou se trouve dans la racine du thème parent au lieu de la racine du thème enfant.	Confirmez le nom exact du fichier et son emplacement. Utilisez Query Monitor ou vérifiez le code source de la page pour y trouver un commentaire temporaire dans le fichier de surcharge.
Les pages de véhicules renvoient une page blanche ou une erreur PHP après la création de la surcharge.	Le fichier de surcharge contient une erreur de syntaxe PHP ou il manque une inclusion requise.	Vérifiez le journal des erreurs PHP du serveur. Confirmez que le fichier de surcharge ouvre et ferme correctement les balises PHP.
Le CSS de l'extension n'est pas appliqué sur le modèle surchargé.	La classe de conteneur `.as24ci-page` ou `.as24ci-page-classic` est manquante dans le rendu de la surcharge.	Assurez-vous que le conteneur externe `<div class="as24ci-page as24ci-page-classic …">` est présent dans la surcharge.
Les réglages de Design (couleurs, typographie) n'ont aucun effet.	Le rendu CSS dynamique repose sur les classes de conteneur de l'extension. Si elles sont absentes, les règles ciblées ne correspondent pas.	Restaurez les classes de conteneur comme décrit ci-dessus.
Le code court `[as24ci_archive]` n'affiche pas l'en-tête ou le pied de page du thème lorsque la surcharge d'archive est également active.	La surcharge appelle toujours `get_header()` et `get_footer()` sans tenir compte de `$as24ci_render_mode`.	Ajoutez une vérification pour `$as24ci_render_mode === 'template'` avant d'appeler `get_header()` et `get_footer()`, en reproduisant la logique du propre modèle de l'extension.