External Data Source
Proporciona un tipo de campo que obtiene datos de APIs externas y muestra los datos como opciones de campo utilizando menús desplegables, casillas de verificación o widgets de autocompletado.
external_data_source
Instalar
composer require 'drupal/external_data_source:^3.2'
composer require 'drupal/external_data_source:^3.1'
Overview
External Data Source es un módulo orientado a desarrolladores que conecta APIs externas con el sistema de campos de Drupal. Proporciona un tipo de campo personalizado que puede poblar sus opciones dinámicamente desde cualquier fuente de datos externa, como APIs REST o servicios web.
El módulo utiliza una arquitectura basada en plugins donde los desarrolladores pueden crear plugins ExternalDataSource para obtener datos de cualquier API externa. Estos plugins manejan la obtención y formateo de datos, mientras que el módulo proporciona widgets de campo listos para usar (menú desplegable, casillas de verificación y autocompletado) que muestran los datos obtenidos como opciones seleccionables.
El módulo incluye tres plugins de ejemplo que demuestran cómo integrarse con APIs externas: un plugin de Countries que utiliza la API RestCountries, y plugins de France Zip Codes y France Regions que utilizan la API geográfica del gobierno francés.
Features
- Tipo de campo personalizado que almacena valores obtenidos de APIs externas
- Widget de selección para mostrar opciones en formato desplegable
- Widget de casillas de verificación para mostrar opciones como checkboxes o botones de radio
- Widget de autocompletado con sugerencias potenciadas por AJAX desde APIs externas
- Arquitectura basada en plugins que permite a los desarrolladores añadir fácilmente nuevas fuentes de datos
- Plugins de ejemplo incluidos para Countries, France Zip Codes y France Regions
- Cantidad máxima configurable de resultados para respuestas de API
- Soporte para múltiples valores a través de todos los widgets
Use Cases
Campo de Selección de País
Crea un campo donde los usuarios pueden seleccionar un país de una lista obtenida dinámicamente. Usando el plugin Countries incluido, el campo obtendrá automáticamente la lista de países más reciente desde la API RestCountries y la presentará como un menú desplegable, casillas de verificación o campo de autocompletado.
Campos de Ubicación Geográfica
Construye formularios que requieren datos geográficos franceses como códigos postales o regiones. Los plugins FranceZipCodes y FranceRegions incluidos demuestran la integración con la API geográfica del gobierno francés para datos geográficos precisos y actualizados.
Integración de API Personalizada
Desarrolla un plugin ExternalDataSource personalizado para obtener categorías de productos, listas de usuarios, artículos de inventario o cualquier otro dato de las APIs REST de tu organización. La arquitectura de plugins facilita añadir nuevas fuentes de datos sin modificar el código central del módulo.
Opciones de Formulario Dinámicas
Reemplaza listas de selección estáticas con opciones dinámicas que se actualizan automáticamente cuando los datos de origen cambian. Esto es particularmente útil para datos que cambian frecuentemente, como tasas de cambio de divisas, disponibilidad de stock o niveles de precios en tiempo real.
Tips
- Crea plugins ExternalDataSource personalizados extendiendo ExternalDataSourceBase e implementando el método getResponse()
- El método getResponse() debe devolver un array de objetos con claves 'value' y 'label'
- Usa la propiedad $this->q en tu plugin para acceder a la consulta de búsqueda del autocompletado
- Para conjuntos de datos grandes, usa el widget de autocompletado que consulta la API mientras los usuarios escriben, en lugar de cargar todas las opciones por adelantado
- La configuración de almacenamiento del campo (ws, count, max_length) no puede cambiarse después de que se hayan introducido datos
- Considera implementar caché en tus plugins personalizados para reducir las llamadas a la API y mejorar el rendimiento
Technical Details
Troubleshooting 4
Asegúrate de tener al menos un plugin ExternalDataSource disponible. El módulo incluye plugins de ejemplo (Countries, FranceZipCodes, FranceRegions). Si estás creando plugins personalizados, verifica que la anotación del plugin sea correcta y limpia la caché de Drupal.
Verifica que la API externa sea accesible desde tu servidor. Comprueba que el método setRequest() del plugin reciba correctamente el objeto de solicitud y que el método getResponse() maneje el parámetro de consulta 'q' para filtrar.
Esto ocurre cuando el plugin configurado ha sido eliminado o renombrado. Edita los ajustes de almacenamiento del campo y selecciona un plugin disponible del menú desplegable.
El módulo incluye conversión UTF8Utils para sanear datos. Si los problemas persisten, asegúrate de que el método formatResponse() de tu plugin personalizado maneje correctamente la codificación de caracteres.
Security Notes 4
- El endpoint de autocompletado del módulo requiere el permiso 'access content', limitando el acceso a usuarios autenticados o con permisos
- Las llamadas a APIs externas se realizan del lado del servidor, evitando la exposición de endpoints de API a los usuarios finales
- Los valores de entrada tienen escape HTML en el formateador para prevenir ataques XSS
- Considera las implicaciones de seguridad de las APIs externas con las que te integras, especialmente en relación con la privacidad de datos y autenticación