Documentation · Documentation technique

Surcharges de modèles

Ce document explique comment surcharger les modèles front-end intégrés du plugin ADP Car Market Hub depuis un thème (enfant) afin que les mises à jour n'écrasent pas vos personnalisations.

Quand utiliser ce document

Lisez ce document si vous devez :

Ajuster le balisage, la mise en page ou l'ordre des champs sur la page de véhicule unique ou l'archive de véhicules sans modifier les fichiers sources du plugin.
Appliquer des conteneurs (wrappers), des barres latérales ou des hooks spécifiques au thème sur les pages du plugin.
Migrer des personnalisations existantes dans un thème enfant pour les rendre sûres lors des mises à jour.

Pour le flux de chargement des modèles sous-jacent, consultez Système de modèles front-end. Pour les shortcodes basés sur des modèles, consultez Shortcodes.

Aperçu

Le plugin affiche les pages de véhicules uniques et l'archive de véhicules via deux filtres WordPress :

single_template — remplacé par single-as24ci_car.php (surcharge du thème) ou le fichier intégré du plugin.
archive_template — remplacé par archive-as24ci_car.php (surcharge du thème) ou le fichier intégré du plugin.

Pour chaque filtre, le plugin appelle d'abord locate_template(). Si le thème actif (ou son thème enfant) fournit un fichier avec le nom attendu, ce fichier l'emporte. Sinon, le plugin se rabat sur le fichier fourni dans son propre répertoire templates/.

Cela rend les surcharges simples : déposez un fichier correctement nommé dans votre thème et WordPress le chargera à la place de la version intégrée.

Configuration requise ou prérequis

Un thème enfant est fortement recommandé afin que les mises à jour du thème n'écrasent pas vos surcharges.
Une familiarité avec les fichiers de modèles intégrés. Ils utilisent l'espace de noms AS24CI et s'appuient sur des classes du plugin telles que Archive_Filters, Field_Mapping, Schema, Options et Locations.
Un accès en lecture au répertoire templates/ du plugin pour copier le balisage intégré actuel comme point de départ.

Instructions étape par étape

Identifiez le modèle que vous souhaitez surcharger : - Page de véhicule unique → single-as24ci_car.php. - Page d'archive de véhicules → archive-as24ci_car.php.
Copiez le fichier intégré depuis le répertoire templates/ du plugin vers la racine de votre thème (enfant) en utilisant le même nom de fichier.
Modifiez la copie dans votre thème. Conservez les références de classe et les recherches de données existantes, à moins d'être sûr de leur remplacement.
Videz tous les caches de page complète ou de modèle.
Rechargez la page concernée sur le front-end et confirmez que la surcharge est chargée (par exemple, en affichant le code source de la page pour y trouver un commentaire de repère que vous avez ajouté).

Emplacements de surcharge

Le plugin utilise locate_template() avec le nom de fichier brut. Cela signifie que WordPress recherche dans :

Le répertoire racine du thème enfant actif.
Le répertoire racine du thème parent actif.

Les structures de sous-répertoires au sein d'un thème (par exemple <theme>/templates/single-as24ci_car.php) ne sont pas parcourues par le filtre du plugin. Placez les fichiers de surcharge à la racine du thème en utilisant le nom de fichier exact.

Ce que vous pouvez surcharger

single-as24ci_car.php — l'intégralité de la page de véhicule unique. Le conteneur intégré est volontairement léger ; la mise en page réelle réside dans single-as24ci_car-classic.php. Surcharger le conteneur signifie que vous assumez l'entière responsabilité du choix et de l'inclusion d'une mise en page.
archive-as24ci_car.php — l'intégralité de la page d'archive de véhicules. C'est également le fichier que le shortcode [as24ci_archive] inclut (voir Limitations ci-dessous).

Ce qui n'est pas directement surchargeable

Les parties de modèle (par exemple templates/parts/search-filter.php) sont chargées avec include depuis des chemins absolus du plugin et ne passent pas par locate_template(). Pour les personnaliser, surchargez le modèle parent qui les inclut et reproduisez le rendu requis, ou utilisez les hooks et filtres disponibles du plugin.
Les modèles de shortcodes — [as24ci_archive], [as24ci_compare] et [as24ci_search_filter] incluent toujours les fichiers intégrés du plugin (archive-as24ci_car.php, page-as24ci_compare.php, parts/search-filter.php). Une surcharge de archive-as24ci_car.php par le thème affecte donc également le shortcode [as24ci_archive], mais les modèles de comparaison et de filtre de recherche ne peuvent pas être surchargés via locate_template().
Le CSS/JS du plugin dont dépendent les modèles. Surchargez les styles via la feuille de style de votre thème plutôt qu'en retirant les ressources mises en file d'attente par le plugin.

Notes opérationnelles

Lors de la mise à jour du plugin, examinez le journal des modifications (changelog) pour repérer les modifications apportées aux modèles intégrés. Si le plugin ajoute ou supprime des données affichées par le modèle, votre surcharge devra peut-être être mise à jour en conséquence.
Évitez de mélanger des surcharges partielles avec du code qui suppose la structure du fichier intégré. Conservez la surcharge proche de l'original ou documentez la divergence à l'intérieur du fichier.
Les surcharges de thème ne sont pas affectées par les mises à jour automatiques du plugin car WordPress ne met à jour que les fichiers situés dans le répertoire du plugin.
Les surcharges s'appliquent à la fois aux administrateurs connectés et aux visiteurs. Il n'y a pas de mécanisme de surcharge par rôle dans le plugin.
Les surcharges ne peuvent pas contourner les vérifications de type de publication (post-type) ou de capacités appliquées par les filtres : la surcharge n'est chargée que pour les requêtes d'archive ou de page unique as24ci_car légitimes.

Dépannage

Le fichier de surcharge est ignoré — confirmez que le fichier se trouve à la racine du thème actif et utilise le nom de fichier exact (single-as24ci_car.php ou archive-as24ci_car.php). Vérifiez l'absence de faute de frappe ou si un thème parent ne fournit pas déjà ce fichier.
Erreur fatale après surcharge — les modèles intégrés utilisent l'espace de noms AS24CI et font référence à des classes du plugin. Si vous n'avez copié qu'une partie du fichier, restaurez la déclaration de l'espace de noms et la protection defined( 'ABSPATH' ), et gardez intactes les recherches Field_Mapping / Archive_Filters.
La surcharge apparaît sur l'archive CPT mais pas dans le shortcode — les deux chemins chargent archive-as24ci_car.php depuis le répertoire templates/ du plugin ; le shortcode n'utilise pas locate_template(). Vérifiez le chemin de votre surcharge et assurez-vous qu'aucun plugin de cache ne sert une ancienne version de la page.
La mise en page n'est pas stylisée après la surcharge — le CSS intégré attend des noms de classes spécifiques. Conservez ces noms de classes dans votre surcharge ou étendez la feuille de style du thème pour couvrir le nouveau balisage.