@cgdd-bun/dido-widgets v2.0.3
DiDo Wigets as Custom Elements Library
This project is a library of web components. This web components are widgets for interaction with the DiDo API.
Actually there are 10 web components in the library:
- a web component for displaying a "dataset" detail
- a web component for displaying a "dataset" card
- a web component for displaying a "datafile" detail
- a web component for displaying a "datafile" card
- a web component for displaying a "millesime" detail
- a web component for downloading data from api
- a web component for displaying a pagination for datasets or datafiles resources (with infinite scroll)
- a web component for displaying an explore page (pagination with ui filter)
- a web component for displaying global apidoc
- a web component for displaying a full catalog
Usage of the library
The library is developped with Vue3. But for optimization Vue is not included in the library and must be loaded before.
The library expose a function for registering each web component with a custom tag. If you don't specify a custom tag, the default tag for the component will be used;
Example of usage of web component dataset:
<!-- Loading of Vue3 -->
<script src="https://unpkg.com/vue@3.2.37/dist/vue.global.prod.js"></script>
<!-- Loading of DiDo Library -->
<script src="https://unpkg.com/@cgdd-bun/dido-widgets/dist/dido-widgets.umd.js"></script>
<!-- Registering dido dataset custom element as my-custom-tag web component -->
<script>
DidoWidgets.register("dataset", "my-custom-tag");
</script>
<!-- Web component will be here in shadow dom -->
<my-custom-tag
dido-url="http://api.diffusion.dido.fr/v1"
dido-dataset-id="61d4612eb90992002e39724f"
/>
Interaction with library
Each web component get props for initializing. Ex: url of api and dataset id for the web component "dataset".
Each web component emit events. You can attach listener to these events
Ex: attaching an event listener to event 'datafile-selection' of web component "dataset":
// get webcomponent
const comp = document.querySelector("dido-dataset");
// attach listener to event 'datafile-selection'
comp.addEventListener("datafile-selection", (event) =>
console.log(
"click on card of datafile " +
event.detail[0].datafileRid +
" of dataset " +
event.detail[0].datasetId,
),
);
Dataset web component
- Default tag for registration:
dido-dataset
- Props:
dido-url
:- url of DiDo api
- required
dido-dataset-id
:- id of Dataset
- required
- Events emitted
widget-mounted
:- emitted when widget is mounted
- event.detail0:
{ type }
bad-configuration
:- emitted when a required prop is not set
- event.detail0: empty
widget-unmounted
:- emitted when widget is mounted
- event.detail0:
{ type }
dataset-retrieved
:- emitted when the dataset is retrieved with api
- event.detail0:
{ datasetId }
dataset-not-retrieved
:- emitted when the dataset is unavailable
- event.detail0:
{ datasetId }
label-selection
:- emitted when a label is clicked
- event.detail0:
{ type, value }
datafile-selection
:- emitted when a datafile in the dataset is clicked
- event.detail0:
{ datasetId, datafileRid }
Dataset Card web component
- Default tag for registration:
dido-dataset-card
- Props:
dido-url
:- url of DiDo api
- required
dido-dataset-id
:- id of Dataset
- required
- Events emitted
widget-mounted
:- emitted when widget is mounted
- event.detail0:
{ type }
bad-configuration
:- emitted when a required prop is not set
- event.detail0: empty
widget-unmounted
:- emitted when widget is mounted
- event.detail0:
{ type }
dataset-retrieved
:- emitted when the dataset is retrieved with api
- event.detail0:
{ datasetId }
dataset-not-retrieved
:- emitted when the dataset is unavailable
- event.detail0:
{ datasetId }
label-selection
:- emitted when a label is clicked
- event.detail0:
{ type, value }
click-card
:- emitted when dataset card is clicked
- event.detail0:
{ datasetId }
Datafile web component
- Default tag for registration:
dido-datafile
Props:
dido-url
:- url of DiDo api
- required
dido-datafile-rid
:- rid of Datafile
- required
dido-datafile-millesime
:- millesime of datafile preselected
- not required (if not set the last millesime is preselected)
dido-initial-filter
:- initial filter in the table of data of selected millesime
not required, if set, format of json string:
{ "orderBy": "-COLUMN1", "columns": "COLUMN1,COLUMN3,COLUMN4", "COLUMN1": { "type": "neq", "value": "valeur1" }, "COLUMN4": { "type": "withinCogZones", "value": "dpt:63@2020" } }
Events emitted
widget-mounted
:- emitted when widget is mounted
- event.detail0:
{ type }
bad-configuration
:- emitted when a required prop is not set
- event.detail0: empty
widget-unmounted
:- emitted when widget is mounted
- event.detail0:
{ type }
datafile-retrieved
:- emitted when the datafile is retrieved with api
- event.detail0:
{ datafileRid }
datafile-not-retrieved
:- emitted when the datafile is unavailable
- event.detail0:
{ datafileRid }
label-selection
:- emitted when a label is clicked
- event.detail0:
{ type, value }
dataset-selection
:- emitted when the dataset of the datefile is clicked
- event.detail0:
{ datasetId }
millesime-selection
:- emitted when a millesime in the datefile is clicked
- event.detail0:
{ datafileRid, datafileMillesime }
Datafile Card web component
- Default tag for registration:
dido-datafile-card
- Props:
dido-url
:- url of DiDo api
- required
dido-datafile-rid
:- rid of Datafile
- required
- Events emitted
widget-mounted
:- emitted when widget is mounted
- event.detail0:
{ type }
widget-unmounted
:- emitted when widget is mounted
- event.detail0:
{ type }
bad-configuration
:- emitted when a required prop is not set
- event.detail0: empty
datafile-retrieved
:- emitted when the datafile is retrieved with api
- event.detail0:
{ datafileRid }
datafile-not-retrieved
:- emitted when the datafile is unavailable
- event.detail0:
{ datafileRid }
label-selection
:- emitted when a label is clicked
- event.detail0:
{ type, value }
click-card
:- emitted when datafile card is clicked
- event.detail0:
{ datafileRid }
Millesime web component
- Default tag for registration:
dido-millesime
Props:
dido-url
:- url of DiDo api
- required
dido-datafile-rid
:- rid of Datafile of millesime
- required
dido-datafile-millesime
:- millesime
- required
dido-initial-filter
:- initial filter in the table of data
not required, if set, format of json string:
{ "orderBy": "-COLUMN1", "columns": "COLUMN1,COLUMN3,COLUMN4", "COLUMN1": { "type": "neq", "value": "valeur1" }, "COLUMN4": { "type": "withinCogZones", "value": "dpt:63@2020" } }
Events emitted
widget-mounted
:- emitted when widget is mounted
- event.detail0:
{ type }
widget-unmounted
:- emitted when widget is mounted
- event.detail0:
{ type }
bad-configuration
:- emitted when a required prop is not set
- event.detail0: empty
millesime-retrieved
:- emitted when the millesime is retrieved with api
- event.detail0:
{ datafileRid, datafileMillesime }
millesime-not-retrieved
:- emitted when the millesime is unavailable
- event.detail0:
{ datafileRid, datafileMillesime }
Download web component
- Default tag for registration:
dido-download
- Props:
dido-url
:- url of DiDo api
- required
dido-widget-type
- level of widget (available values are dataset, datafile and millesime)
- required
dido-dataset-id
:- id of Dataset
- required if dido-widget-type is
dataset
dido-datafile-rid
:- id of Datafile
- required if dido-widget-type is
datafile
ormillesime
dido-datafile-millesime
:- millesime of datafile preselected
- required if dido-widget-type is
millesime
- Events emitted
widget-mounted
:- emitted when widget is mounted
- event.detail0:
{ type }
widget-unmounted
:- emitted when widget is mounted
- event.detail0:
{ type }
bad-configuration
:- emitted when a required prop is not set
- event.detail0: empty
widget-type-unknown
:- emitted when dido-widget-type is not valid
- event.detail0:
{ datasetId }
dataset-retrieved
:- emitted when dido-widget-type is
dataset
and the dataset is retrieved with api - event.detail0:
{ datasetId }
- emitted when dido-widget-type is
dataset-not-retrieved
:- emitted when dido-widget-type is
dataset
and the dataset is unavailable - event.detail0:
{ datasetId }
- emitted when dido-widget-type is
datafile-retrieved
:- emitted when dido-widget-type is
datafile
and the datafile is retrieved with api - event.detail0:
{ datafileRid }
- emitted when dido-widget-type is
datafile-not-retrieved
:- emitted when dido-widget-type is
datafile
and the datafile is unavailable - event.detail0:
{ datafileRid }
- emitted when dido-widget-type is
millesime-retrieved
:- emitted when dido-widget-type is
millesime
and the millesime is retrieved with api - event.detail0:
{ datafileRid, datafileMillesime }
- emitted when dido-widget-type is
millesime-not-retrieved
:- eemitted when dido-widget-type is
millesime
and the millesime is unavailable - event.detail0:
{ widgetType }
- eemitted when dido-widget-type is
Pagination web component
- Default tag for registration:
dido-pagination
Props:
dido-url
:- url of DiDo api
- required
dido-filter
:- filter used for pagination
- required (you can pass {} for default value)
default value:
{ "itemsType": "dataset", "order": { "field": "last_modified", "sort": "desc" }, "text": "", "lastModified": { "max": "", "min": "" }, "temporalCoverage": { "from": "", "to": "" }, "topics": [], "tags": [], "licenses": [], "zones": [], "granularities": [], "frequencies": [] }
Events emitted
widget-mounted
:- emitted when widget is mounted
- event.detail0:
{ type }
bad-configuration
:- emitted when a required prop is not set
- event.detail0: empty
widget-unmounted
:- emitted when widget is mounted
- event.detail0:
{ type }
click-card
:- emitted when a card id clicked
- event.detail0:
{ type, datasetId, datafileRid }
label-selection-on-card
:- emitted when a label in a card is clicked
- event.detail0:
{ card, type, value }
init
:- emitted when a pagination with new filter is initialized
event.detail0:
{ itemsType, order: { field, sort }, text, lastModified: { min, max }, temporalCoverage: { from, to }, topics, tags, frequencies, zones, granularities, licenses }
Explore web component
- Default tag for registration:
dido-explore
Props:
dido-url
:- url of DiDo api
- required
dido-filter
:- filter used for explore
- required (you can pass {} for default value)
default value:
{ "itemsType": "dataset", "order": { "field": "last_modified", "sort": "desc" }, "text": "", "lastModified": { "max": "", "min": "" }, "temporalCoverage": { "from": "", "to": "" }, "topics": [], "tags": [], "licenses": [], "zones": [], "granularities": [], "frequencies": [] }
Events emitted
widget-mounted
:- emitted when widget is mounted
- event.detail0:
{ type }
bad-configuration
:- emitted when a required prop is not set
- event.detail0: empty
widget-unmounted
:- emitted when widget is mounted
- event.detail0:
{ type }
click-card
:- emitted when a card id clicked
- event.detail0:
{ type, datasetId, datafileRid }
label-selection-on-card
:- emitted when a label in a card is clicked
- event.detail0:
{ card, type, value }
new-filter
:- emitted when a new filter is activated
event.detail0:
{ itemsType, order: { field, sort }, text, lastModified: { min, max }, temporalCoverage: { from, to }, topics, tags, frequencies, zones, granularities, licenses }
Global apidoc web component
- Default tag for registration:
dido-apidoc
- Props:
dido-url
:- url of DiDo api
- required
- Events emitted
Catalog web component
- Default tag for registration:
dido-catalog
Props:
dido-url
:- url of DiDo api
- required
dido-catalog-contact-url
:- url for contact point
- not required (default: https://statistiques.developpement-durable.gouv.fr/contact)
dido-linked-docs-url
:- url for linked docs from external api
schema for external api:
[ { "nid": "5825", // the external id "type_dido": "dataset", "datasetid": "631b03afb61e5c6479370169", "datafileRid": "", "datafileMillesime": "", "created": "2023-05-05", "content_title": "Donn\u00e9es mensuelles de l\u0026#039;\u00e9nergie", // Url encoded "content_summary": "Principales donn\u00e9es mensuelles.......", // Url encoded "content_link": "https://www.statistiques.developpement-durable.gouv.fr/donnees-mensuelles-de-lenergie" // Url encoded } ]
not required (if not set linked docs functionnality is disabled)
dido-initial-explore-url:
- not required
- used for setting an initial filter in explore page when first loading and querystring in url is empty
format of string example:
type=datafile&pagination=1&sortField=title&sortOrder=desc&topics=Environnement&tags=territoire,indicateur&licenses=fr-lo&zones=country:fr&granularities=fr:commune&frequencies=annual
Events emitted
3 months ago
5 months ago
7 months ago
1 year ago
1 year ago
1 year ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago