Search Autocomplete
Proporciona funcionalidad de autocompletado para cualquier campo de entrada de formulario en un sitio Drupal, con fuentes de sugerencias desde Views o callbacks personalizados.
search_autocomplete
Install
composer require 'drupal/search_autocomplete:^4.0'
composer require 'drupal/search_autocomplete:^3.0'
composer require 'drupal/search_autocomplete:^2.0'
Overview
Search Autocomplete es un módulo potente que añade funcionalidad de autocompletado a prácticamente cualquier campo de entrada en tu sitio Drupal. Durante la entrada del usuario, el campo se expande para mostrar una lista desplegable de sugerencias antes del envío del formulario.
Las sugerencias pueden obtenerse desde Views usando cualquier tipo de entidad disponible en tu sitio, o desde callbacks PHP personalizados o APIs externas. El módulo proporciona una integración profunda con el módulo Search de Drupal core y el Search Block de forma predeterminada.
Las capacidades principales incluyen activadores configurables por número mínimo de caracteres, límites máximos de sugerencias, comportamientos de auto-envío y auto-redirección, mensajes personalizables de "sin resultados" y "más resultados", y múltiples temas CSS para estilizar el desplegable de sugerencias. La seguridad está garantizada mediante la integración de DOMPurify para la prevención de XSS.
Los escenarios básicos pueden configurarse completamente a través de la interfaz, como el autocompletado de filtros expuestos de Views. Los usuarios avanzados pueden crear escenarios complejos con código personalizado para integrar fuentes de datos externas como Twitter, Google Places o cualquier API.
Features
- Añadir sugerencias de autocompletado a cualquier campo de entrada usando selectores CSS
- Usar Views como fuentes de datos de sugerencias con plugins personalizados de display, style y row
- Soporte para URLs de callback personalizadas (rutas internas de Drupal o APIs externas)
- Auto-envío del formulario cuando se selecciona una sugerencia
- Auto-redirección al enlace de la sugerencia cuando se selecciona
- Número mínimo configurable de caracteres antes de que se active el autocompletado
- Número máximo configurable de sugerencias mostradas
- Mensaje personalizado de 'sin resultados' con etiqueta, valor y enlace de redirección configurables
- Mensaje personalizado de 'ver todos los resultados' con etiqueta, valor y enlace de redirección configurables
- Múltiples temas CSS (basic, minimal) con soporte para temas personalizados
- Herramienta de ayuda para administradores que detecta selectores CSS al pasar sobre campos de entrada
- Protección XSS mediante integración de la biblioteca DOMPurify
- Autocompletado preconfigurado para el Search Block y Search Form de Drupal core
- Soporte para campos de múltiples valores separados por comas
- Agrupación de sugerencias por categoría en Views
- Soporte de tokens en mensajes: [search-phrase] y [search-count]
- Indicadores de control de acceso para proteger configuraciones de edición o eliminación
Use Cases
Autocompletado del Search Block
Habilitar autocompletado en el Search Block de Drupal core para sugerir títulos de contenido coincidentes mientras los usuarios escriben. La configuración predeterminada busca nodes publicados y muestra hasta 10 sugerencias. Seleccionar una sugerencia envía el formulario de búsqueda con ese valor.
Autocompletado de Filtros Expuestos de Views
Añadir autocompletado a cualquier campo de entrada de filtro expuesto de Views. Crear una nueva configuración, usar la herramienta de ayuda para administradores para identificar el selector CSS del filtro, y especificar un display de View como fuente de sugerencias. Los usuarios pueden filtrar contenido con asistencia de autocompletado.
Búsqueda de Usuarios con Autocompletado
Habilitar autocompletado en formularios de búsqueda de usuarios para sugerir nombres de usuario coincidentes. El módulo incluye una configuración predeterminada para la pestaña de usuarios del Search Form que consulta el callback de View de usuarios.
Integración con API Externa
Crear sugerencias de autocompletado desde APIs externas como Google Places o servicios web personalizados. Configurar el campo source con la URL de la API externa. La API debe devolver JSON en el formato esperado con campos label, value y link opcionales.
Callback Personalizado para Sugerencias Complejas
Construir un controller Drupal personalizado que devuelva sugerencias JSON desde consultas complejas o fuentes de datos agregadas. Especificar la ruta del controller como URL source y devolver datos en el formato esperado.
Sugerencias Agrupadas por Categoría
Usar agrupación de Views para organizar sugerencias por tipo de contenido, término de taxonomía u otros criterios. El plugin de style soporta agrupación con separación visual entre grupos en el desplegable.
Múltiples Campos de Autocompletado en Una Página
Configurar múltiples configuraciones de autocompletado con diferentes selectores CSS para habilitar autocompletado en múltiples campos simultáneamente. Cada uno puede tener su propia fuente, tema y ajustes de comportamiento.
Tips
- Usar la herramienta de ayuda para administradores para identificar fácilmente selectores CSS pasando sobre campos de entrada
- Crear temas CSS personalizados copiando un archivo existente en css/themes/ y modificándolo
- Usar el token [search-phrase] en mensajes de sin-resultado y más-resultados para mostrar a los usuarios qué buscaron
- Establecer caracteres mínimos en 2-3 para reducir la carga del servidor mientras se proporcionan sugerencias útiles
- Usar agrupación de View para categorizar sugerencias visualmente (ej., por tipo de contenido)
- Para autocompletado de filtro expuesto, el identificador del filtro expuesto de la View se pasa automáticamente al callback
- Probar el comportamiento del autocompletado en la vista previa de View - la salida JSON está formateada para legibilidad
Technical Details
Admin Pages 4
/admin/config/search/search_autocomplete
Página principal de administración que muestra una lista de todas las configuraciones de autocompletado. Permite habilitar/deshabilitar configuraciones individuales y alternar la herramienta de ayuda para administradores. Muestra el nombre de configuración, estado habilitado y selector CSS para cada entrada.
/admin/config/search/search_autocomplete/add
Formulario para crear una nueva configuración de autocompletado. Requiere un nombre legible por humanos, nombre de máquina y selector CSS para el campo de entrada objetivo.
/admin/config/search/search_autocomplete/manage/{autocompletion_configuration}
Formulario completo para configurar todos los aspectos de una configuración de autocompletado incluyendo comportamiento de visualización, fuente de datos y tema.
/admin/config/search/search_autocomplete/manage/{autocompletion_configuration}/delete
Formulario de confirmación para eliminar una configuración de autocompletado. Algunas configuraciones predeterminadas pueden tener la eliminación deshabilitada.
Permissions 2
Hooks 5
hook_element_info_alter
Modifica elementos de formulario para añadir procesamiento de autocompletado personalizado. Identifica elementos con processAutocomplete y añade el manejador process_search_autocomplete.
hook_library_info_build
Crea dinámicamente definiciones de biblioteca para archivos de tema CSS encontrados en el directorio css/themes.
hook_library_info_alter
Modifica la biblioteca core/drupal.autocomplete para inyectar JavaScript personalizado y añadir dependencia de DOMPurify si está disponible.
hook_page_attachments
Adjunta configuraciones de autocompletado a las páginas. Carga ajustes para todas las configuraciones habilitadas con selectores CSS y adjunta la biblioteca de ayuda para administradores si está habilitada.
hook_form_alter
Aplica configuraciones de autocompletado predeterminadas a formularios de búsqueda de Drupal core (search_block_form y search_form).
Troubleshooting 5
Verificar que el selector CSS es correcto usando las herramientas de desarrollador del navegador. Asegurar que el usuario tiene el permiso 'use search autocomplete'. Limpiar todas las cachés después de cambios de configuración. Comprobar que la configuración está habilitada.
Descargar DOMPurify desde https://github.com/cure53/DOMPurify y colocarlo en libraries/dompurify/ para que exista la ruta libraries/dompurify/dist/purify.min.js. Alternativamente, configurar Composer para descargarlo automáticamente.
Revisar la consola del navegador para errores de JavaScript. Verificar que la URL source o el display de View existe y es accesible. Asegurar que la View tiene un display de Autocompletion Callback configurado correctamente.
Habilitar la casilla de herramienta de ayuda para administradores en la página principal de configuración. Asegurar que tienes el permiso 'administer search autocomplete'. La herramienta solo aparece en campos de entrada de texto y búsqueda.
Algunas configuraciones predeterminadas tienen el indicador editable o deletable establecido en FALSE para protección. Estos ajustes se almacenan en config y no pueden cambiarse a través de la interfaz.
Security Notes 5
- El módulo requiere la biblioteca DOMPurify para protección XSS - no usar sin ella
- La salida de sugerencias se sanitiza a través de DOMPurify antes de renderizar en el desplegable
- El permiso 'use search autocomplete' controla qué usuarios ven la funcionalidad de autocompletado
- Las URLs de callback externas deben verificarse cuidadosamente para prevenir exposición de datos
- Las entidades de configuración tienen indicadores editable/deletable para prevenir modificación accidental de configuraciones críticas