Sugerencias de dirección con Google Places en campos de entrada personalizados

PLUS

El autocompletado de direcciones que WP-ImmoMakler utiliza en la búsqueda por radio está disponible a partir de la versión 5.60.0 como biblioteca reutilizable en cualquier campo de entrada de su sitio web. Puede utilizarlo, por ejemplo, para equipar un formulario de contacto, un buscador de agentes inmobiliarios o un filtro personalizado con las mismas sugerencias — incluida la navegación por teclado, caché y protección de su clave de API de Google.

Requisitos previos

Para que la biblioteca se active en una página, deben cumplirse los siguientes requisitos:

Usted utiliza la edición Plus de WP-ImmoMakler.
Los servicios de Google están activados en el backend de WordPress (wp-admin) bajo WP-ImmoMakler → Ajustes → Google Maps y se ha introducido una clave de API de Google Maps Geocoding válida.

Si se cumplen ambas condiciones, WP-ImmoMakler carga automáticamente el script assets-plus/js/places-autocomplete.js en cada página del frontend (diferido). Si el script no encuentra ningún campo de entrada coincidente en la página, no tiene ningún efecto adicional — no se generan solicitudes a Google.

Variante 1: mediante atributo HTML (recomendado)

Añada el atributo data-immomakler-autocomplete a un elemento <input>. La biblioteca detecta el campo automáticamente y se vincula a él:

<input
  type="text"
  name="direccion"
  placeholder="Código postal, ciudad o calle"
  data-immomakler-autocomplete
  autocomplete="off"
>

Cuando el usuario selecciona una sugerencia, WP-ImmoMakler inserta el texto de dirección formateado en el campo y dispara un CustomEvent con el nombre immomakler:place-selected en el mismo elemento. El evento contiene el texto de dirección (label) y el ID de lugar de Google (placeId) en el objeto detail:

const input = document.querySelector('input[name="direccion"]');
input.addEventListener('immomakler:place-selected', (event) => {
  console.log(event.detail.label);   // "Calle Principal 1, 20095 Hamburgo, Alemania"
  console.log(event.detail.placeId); // "ChIJ..."
});

Variante 2: mediante API de JavaScript

Si el campo de entrada se inserta dinámicamente en la página (por ejemplo, en un formulario abierto en un modal), vincule la biblioteca de forma explícita:

const input = document.getElementById('mi-campo-direccion');
window.ImmoMaklerPlacesAutocomplete.attach(input, {
  minLength: 4,        // Número mínimo de caracteres antes de la primera solicitud (por defecto: 3)
  maxResults: 5,       // Número máximo de sugerencias (por defecto: 8)
  debounceMs: 200      // Retraso de escritura en milisegundos (por defecto: 140)
});

Para eliminar el vínculo — por ejemplo, al cerrar un modal — utilice detach:

window.ImmoMaklerPlacesAutocomplete.detach(input);

attach y detach aceptan tanto un elemento DOM como un selector CSS.

Opciones por campo de entrada como JSON

También puede especificar las opciones de la Variante 2 directamente en el atributo data-immomakler-autocomplete en formato JSON:

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

Cómo se procesan las solicitudes

WP-ImmoMakler ofrece tres formas para que el script del navegador obtenga las sugerencias de dirección — una rápida y dos que pasan por toda la pila de WordPress:

Proxy Fast-API (por defecto, rápido). Un script PHP independiente en wp-content/cache/immomakler/fast-api/immomakler-autocomplete.php que no carga WordPress. Verifica un token HMAC firmado, realiza una comprobación same-origin y un límite de velocidad por IP, llama a Google Places mediante cURL y devuelve JSON. Una solicitud suele tardar 5–15 ms en lugar de 100–500 ms (arranque de WordPress con todos los plugins activos).
Endpoint REST (alternativa). POST /wp-json/immomakler/v1/places/autocomplete — se ejecuta a través de index.php, pasa por los hooks habituales y devuelve las mismas sugerencias.
Endpoint admin-ajax (segunda alternativa). POST /wp-admin/admin-ajax.php?action=immomakler_places_autocomplete — interviene cuando la API REST no está disponible en el sitio (por ejemplo, porque ha sido desactivada por un plugin o un filtro).

El script del navegador intenta primero la ruta 1, luego recurre automáticamente a la ruta 2 y finalmente a la ruta 3. El resultado funcional es idéntico para el usuario final; solo difiere la latencia.

Desactivar el proxy Fast-API

Si sus políticas de cumplimiento o seguridad requieren que no haya archivos PHP ejecutables fuera del arranque habitual de WordPress, puede desactivar el proxy Fast-API en el backend de WordPress (wp-admin) bajo WP-ImmoMakler → Ajustes → Google Maps con la casilla Usar proxy Fast-API. El autocompletado de direcciones funcionará entonces exclusivamente a través del endpoint REST (con admin-ajax como segunda alternativa), y el script del proxy se eliminará del sistema de archivos al guardar.

Alternativamente, puede bloquear la ruta wp-content/cache/immomakler/fast-api/*.php mediante una regla de servidor (.htaccess, Nginx) — el script lo detecta (HTTP 403) y cambia automáticamente a la alternativa REST sin necesidad de modificar nada en el plugin.

Compatibilidad con plugins de caché

La biblioteca está diseñada deliberadamente para funcionar con configuraciones de caché agresiva (WP Rocket, W3 Total Cache, LiteSpeed Cache, WP Super Cache, Cloudflare APO):

Sin token de seguridad en el HTML. Antes de la versión 5.60.0, WP-ImmoMakler escribía en el código fuente de la página un token válido durante 15 minutos. En las páginas en caché, este token ya había expirado para el primer visitante. A partir de la versión 5.60.0, el token se obtiene en el primer enfoque del campo de entrada a través del endpoint no cacheable /wp-json/immomakler/v1/places/token.
Alternativa de múltiples niveles. Si el proxy rápido falla (por ejemplo, porque un token ha caducado), la biblioteca obtiene automáticamente uno nuevo y lo reintenta. Si el proxy sigue sin responder, las solicitudes se redirigen de forma transparente a la API REST de WordPress y, finalmente, a admin-ajax. El autocompletado de direcciones funciona en cualquier caso.

Si su plugin de caché gestiona las rutas REST de forma inusual, excluya la ruta /wp-json/immomakler/v1/places/* del procesamiento de caché.

Personalización mediante filtros

Tres filtros influyen en el comportamiento de la biblioteca:

// No insertar el script automáticamente en el pie de página, sino cargarlo
// manualmente con wp_enqueue_script( 'immomakler-places-autocomplete' ) en páginas concretas:
add_filter( 'immomakler_places_autocomplete_auto_enqueue', '__return_false' );

// Tiempo de vida del token (en segundos, por defecto 900 = 15 minutos):
add_filter( 'immomakler_places_token_ttl', fn () => 600 );

// Número mínimo de caracteres / máximo de sugerencias / retraso de escritura:
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 );