Suggestions d'adresse via Google Places sur des champs de saisie personnalisés

PLUS

L’autocomplétion d’adresses qu’utilise WP-ImmoMakler dans la recherche par rayon est disponible à partir de la version 5.60.0 en tant que bibliothèque réutilisable sur n’importe quel champ de saisie de votre site web. Vous pouvez l’utiliser, par exemple, pour équiper un formulaire de contact, un outil de recherche d’agent immobilier ou un filtre personnalisé avec les mêmes suggestions — navigation au clavier, mise en cache et protection de votre clé API Google incluses.

Prérequis

Pour que la bibliothèque soit active sur une page, les conditions suivantes doivent être remplies :

Vous utilisez l’édition Plus de WP-ImmoMakler.
Les services Google sont activés dans l’interface d’administration WordPress (wp-admin) sous WP-ImmoMakler → Réglages → Google Maps et une clé API Google Maps Geocoding valide est renseignée.

Si les deux conditions sont remplies, WP-ImmoMakler charge automatiquement le script assets-plus/js/places-autocomplete.js sur chaque page du frontend (en différé). Si le script ne trouve pas de champ de saisie correspondant sur la page, il n’a aucun autre effet — aucune requête n’est envoyée à Google.

Variante 1 : via attribut HTML (recommandé)

Ajoutez l’attribut data-immomakler-autocomplete à un élément <input>. La bibliothèque détecte automatiquement le champ et s’y attache :

<input
  type="text"
  name="adresse"
  placeholder="Code postal, ville ou rue"
  data-immomakler-autocomplete
  autocomplete="off"
>

Lorsque l’utilisateur sélectionne une suggestion, WP-ImmoMakler insère le texte d’adresse formaté dans le champ et déclenche un CustomEvent nommé immomakler:place-selected sur ce même élément. L’événement contient le texte de l’adresse (label) et l’identifiant Google Place (placeId) dans l’objet detail :

const input = document.querySelector('input[name="adresse"]');
input.addEventListener('immomakler:place-selected', (event) => {
  console.log(event.detail.label);   // "Rue Principale 1, 20095 Hambourg, Allemagne"
  console.log(event.detail.placeId); // "ChIJ..."
});

Variante 2 : via l’API JavaScript

Si le champ de saisie est inséré dynamiquement dans la page (par exemple dans un formulaire ouvert en modal), attachez la bibliothèque explicitement :

const input = document.getElementById('mon-champ-adresse');
window.ImmoMaklerPlacesAutocomplete.attach(input, {
  minLength: 4,        // Nombre minimum de caractères avant la première requête (défaut : 3)
  maxResults: 5,       // Nombre maximum de suggestions (défaut : 8)
  debounceMs: 200      // Délai de frappe en millisecondes (défaut : 140)
});

Pour supprimer le lien — par exemple lors de la fermeture d’un modal — utilisez detach :

window.ImmoMaklerPlacesAutocomplete.detach(input);

attach et detach acceptent aussi bien un élément DOM qu’un sélecteur CSS.

Options par champ de saisie en JSON

Vous pouvez également spécifier les options de la variante 2 directement dans l’attribut data-immomakler-autocomplete au format JSON :

<input
  type="text"
  name="adresse"
  data-immomakler-autocomplete='{"minLength": 4, "maxResults": 5}'
>

Traitement des requêtes

WP-ImmoMakler propose trois moyens pour que le script navigateur récupère les suggestions d’adresse — un rapide et deux qui traversent toute la pile WordPress :

Proxy Fast-API (par défaut, rapide). Un script PHP autonome situé à wp-content/cache/immomakler/fast-api/immomakler-autocomplete.php qui ne charge pas WordPress. Il vérifie un token HMAC signé, effectue une vérification same-origin et une limitation de débit par IP, appelle Google Places via cURL et renvoie du JSON. Une requête prend généralement 5–15 ms au lieu de 100–500 ms (démarrage WordPress avec tous les plugins actifs).
Endpoint REST (solution de repli). POST /wp-json/immomakler/v1/places/autocomplete — passe par index.php, traverse les hooks habituels et renvoie les mêmes suggestions.
Endpoint admin-ajax (deuxième solution de repli). POST /wp-admin/admin-ajax.php?action=immomakler_places_autocomplete — prend le relais lorsque l’API REST n’est pas disponible sur le site (par exemple parce qu’elle a été désactivée par un plugin ou un filtre).

Le script navigateur essaie d’abord la voie 1, puis bascule automatiquement sur la voie 2 et enfin sur la voie 3. Le résultat est fonctionnellement identique pour l’utilisateur final ; seule la latence diffère.

Désactiver le proxy Fast-API

Si vos politiques de conformité ou de sécurité exigent qu’aucun fichier PHP en dehors du démarrage WordPress habituel ne soit exécutable, vous pouvez désactiver le proxy Fast-API dans l’interface d’administration WordPress (wp-admin) sous WP-ImmoMakler → Réglages → Google Maps à l’aide de la case à cocher Utiliser le proxy Fast-API. L’autocomplétion d’adresses fonctionnera alors exclusivement via l’endpoint REST (avec admin-ajax comme deuxième solution de repli), et le script du proxy sera supprimé du système de fichiers lors de l’enregistrement.

Vous pouvez également bloquer le chemin wp-content/cache/immomakler/fast-api/*.php via une règle serveur (.htaccess, Nginx) — le script le détecte (HTTP 403) et bascule automatiquement sur la solution de repli REST sans qu’aucune modification du plugin ne soit nécessaire.

Compatibilité avec les plugins de mise en cache

La bibliothèque est délibérément conçue pour fonctionner avec des configurations de mise en cache agressive (WP Rocket, W3 Total Cache, LiteSpeed Cache, WP Super Cache, Cloudflare APO) :

Pas de token de sécurité dans le HTML. Avant la version 5.60.0, WP-ImmoMakler inscrivait dans le code source de la page un token valable 15 minutes. Sur les pages mises en cache, ce token était déjà expiré pour le premier visiteur. À partir de la version 5.60.0, le token est récupéré au premier focus sur le champ de saisie via l’endpoint non mis en cache /wp-json/immomakler/v1/places/token.
Solution de repli à plusieurs niveaux. Si le proxy rapide échoue (par exemple parce qu’un token a expiré), la bibliothèque en récupère automatiquement un nouveau et réessaie. Si le proxy reste inaccessible, les requêtes basculent de façon transparente vers l’API REST WordPress et enfin vers admin-ajax. L’autocomplétion d’adresses fonctionne dans tous les cas.

Si votre plugin de mise en cache gère les routes REST de façon inhabituelle, excluez le chemin /wp-json/immomakler/v1/places/* du traitement du cache.

Personnalisation via des filtres

Trois filtres influencent le comportement de la bibliothèque :

// Ne pas insérer le script automatiquement dans le pied de page, mais le charger
// soi-même via wp_enqueue_script( 'immomakler-places-autocomplete' ) sur des pages spécifiques :
add_filter( 'immomakler_places_autocomplete_auto_enqueue', '__return_false' );

// Durée de vie du token (en secondes, défaut 900 = 15 minutes) :
add_filter( 'immomakler_places_token_ttl', fn () => 600 );

// Nombre minimum de caractères / nombre maximum de suggestions / délai de frappe :
add_filter( 'immomakler_places_autocomplete_min_length', fn () => 4 );
add_filter( 'immomakler_places_autocomplete_max_results', fn () => 5 );
add_filter( 'immomakler_places_autocomplete_debounce_ms', fn () => 200 );