Documentation · Guide d'intégration

Intégration des constructeurs de pages

Ce document explique comment utiliser l'extension ADP Car Market Hub au sein des flux de travail des constructeurs de pages (page builders), comment placer des shortcodes sur des pages créées avec n'importe quel éditeur de page, et ce qu'il convient de valider sur le front-end après leur intégration.

Quand utiliser ce document

Utilisez ce document si vous devez :

Intégrer des listes de véhicules, des filtres de recherche ou l'outil de comparaison sur des pages créées avec un constructeur de pages tel qu'Elementor, WPBakery, Divi, Beaver Builder ou l'éditeur de blocs WordPress (Gutenberg).
Créer une page d'accueil ou une page d'atterrissage personnalisée qui doit afficher un sous-ensemble filtré de l'inventaire de véhicules.
Placer un filtre de recherche autonome sur une page afin que les visiteurs puissent commencer à filtrer avant de naviguer vers la page des résultats.
Diagnostiquer des problèmes où les ressources de l'extension ne se chargent pas correctement sur une page de constructeur de pages.

Le public cible est un administrateur ou un concepteur de site WordPress. Aucune connaissance en PHP ou CSS n'est requise pour le placement de base des shortcodes.

Aperçu

L'extension fournit trois shortcodes front-end que vous pouvez placer sur n'importe quelle page WordPress, y compris les pages créées avec des constructeurs de pages tiers :

Shortcode	Ce qu'il affiche
`[as24ci_archive]`	Liste complète des véhicules avec filtres de recherche, contrôles de tri, onglets d'état et pagination. Équivalent à la page d'archive des véhicules.
`[as24ci_search_filter]`	Formulaire de filtre de recherche autonome sans résultats. Soumet les données à l'archive des véhicules ou à toute page de résultats que vous spécifiez.
`[as24ci_compare]`	Tableau de comparaison des véhicules. Dépend des véhicules ayant été ajoutés à la liste de comparaison par le visiteur.

Des shortcodes supplémentaires sont disponibles pour les fonctionnalités secondaires :

Shortcode	Ce qu'il affiche
`[as24ci_favorites]`	Liste des véhicules que le visiteur a marqués comme favoris.
`[as24ci_location_box post_id=""]`	Carte de l'emplacement du concessionnaire pour la publication Location spécifiée.
`[as24ci_hours_box post_id=""]`	Carte des horaires d'ouverture pour la publication Location spécifiée.

Ces shortcodes fonctionnent dans n'importe quel constructeur de pages prenant en charge les shortcodes standard de WordPress. Le rendu est identique à celui des pages correspondantes gérées par l'extension.

Prérequis

Avant de placer des shortcodes :

L'extension est installée et activée.
Au moins un véhicule a été importé (pour [as24ci_archive] et [as24ci_search_filter]).
Les permaliens personnalisés (« jolis permaliens ») sont activés (Réglages → Permaliens). Sans permaliens personnalisés, l'URL de l'archive des véhicules peut ne pas se résoudre correctement lorsque [as24ci_search_filter] redirige un visiteur vers la page des résultats.
Si vous utilisez l'éditeur de blocs (Gutenberg), aucune configuration supplémentaire n'est requise. Si vous utilisez un constructeur de pages tiers, vérifiez qu'il préserve les shortcodes WordPress sans encoder ni échapper les crochets.

Instructions étape par étape

Intégrer l'archive des véhicules sur une page

Créez une nouvelle page ou ouvrez une page existante dans votre constructeur de pages.
Ajoutez un bloc de shortcode (ou son équivalent dans votre constructeur de pages — Elementor propose un widget Shortcode, WPBakery un élément Single Image → Shortcode, Divi un module Code, etc.).
Collez le shortcode :

   [as24ci_archive]

Pour pré-filtrer la liste — par exemple pour n'afficher que les véhicules électriques — utilisez les attributs de shortcode facultatifs :

   [as24ci_archive fuel="electric" per_page="24"]

Attributs pris en charge :

Attribut	Valeurs	Description
`make`	Tout identifiant de marque (ex. `bmw`)	Pré-sélectionne une marque.
`model`	Tout identifiant de modèle (ex. `3-series`)	Pré-sélectionne un modèle (à utiliser avec `make`).
`price_min`	Entier	Filtre de prix minimum.
`price_max`	Entier	Filtre de prix maximum.
`fuel`	Tout identifiant de type de carburant	Pré-sélectionne un type de carburant.
`body`	Tout identifiant de type de carrosserie	Pré-sélectionne un type de carrosserie.
`order_by`	`price`, `mileage`, `date`	Champ de tri par défaut.
`order`	`asc`, `desc`	Direction du tri. Par défaut `asc`.
`per_page`	`12`, `24`, `48`, `72`, `all`	Résultats par page. Par défaut `24`.

Les attributs de shortcode définissent les valeurs par défaut. Les visiteurs peuvent toujours les remplacer en interagissant avec les filtres sur la page. Les paramètres de requête d'URL ont toujours la priorité sur les attributs de shortcode.

Publiez ou prévisualisez la page et confirmez que la liste des véhicules apparaît.

Intégrer un filtre de recherche autonome

Placez [as24ci_search_filter] n'importe où sur une page — par exemple sur la page d'accueil — pour permettre aux visiteurs de définir leurs critères avant d'être redirigés vers la page des résultats.

[as24ci_search_filter results_url="/cars/"]

L'attribut results_url spécifie l'endroit où le formulaire soumet les données. Par défaut, il s'agit de l'URL de l'archive des véhicules. Définissez-le sur l'URL de n'importe quelle page contenant [as24ci_archive].
Si l'extension ne peut pas déterminer automatiquement l'URL de l'archive et que results_url n'est pas défini, le formulaire utilise par défaut /cars/.

Utiliser la page de comparaison comme modèle

La page de comparaison est un modèle de page WordPress spécial (page-as24ci_compare.php). L'extension peut créer automatiquement une page Compare lors de l'installation. Vous pouvez également placer [as24ci_compare] dans un bloc de shortcode sur n'importe quelle page standard pour intégrer le tableau de comparaison en ligne.

Référence de configuration

Tous les shortcodes utilisent les réglages déjà définis dans l'administration de l'extension. Il n'y a pas de champs de configuration distincts pour le mode constructeur de pages.

Attribut de shortcode	Origine des options sous-jacentes
Quels filtres apparaissent dans `[as24ci_archive]` et `[as24ci_search_filter]`	La mise en page des filtres active configurée dans l'onglet Filtres de l'administration de l'extension.
Design visuel de tous les shortcodes	Car Market Hub → Design — couleurs, typographie, rayon de bordure, etc.
Indicateurs de fonctionnalités (favoris, comparaison, alerte de recherche)	Car Market Hub → Réglages (et l'assistant de configuration). Si une fonctionnalité est désactivée, le shortcode correspondant n'affiche rien ou affiche un message.

Chargement des ressources

L'extension détecte si un shortcode est présent sur la page actuelle à l'aide de la fonction has_shortcode() de WordPress, et met automatiquement en file d'attente les fichiers CSS et JavaScript appropriés. Vous n'avez pas besoin de configurer manuellement le chargement des ressources.

Sur les pages utilisant [as24ci_archive] ou [as24ci_compare], les feuilles de style suivantes sont mises en file d'attente :

as24ci-archive.css — pour [as24ci_archive]
as24ci-compare.css — pour [as24ci_compare] et pour le bouton de comparaison sur les pages d'archive et de véhicule unique
as24ci-search-agent.css — lorsque la fonctionnalité d'alerte de recherche est activée

Le bloc CSS de design dynamique (<style id="as24ci-dynamic-styles">) est généré dans <head> sur chaque page du front-end, et pas seulement sur les pages spécifiques à l'extension.

Notes opérationnelles

Pagination sur les pages de shortcode. Le shortcode [as24ci_archive] lit les paramètres de requête ?paged= et ?page= pour la pagination. Lorsqu'un constructeur de pages ou un thème utilise ces paramètres à ses propres fins, un conflit peut survenir. Testez la pagination sur la page dans son contexte final.
Permaliens simples. Lorsque les permaliens simples (chaîne de requête) sont activés, is_post_type_archive() renvoie faux pour l'archive de l'extension. L'extension se rabat sur la détection has_shortcode(), de sorte que le CSS et le JavaScript sont toujours chargés. Cependant, le results_url pour [as24ci_search_filter] peut ne pas se résoudre correctement — préférez les permaliens personnalisés en production.
Rendu du contenu du constructeur de pages. Certains constructeurs de pages effectuent le rendu des shortcodes sur le serveur (do_shortcode standard) et d'autres via Ajax ou côté client. Les shortcodes de l'extension reposent sur un rendu standard côté serveur. Si un constructeur de pages diffère le rendu côté client, le résultat peut apparaître vide dans l'aperçu du constructeur mais devrait s'afficher correctement sur le front-end publié.
Shortcodes imbriqués. N'imbriquez pas les shortcodes de l'extension les uns dans les autres. Chaque shortcode gère sa propre WP_Query et son état global.
Mise en page pleine largeur. Tout comme les modèles d'archive et de véhicule unique de l'extension, le rendu du shortcode enveloppe tout dans .as24ci-page.alignfull. Sur les thèmes basés sur des blocs, cela permet à la liste de s'étendre sur toute la largeur. Si le constructeur de pages limite la page à un conteneur plus étroit, le contenu du shortcode sera contraint par ce conteneur. Consultez l'intégration du thème Theme Integration pour plus de détails.
Position du filtre de recherche. Le shortcode [as24ci_search_filter] affiche le formulaire de filtre mais pas de liste de résultats. Lorsqu'il est placé sur la page d'accueil, l'action du formulaire doit pointer vers une page distincte contenant [as24ci_archive].

Dépannage

Symptôme	Cause probable	Ce qu'il faut vérifier
Le shortcode s'affiche sous forme de texte brut (`[as24ci_archive]`).	Le constructeur de pages échappe ou encode le shortcode au lieu de l'exécuter.	Utilisez le widget dédié Shortcode ou le bloc Code du constructeur de pages plutôt qu'un bloc de texte brut.
Le shortcode d'archive ne montre aucun véhicule.	Aucun véhicule n'a encore été importé, ou les attributs de pré-filtrage du shortcode ne correspondent à aucun véhicule.	Importez d'abord des véhicules. Vérifiez les valeurs des attributs par rapport aux données réelles dans Car Market Hub → Cars.
Le CSS n'est pas appliqué sur la page du shortcode.	Le constructeur de pages supprime ou diffère les feuilles de style de l'extension.	Vérifiez l'onglet Réseau des outils de développement du navigateur pour trouver la feuille de style `as24ci-archive` ou `as24ci-single`. Si elle est manquante, vérifiez si le constructeur de pages dispose d'une option pour préserver les ressources tierces.
Le CSS dynamique (`as24ci-dynamic-styles`) est manquant.	Une extension de mise en cache ou d'optimisation supprime les blocs `<style>` intégrés de `<head>`.	Excluez `as24ci-dynamic-styles` de la règle d'optimisation, ou ajoutez les poignées `as24ci-*` à la liste d'autorisation.
La pagination ne fonctionne pas sur la page du shortcode d'archive.	Le paramètre `?paged=` est consommé ou réécrit par le thème ou le constructeur de pages.	Testez avec une navigation par URL simple. Vérifiez si le thème ou le constructeur de pages intercepte les paramètres de requête.
`[as24ci_search_filter]` soumet les données à la mauvaise URL.	L'attribut `results_url` est manquant ou pointe vers une page sans `[as24ci_archive]`.	Ajoutez `results_url="/cars/"` (ou le chemin correct) au shortcode.