Composant invisible de connexion aux donnees. Recupere des donnees depuis une API REST (URL brute ou via un adapter specialise) et les distribue aux autres composants via le systeme d'evenements. Supporte aussi les donnees JSON inline.
Invisible : Ce composant ne rend rien visuellement. Il agit comme un "pont" entre votre API et les composants de visualisation.
dsfr-data-source se connecte a une API, recupere les donnees et les
redistribue. En mode adapter, il gere la pagination automatique, les filtres server-side
et la pagination pilotable (server-side).
dsfr-data-query est une couche de transformation client-side : il filtre, groupe,
agrege et trie les donnees. Il ecoute un dsfr-data-source via l'attribut
source et traite les donnees cote client.
Pattern recommande : <dsfr-data-source api-type="..."> +
<dsfr-data-query source="..."> pour combiner fetch serveur et
transformation client.
Le composant supporte trois modes :
| Mode | Description |
|---|---|
| URL brute | Appel HTTP generique via l'attribut url. Supporte GET/POST, headers,
params JSON, extraction via transform et pagination manuelle via paginate. |
| Adapter | Active via api-type (sans url). L'adapter gere la construction d'URL,
la pagination automatique, les filtres et le parsing specifiques au provider
(OpenDataSoft, Tabular, Grist). |
| Inline data | Donnees JSON passees directement via l'attribut data. Pas de fetch HTTP. |
En mode adapter, l'attribut api-type selectionne le provider :
| api-type | API | Identifiant requis | Pagination | Max records |
|---|---|---|---|---|
opendatasoft |
OpenDataSoft (v2.1) | dataset-id |
offset, 100/page, max 10 pages | 1 000 |
tabular |
Tabular API (data.gouv.fr) | resource |
page, 50/page, max 500 pages | 25 000 |
grist |
Grist (numerique.gouv.fr, getgrist.com) | base-url |
offset, 100/page, illimitee | Illimite |
| Attribut | Type | Format / Valeurs | Description |
|---|---|---|---|
id | String | id="ma-source" | Identifiant unique (requis). Les composants en aval l'utilisent pour s'abonner aux donnees. |
refresh | Number | Entier en secondes. 0 = off | Intervalle de rafraichissement automatique |
transform | String | "results", "data.items" | Chemin JSON pour extraire les donnees de la reponse API |
headers | String | '{"apikey":"abc123"}' | Headers HTTP en JSON (API key, Bearer token, etc.) |
cache-ttl | Number | Entier en secondes. Defaut : 3600 | Duree de cache serveur en mode DB (0 = pas de cache) |
| Attribut | Type | Format / Valeurs | Description |
|---|---|---|---|
url | String | URL relative ou absolue | URL de l'API REST a appeler |
method | String | GET | POST | Methode HTTP. Defaut : GET |
params | String | '{"limit": 100}' | GET : ajoutes a l'URL comme query params. POST : envoyes comme body JSON. |
paginate | Boolean | Presence = true | Active la pagination manuelle. Injecte page et page_size dans l'URL.
Auto-extrait json.data si aucun transform n'est defini. |
page-size | Number | Entier positif. Defaut : 20 | Taille de page pour la pagination manuelle |
use-proxy | Boolean | Presence = true | Force le passage par le proxy CORS generique (/cors-proxy).
Utile pour les APIs externes qui ne gerent pas CORS. La requete est routee cote serveur
via un header X-Target-URL. |
| Attribut | Type | Format / Valeurs | Description |
|---|---|---|---|
api-type | String | opendatasoft | tabular | grist | Type de provider. Active le mode adapter (ne pas combiner avec url). |
base-url | String | "https://data.iledefrance.fr" | URL de base de l'API. Requis pour Grist, optionnel pour ODS/Tabular (defauts fournis). |
dataset-id | String | "mon-dataset-2024" | Identifiant (slug) du dataset. Mode opendatasoft uniquement. |
resource | String | "2876a346-d50c-..." (UUID) | Identifiant de la ressource. Mode tabular uniquement. |
where | String | Colon : "champ:op:val"ODS : ODSQL libre | Clause WHERE statique. Format depend du provider (voir section Filtres). |
select | String | "sum(pop) as total, region" | Clause SELECT en syntaxe ODSQL. Mode opendatasoft uniquement. |
group-by | String | "champ1, champ2" | Champs de regroupement. Delegue au serveur si le provider le supporte. |
aggregate | String | "champ:fn" ou "champ:fn:alias" | Agregations server-side. Fonctions : count sum avg min max. |
order-by | String | "champ:asc" ou "champ:desc" | Tri des resultats. Peut etre surcharge dynamiquement par un dsfr-data-list. |
limit | Number | Entier positif. 0 = illimite | Nombre maximum de resultats |
server-side | Boolean | Presence = true | Mode pagination pilotable : charge une page a la fois, ecoute les commandes
des composants en aval (dsfr-data-list, dsfr-data-facets, dsfr-data-search). |
| Attribut | Type | Format / Valeurs | Description |
|---|---|---|---|
data | String | JSON valide (tableau ou objet) | Donnees inline. Pas de fetch HTTP, les donnees sont parsees et emises directement. |
L'attribut where definit un filtre permanent sur la source.
En mode Tabular / Grist, format colon champ:operateur:valeur :
where="population:gt:5000" where="population:gt:5000, region:in:IDF|OCC|BRE" where="email:isnull"
En mode OpenDataSoft, syntaxe ODSQL libre :
where="population > 5000 AND status = 'active'"
Les composants en aval (dsfr-data-facets, dsfr-data-search) peuvent ajouter
des filtres dynamiques via le systeme de commandes. Ces filtres sont fusionnes
avec le where statique a chaque requete.
Chaque composant envoie un overlay identifie par une cle unique (whereKey).
Les overlays sont combines en ET logique. La methode getEffectiveWhere()
retourne la clause WHERE fusionnee.
<!-- WHERE statique + overlays dynamiques des facettes et recherche --> <dsfr-data-source id="src" api-type="opendatasoft" dataset-id="rappelconso-v2-gtin-trie" base-url="https://data.economie.gouv.fr" where="categorie_produit = 'Alimentation'" server-side page-size="20"> </dsfr-data-source> <!-- La recherche ajoute un overlay WHERE via server-search --> <dsfr-data-search id="search" source="src" server-search> </dsfr-data-search> <!-- Les facettes ajoutent des overlays WHERE --> <dsfr-data-facets id="facets" source="src" fields="categorie_produit, marque_produit" server-facets> </dsfr-data-facets>
Avec server-side, dsfr-data-source charge une seule page
a la fois et ecoute les commandes des composants en aval pour naviguer entre les pages.
Cela permet d'afficher des datasets de milliers d'enregistrements sans tout charger en memoire.
Le composant reagit a trois types de commandes :
| Commande | Source | Effet |
|---|---|---|
{ page } | dsfr-data-list | Change la page courante et re-fetche |
{ where, whereKey } | dsfr-data-facets, dsfr-data-search | Ajoute/supprime un overlay WHERE et reset a la page 1 |
{ orderBy } | dsfr-data-list | Change le tri et re-fetche |
<dsfr-data-source id="prix-ct" url="https://data.economie.gouv.fr/api/explore/v2.1/catalog/datasets/prix-controle-technique/records" transform="results" ></dsfr-data-source>
<dsfr-data-source
id="api-privee"
url="https://mon-api.gouv.fr/data"
method="POST"
headers='{"Authorization": "Bearer TOKEN"}'
params='{"limit": 100, "filters": {"annee": 2024}}'
transform="data.items"
refresh="60"
></dsfr-data-source>
Avec paginate, chaque changement de page dans un dsfr-data-list
en aval declenche un nouvel appel API avec les parametres de pagination.
<dsfr-data-source id="browse" api-type="opendatasoft" dataset-id="rappelconso-v2-gtin-trie" base-url="https://data.economie.gouv.fr" server-side paginate page-size="20" ></dsfr-data-source> <dsfr-data-list source="browse" colonnes="modeles_ou_references:Produit, categorie_produit:Categorie, marque_produit:Marque" pagination="20"> </dsfr-data-list>
Auto-extraction : en mode paginate, pas besoin de transform="data".
Les donnees sont automatiquement extraites depuis json.data et les metadonnees de pagination
(json.meta) sont stockees pour calculer le nombre total de pages.
L'attribut use-proxy force le passage par le proxy CORS generique.
Utile quand l'API cible ne renvoie pas les headers CORS necessaires.
<dsfr-data-source id="ghibli-films" url="https://ghibliapi.vercel.app/films" use-proxy ></dsfr-data-source>
Fonctionnement : en dev, la requete est routee via le middleware Vite
/cors-proxy. En production, elle passe par l'endpoint equivalent sur le serveur proxy
(<votre-proxy>/cors-proxy).
L'URL cible est transmise dans le header X-Target-URL.
L'adapter gere automatiquement la construction d'URL, la pagination et le parsing. Pagination automatique (toutes les pages en une seule requete) jusqu'a 1 000 records.
<dsfr-data-source id="elus" api-type="opendatasoft" base-url="https://data.iledefrance.fr" dataset-id="elus-regionaux" where="sexe = 'F'" ></dsfr-data-source> <dsfr-data-query id="stats" source="elus" group-by="groupe_politique" aggregate="nom:count:nb" order-by="nb:desc"> </dsfr-data-query> <dsfr-data-chart source="stats" type="bar" label-field="groupe_politique" value-field="nb"> </dsfr-data-chart>
L'adapter ODS gere la pagination, le tri serveur, la recherche full-text et les facettes. Ici un simple datalist pagine.
<dsfr-data-source id="src-ods" api-type="opendatasoft" dataset-id="rappelconso-v2-gtin-trie" base-url="https://data.economie.gouv.fr" server-side page-size="20" ></dsfr-data-source> <dsfr-data-list source="src-ods" colonnes="modeles_ou_references:Produit, categorie_produit:Categorie, marque_produit:Marque, date_publication:Date" server-tri pagination="20"> </dsfr-data-list>
L'adapter Grist se connecte aux instances Grist (numerique.gouv.fr ou getgrist.com). Il detecte automatiquement si la requete necessite le mode SQL (groupement, agregation, operateurs avances) ou le mode Records standard.
<dsfr-data-source
id="grist-data"
api-type="grist"
base-url="https://grist.numerique.gouv.fr/api/docs/DOC_ID/tables/TABLE_ID/records"
headers='{"Authorization": "Bearer TOKEN"}'
></dsfr-data-source>
<dsfr-data-normalize id="clean" source="grist-data" flatten>
</dsfr-data-normalize>
<dsfr-data-chart source="clean" type="bar"
label-field="nom" value-field="valeur">
</dsfr-data-chart>
Flatten requis : Grist retourne les champs imbriques dans un objet fields.
Utilisez <dsfr-data-normalize flatten> pour aplatir les donnees avant de les exploiter.
Avec server-side, la source charge une page a la fois.
Le dsfr-data-list en aval pilote la navigation entre les pages.
<dsfr-data-source id="srv" api-type="opendatasoft" dataset-id="rappelconso-v2-gtin-trie" base-url="https://data.economie.gouv.fr" server-side page-size="20" ></dsfr-data-source> <dsfr-data-list source="srv" colonnes="modeles_ou_references:Produit, categorie_produit:Categorie, marque_produit:Marque" server-tri pagination="20"> </dsfr-data-list>
L'attribut data permet de passer des donnees JSON directement,
sans aucun appel HTTP. Utile pour les exemples, prototypes ou donnees statiques.
<dsfr-data-source
id="inline"
data='[{"nom":"Paris","pop":2161000},{"nom":"Lyon","pop":516092},{"nom":"Marseille","pop":870731}]'
></dsfr-data-source>
<dsfr-data-chart source="inline" type="bar"
label-field="nom" value-field="pop">
</dsfr-data-chart>
L'attribut refresh re-execute la requete a intervalles reguliers (en secondes).
Fonctionne dans les deux modes (URL brute et adapter).
<dsfr-data-source id="live" api-type="opendatasoft" base-url="https://data.opendatasoft.com" dataset-id="mon-dataset" refresh="30" ></dsfr-data-source>
Le composant emet des evenements personnalises via le systeme data-bridge :
dsfr-data-loaded : Donnees chargees avec succes (detail : tableau de records)dsfr-data-loading : Chargement en coursdsfr-data-error : Erreur de chargement (detail : objet Error)cache-fallback : Les donnees proviennent du cache serveur suite a une erreur API (mode DB uniquement)| Methode | Retour | Description |
|---|---|---|
reload() | void | Force le rechargement des donnees |
getData() | unknown | Retourne les donnees actuelles |
isLoading() | Boolean | Indique si un chargement est en cours |
getError() | Error | null | Retourne l'erreur eventuelle |
getAdapter() | ApiAdapter | null | Retourne l'adapter actif (mode adapter uniquement, null en mode URL brute) |
getEffectiveWhere(excludeKey?) | String | Retourne la clause WHERE fusionnee (statique + tous les overlays dynamiques).
Le parametre excludeKey permet d'exclure un overlay specifique (utilise par les facettes). |
Choisir le bon mode : Utilisez le mode URL brute pour vous connecter a n'importe quelle API REST. Utilisez le mode adapter pour les APIs connues (ODS, Tabular, Grist) afin de beneficier de la pagination automatique, des filtres server-side et de la construction d'URL geree.
server-side vs pagination automatique : Sans server-side, l'adapter
charge toutes les donnees (multi-pages) en une seule operation. Avec server-side,
il charge une seule page et attend les commandes des composants en aval. Utilisez
server-side pour les grands datasets avec un dsfr-data-list pagine.
Pipeline de donnees : dsfr-data-source s'integre dans un pipeline :
dsfr-data-source → dsfr-data-normalize →
dsfr-data-query / dsfr-data-search / dsfr-data-facets →
composants de visualisation.
Securite : les headers et tokens sont visibles dans le code source HTML. Ne les utilisez que pour des cles a acces restreint (lecture seule) ou dans des contextes proteges (intranet, applications internes).