External Data Source
Provides a field type that fetches data from external APIs and displays the data as field options using select dropdowns, checkboxes, or autocomplete widgets.
external_data_source
Install
composer require 'drupal/external_data_source:^3.2'
composer require 'drupal/external_data_source:^3.1'
Overview
External Data Source is a developer-focused module that bridges the gap between external APIs and Drupal's field system. It provides a custom field type that can populate its options dynamically from any external data source, such as REST APIs or web services.
The module uses a plugin-based architecture where developers can create ExternalDataSource plugins to fetch data from any external API. These plugins handle the data retrieval and formatting, while the module provides ready-to-use field widgets (select dropdown, checkboxes, and autocomplete) that display the fetched data as selectable options.
The module comes with three example plugins demonstrating how to integrate with external APIs: a Countries plugin using the RestCountries API, and France Zip Codes and France Regions plugins using the French government's geo API.
Features
- Custom field type that stores values fetched from external APIs
- Select widget for displaying options in a dropdown format
- Checkboxes widget for displaying options as checkboxes or radio buttons
- Autocomplete widget with AJAX-powered suggestions from external APIs
- Plugin-based architecture allowing developers to easily add new data sources
- Built-in example plugins for Countries, France Zip Codes, and France Regions
- Configurable maximum result count for API responses
- Support for multiple values through all widgets
Use Cases
Country Selection Field
Create a field where users can select a country from a dynamically fetched list. Using the built-in Countries plugin, the field will automatically fetch the latest country list from the RestCountries API and present it as a dropdown, checkboxes, or autocomplete field.
Geographic Location Fields
Build forms that require French geographic data such as postal codes or regions. The included FranceZipCodes and FranceRegions plugins demonstrate integration with the French government's geo API for accurate, up-to-date geographic data.
Custom API Integration
Develop a custom ExternalDataSource plugin to fetch product categories, user lists, inventory items, or any other data from your organization's REST APIs. The plugin architecture makes it easy to add new data sources without modifying core module code.
Dynamic Form Options
Replace static select lists with dynamic options that automatically update when the source data changes. This is particularly useful for data that changes frequently, such as currency exchange rates, stock availability, or real-time pricing tiers.
Tips
- Create custom ExternalDataSource plugins by extending ExternalDataSourceBase and implementing the getResponse() method
- The getResponse() method should return an array of objects with 'value' and 'label' keys
- Use the $this->q property in your plugin to access the autocomplete search query
- For large datasets, use the autocomplete widget which queries the API as users type, rather than loading all options upfront
- The field storage settings (ws, count, max_length) cannot be changed after data has been entered
- Consider implementing caching in your custom plugins to reduce API calls and improve performance
Technical Details
Troubleshooting 4
Ensure you have at least one ExternalDataSource plugin available. The module includes example plugins (Countries, FranceZipCodes, FranceRegions). If creating custom plugins, verify the plugin annotation is correct and clear the Drupal cache.
Check that the external API is accessible from your server. Verify the plugin's setRequest() method properly receives the request object and the getResponse() method handles the 'q' query parameter for filtering.
This occurs when the configured plugin has been removed or renamed. Edit the field storage settings and select an available plugin from the dropdown.
The module includes UTF8Utils conversion for sanitizing data. If issues persist, ensure your custom plugin's formatResponse() method properly handles character encoding.
Security Notes 4
- The module's autocomplete endpoint requires 'access content' permission, limiting access to authenticated or permitted users
- External API calls are made server-side, preventing exposure of API endpoints to end users
- Input values are HTML-escaped in the formatter to prevent XSS attacks
- Consider the security implications of the external APIs you integrate with, especially regarding data privacy and authentication