Système de templates et surcharges

Ce document décrit comment l'extension ADP Car Market Hub charge ses templates front-end et comment un thème peut les surcharger. Il répertorie les fichiers fournis dans le dossier templates/ de l'extension et explique lesquels peuvent être surchargés par le thème via la hiérarchie standard des templates WordPress et lesquels sont chargés directement par les shortcodes.

Quand utiliser ce document

Lisez ce document lorsque vous devez :

• Personnaliser le balisage de la page unique du véhicule, de l'archive des véhicules ou de la page de comparaison à partir d'un thème ou d'un thème enfant.
• Remplacer une petite partie (par exemple le formulaire de filtre de recherche) sans dupliquer l'intégralité du template.
• Comprendre quels fichiers de template peuvent être surchargés en toute sécurité et lesquels changent d'une version à l'autre.

Pour les types de publication personnalisés (CPT) et les taxonomies que ces templates affichent, consultez Custom Post Types And Taxonomies. Pour les shortcodes qui chargent directement des parties de template, consultez Shortcodes For Developers.

Aperçu

L'extension fournit ses templates dans le dossier templates/ de l'extension. Deux mécanismes les exposent :

1. Filtres de la hiérarchie des templates WordPress. L'extension se greffe sur single_template et archive_template. Pour ces deux filtres, elle appelle d'abord locate_template() afin qu'un thème actif ou un thème enfant puisse fournir sa propre copie du fichier. Si aucune surcharge de thème n'est trouvée, le template intégré de l'extension est utilisé.
2. Rendu direct par shortcode. Les shortcodes pour la page de comparaison ([as24ci_compare]) et le filtre de recherche autonome ([as24ci_search_filter]) chargent leurs templates directement depuis le dossier templates/ de l'extension. Ils ne consultent pas le thème pour une surcharge.

Le résultat est que la page de véhicule unique et l'archive de véhicules peuvent être surchargées proprement en déposant un fichier dans le thème actif, tandis que la page de comparaison et le template partiel du filtre de recherche ne changent que lorsque vous modifiez ou filtrez leur sortie via un mécanisme différent.

Fichiers fournis sous templates/

Templates de premier niveau :

• archive-as24ci_car.php — liste d'archives de véhicules.
• single-as24ci_car.php — page unique de véhicule (mise en page par défaut).
• single-as24ci_car-classic.php — mise en page unique alternative "classique".
• page-as24ci_compare.php — page de comparaison générée par [as24ci_compare].

Partiels et ressources :

• parts/search-filter.php — le formulaire de filtre de recherche généré par [as24ci_search_filter].
• icons/ — définitions d'icônes SVG utilisées par les templates.
• css/ et js/ — feuilles de style et scripts front-end fournis avec les templates et mis en file d'attente par le chargeur de ressources (voir Frontend Assets).

Templates surchargeables par le thème

Ces fichiers sont chargés via les filtres single_template / archive_template et respectent donc le thème :

L'extension appelle locate_template( '<file-name>.php' ) sans préfixe de sous-dossier, le fichier de surcharge va donc directement à la racine du thème actif (ou du thème enfant). Si locate_template() renvoie un chemin, l'extension l'utilise ; sinon, elle se rabat sur le template intégré.

Templates non chargés via la hiérarchie du thème

Ces fichiers sont chargés directement par l'extension et ne sont pas détectés par locate_template() :

Pour les personnaliser, vous disposez de trois options fiables :

1. Créez une page ou un template conteneur dans votre thème qui appelle le shortcode concerné et entoure sa sortie avec votre propre balisage.
2. Utilisez les hooks d'action et de filtre que l'extension expose (voir Hooks And Filters, Actions Reference, Filters Reference) pour modifier le comportement plutôt que le balisage.
3. En dernier recours, dupliquez le fichier dans votre thème et chargez-le depuis votre propre template ; vous assumez alors la responsabilité de le maintenir aligné avec les futures versions de l'extension.

Instructions étape par étape

Surcharger la page unique de véhicule

1. Copiez single-as24ci_car.php depuis le dossier templates/ de l'extension.
2. Collez-le à la racine de votre thème actif (ou thème enfant).
3. Modifiez la copie pour y apporter vos changements.
4. Rechargez une page de véhicule unique. WordPress chargera votre fichier via locate_template() au lieu du fichier intégré de l'extension.

Surcharger l'archive de véhicules

1. Copiez archive-as24ci_car.php depuis le dossier templates/ de l'extension.
2. Collez-le à la racine de votre thème actif (ou thème enfant).
3. Modifiez la copie. Rechargez la page d'archive (/cars/ par défaut) pour voir votre version.

Personnaliser la page de comparaison ou le formulaire de filtre de recherche

1. Enveloppez le shortcode concerné dans un template de page personnalisé ou une mise en page par blocs dans votre thème, ou dupliquez le template sous-jacent dans votre thème et chargez-le depuis votre propre template.
2. Vérifiez que toutes les ressources de l'extension dont vous dépendez (CSS/JS, voir Frontend Assets) sont toujours mises en file d'attente sur votre page personnalisée.

Notes opérationnelles

• Utilisez un thème enfant. Placez les surcharges dans un thème enfant pour éviter de les perdre lors des mises à jour du thème parent.
• Interaction avec le gestionnaire de mise en page. L'extension comprend un gestionnaire de mise en page qui organise les blocs dans les pages de véhicule unique et d'archive, configuré depuis l'interface d'administration de l'extension. Si vous remplacez entièrement le template de page unique ou d'archive, vous contournez également le gestionnaire de mise en page. Utilisez des modifications sélectives basées sur des hooks lorsque vous devez conserver ce comportement.
• Activation de la page de comparaison. La page de comparaison est créée lors de l'activation. La page elle-même contient simplement le shortcode [as24ci_compare], son contenu est donc généré par le template de l'extension, et non par single_template / archive_template.
• Shortcode dans n'importe quelle page. Comme [as24ci_archive] réutilise le moteur de rendu de l'archive, vous pouvez intégrer la liste dans n'importe quelle page ou mise en page par blocs WordPress sans avoir à surcharger le template d'archive.
• Mise en file d'attente des ressources. Les fichiers CSS et JavaScript front-end fournis avec l'extension sont mis en file d'attente de manière conditionnelle en fonction de la page actuelle (page unique, archive, utilisation de shortcode). Si vous créez un template conteneur personnalisé qui ne correspond pas aux conditions standard, les ressources de l'extension concernées risquent de ne pas être mises en file d'attente automatiquement.
• Vérifiez le comportement dans la version actuelle de l'extension avant de publier un thème personnalisé. La structure des templates et le balisage des blocs peuvent changer d'une version à l'autre.

Dépannage

• Ma surcharge de thème est ignorée. Confirmez que le nom du fichier correspond exactement (single-as24ci_car.php, archive-as24ci_car.php) et qu'il se trouve à la racine du thème actif. Videz tout cache d'objet ou de page.
• La page unique affiche la mise en page classique (ou vice versa). La mise en page unique est sélectionnée depuis les réglages de design de l'extension dans l'interface d'administration. Modifiez-la à cet endroit plutôt que depuis le thème.
• La page de comparaison n'affiche rien ou une erreur 404. Confirmez que la page de comparaison existe toujours, contient le shortcode [as24ci_compare] et est publiée. Confirmez que la fonctionnalité de comparaison est activée dans l'interface d'administration de l'extension.
• Script ou style front-end manquant sur une page conteneur personnalisée. Le chargeur de ressources de l'extension se base sur la détection du type de publication, de l'archive et des shortcodes. Utilisez les shortcodes officiels à l'intérieur de votre conteneur afin que les ressources correspondantes soient mises en file d'attente automatiquement.
• Vérifiez le comportement dans la version actuelle de l'extension avant de publier une intégration personnalisée. Les chemins des templates et le balisage peuvent évoluer d'une version à l'autre.

Documents connexes

• Custom Post Types And Taxonomies
• Shortcodes For Developers
• Frontend Assets
• Hooks And Filters
• Filters Reference