Système de templates front-end

Ce document explique comment le plugin ADP Car Market Hub affiche les pages de véhicules sur le front-end, comment ses templates intégrés s'articulent avec le thème WordPress actif, et quels points d'extension sont exposés aux thèmes et aux shortcodes.

Quand utiliser ce document

Lisez ce document si vous devez :

• Comprendre quel fichier affiche la page de véhicule unique ou l'archive de véhicules.
• Décider s'il faut utiliser une liste basée sur un shortcode dans une page normale ou s'appuyer sur l'archive CPT.
• Étendre ou surcharger la mise en page depuis un thème enfant. Pour le mécanisme de surcharge, consultez Surcharges de templates.

Aperçu

Le plugin enregistre son type de publication as24ci_car avec le support des archives et fournit un ensemble restreint de templates intégrés sous le répertoire templates/ du plugin. Deux filtres WordPress acheminent les requêtes vers ces templates lorsque le thème actif ne fournit pas sa propre version :

• single_template — utilisé pour is_singular( 'as24ci_car' ).
• archive_template — utilisé pour is_post_type_archive( 'as24ci_car' ).

Chaque filtre demande d'abord à WordPress de localiser une surcharge au niveau du thème (locate_template()), et ne se rabat sur le fichier intégré du plugin que si aucune surcharge n'existe.

Templates intégrés

Les fichiers suivants se trouvent sous le dossier templates/ du plugin et sont chargés par les filtres ci-dessus (ou par des shortcodes) :

• single-as24ci_car.php — fine enveloppe qui sélectionne la mise en page de véhicule unique appropriée en fonction de l'option as24ci_design_single_layout et inclut le fichier de mise en page choisi.
• single-as24ci_car-classic.php — la mise en page actuelle de véhicule unique. L'enveloppe charge actuellement toujours ce fichier ; les versions futures pourront ajouter d'autres mises en page. Vérifiez le comportement par rapport à la version actuelle du plugin avant de publier des textes destinés aux clients.
• archive-as24ci_car.php — la mise en page de l'archive de véhicules utilisée pour l'archive CPT et pour le shortcode [as24ci_archive].
• parts/search-filter.php — partiel rendu par [as24ci_search_filter] pour afficher le formulaire de recherche autonome.
• page-as24ci_compare.php — page de comparaison rendue par [as24ci_compare].
• icons/ — helpers d'icônes SVG intégrés partagés utilisés dans les templates.
• css/ et js/ — ressources dont dépendent les templates.

Comment une requête atteint un template

1. WordPress analyse la requête et la résout en un véhicule unique ou en archive de véhicules.
2. Juste avant l'affichage, WordPress applique single_template ou archive_template.
3. Le callback de filtre du plugin : - renvoie le $template d'origine lorsque la requête ne concerne pas as24ci_car ; - appelle locate_template( '<template>.php' ) pour donner au thème actif (enfant) la première opportunité de surcharge ; - si aucun fichier de thème n'existe, renvoie le fichier intégré du répertoire templates/ du plugin ; - si aucun des deux n'existe, renvoie le $template d'origine afin que WordPress puisse se rabattre sur sa hiérarchie standard.

Les shortcodes suivent le même principe de priorité, mais ils n'appellent pas locate_template() — ils incluent toujours les fichiers d'archive / de comparaison / de filtre de recherche intégrés du plugin. Voir Shortcodes et Surcharges de templates pour les implications.

Intégration des shortcodes et du mode de rendu

Le plugin expose un indicateur global, $as24ci_render_mode, que les gestionnaires de shortcodes définissent sur 'shortcode' pendant que leur template intégré s'exécute. Le code conditionnel dans les templates et dans les classes de support (par exemple pour le chargement des ressources) utilise cet indicateur pour appliquer la même logique sur les pages basées sur des shortcodes que celle appliquée sur l'archive CPT native.

Le shortcode [as24ci_archive] remplace la requête globale $wp_query par une requête personnalisée pendant le rendu du template d'archive, et restaure la requête précédente et wp_reset_postdata() ensuite, afin qu'il puisse être intégré en toute sécurité dans une page normale.

Référence de configuration

Les options de mise en page, de design et de fonctionnalités qui affectent ce qui est rendu à l'intérieur des templates (zones de filtrage, ensemble de champs de favoris, activation de l'agent de recherche, etc.) sont documentées dans Stockage des options et des réglages.

Notes opérationnelles

• Les callbacks de filtre du plugin renvoient le chemin du fichier intégré sous forme de chaîne. WordPress inclut le fichier avec son chargeur de template standard, de sorte que les variables globales telles que $post, $wp_query et les classes de body se comportent comme dans n'importe quel template de thème.
• Les templates intégrés déclarent namespace AS24CI; et exit lorsque ABSPATH n'est pas défini, reflétant la protection standard de WordPress.
• Les fichiers de templates font référence à des classes du plugin telles que Archive_Filters, Field_Mapping, Schema, Options et Locations pour assembler leurs données. Les thèmes surchargant le fichier doivent conserver ces références intactes (ou reproduire la récupération de données équivalente) pour éviter les avertissements de variables non définies.
• L'archive basée sur un shortcode force un nouveau WP_Query à partir des paramètres $_GET via Archive_Filters::build_query_args_from_request(), de sorte que les filtres d'URL fonctionnent de manière identique sur l'archive CPT et sur les pages de shortcodes.

Dépannage

• La mise en page du plugin n'apparaît jamais — vérifiez que le thème actif ne définit pas son propre single-as24ci_car.php ou archive-as24ci_car.php ; les fichiers du thème l'emportent toujours. Voir Surcharges de templates.
• Une page utilisant [as24ci_archive] affiche la mauvaise publication — le shortcode remplace la requête globale pendant son exécution et la restaure ensuite. Si un composant de thème personnalisé lit la requête globale avant le traitement du shortcode, l'ordre dans lequel la page affiche les parties de la mise en page est important ; intégrez le shortcode dans la zone de contenu principal plutôt que dans l'en-tête ou la barre latérale.
• La pagination se réinitialise à la page 1 dans [as24ci_archive] — le shortcode lit ?paged= et ?page= depuis l'URL. Assurez-vous que la structure de vos permaliens autorise les chaînes de requête ou utilisez un permalien compatible avec le shortcode.
• La ressource (CSS/JS) n'est pas chargée sur une page de shortcode — le plugin détecte les shortcodes et l'indicateur $as24ci_render_mode pour charger les ressources. Si un constructeur de page met en cache le rendu de la page, videz de force ce cache après avoir modifié la page afin que le shortcode soit détecté lors de la mise en file d'attente.

Documents connexes

• Surcharges de templates
• Shortcodes
• Types de publications personnalisés et taxonomies
• Stockage des options et des réglages
• Aperçu de l'architecture