DiDo Wigets as Custom Elements Library

This project is a library of web components for interaction with the DiDo API.

Actually there are six 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 with infinite scroll for datasets or datafiles resources
• a web component for displaying an explore page (pagination with ui filter)
• 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/[email protected]/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 (example url of api and dataset id for the web component "dataset").

Each web component emit events. You can attach listener to these events

Example of 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.detail[0]: { type }
  • widget-unmounted:
    • emitted when widget is mounted
    • event.detail[0]: { type }
  • dataset-retrieved:
    • emitted when the dataset is retrieved with api
    • event.detail[0]: { datasetId }
  • dataset-not-retrieved:
    • emitted when the dataset is unavailable
    • event.detail[0]: { datasetId }
  • label-selection:
    • emitted when a label is clicked
    • event.detail[0]: { type, value }
  • datafile-selection:
    • emitted when a datafile in the dataset is clicked
    • event.detail[0]: { 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.detail[0]: { type }
  • widget-unmounted:
    • emitted when widget is mounted
    • event.detail[0]: { type }
  • dataset-retrieved:
    • emitted when the dataset is retrieved with api
    • event.detail[0]: { datasetId }
  • dataset-not-retrieved:
    • emitted when the dataset is unavailable
    • event.detail[0]: { datasetId }
  • label-selection:
    • emitted when a label is clicked
    • event.detail[0]: { type, value }
  • click-card:
    • emitted when dataset card is clicked
    • event.detail[0]: { 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)
• Events emitted
  • widget-mounted:
    • emitted when widget is mounted
    • event.detail[0]: { type }
  • widget-unmounted:
    • emitted when widget is mounted
    • event.detail[0]: { type }
  • datafile-retrieved:
    • emitted when the datafile is retrieved with api
    • event.detail[0]: { datafileRid }
  • datafile-not-retrieved:
    • emitted when the datafile is unavailable
    • event.detail[0]: { datafileRid }
  • label-selection:
    • emitted when a label is clicked
    • event.detail[0]: { type, value }
  • dataset-selection:
    • emitted when the dataset of the datefile is clicked
    • event.detail[0]: { datasetId }
  • millesime-selection:
    • emitted when a millesime in the datefile is clicked
    • event.detail[0]: { 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.detail[0]: { type }
  • widget-unmounted:
    • emitted when widget is mounted
    • event.detail[0]: { type }
  • datafile-retrieved:
    • emitted when the datafile is retrieved with api
    • event.detail[0]: { datafileRid }
  • datafile-not-retrieved:
    • emitted when the datafile is unavailable
    • event.detail[0]: { datafileRid }
  • label-selection:
    • emitted when a label is clicked
    • event.detail[0]: { type, value }
  • click-card:
    • emitted when datafile card is clicked
    • event.detail[0]: { 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
• Events emitted
  • widget-mounted:
    • emitted when widget is mounted
    • event.detail[0]: { type }
  • widget-unmounted:
    • emitted when widget is mounted
    • event.detail[0]: { type }
  • millesime-retrieved:
    • emitted when the millesime is retrieved with api
    • event.detail[0]: { datafileRid, datafileMillesime }
  • millesime-not-retrieved:
    • emitted when the millesime is unavailable
    • event.detail[0]: { 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 or millesime
  • dido-datafile-millesime:
    • millesime of datafile preselected
    • required if dido-widget-type is millesime
• Events emitted
  • widget-mounted:
    • emitted when widget is mounted
    • event.detail[0]: { type }
  • widget-unmounted:
    • emitted when widget is mounted
    • event.detail[0]: { type }
  • widget-type-unknown:
    • emitted when dido-widget-type is not valid
    • event.detail[0]: { datasetId }
  • dataset-retrieved:
    • emitted when dido-widget-type is dataset and the dataset is retrieved with api
    • event.detail[0]: { datasetId }
  • dataset-not-retrieved:
    • emitted when dido-widget-type is dataset and the dataset is unavailable
    • event.detail[0]: { datasetId }
  • datafile-retrieved:
    • emitted when dido-widget-type is datafileand the datafile is retrieved with api
    • event.detail[0]: { datafileRid }
  • datafile-not-retrieved:
    • emitted when dido-widget-type is datafileand the datafile is unavailable
    • event.detail[0]: { datafileRid }
  • millesime-retrieved:
    • emitted when dido-widget-type is millesime and the millesime is retrieved with api
    • event.detail[0]: { datafileRid, datafileMillesime }
  • millesime-not-retrieved:
    • eemitted when dido-widget-type is millesime and the millesime is unavailable
    • event.detail[0]: { widgetType }

Pagination web component

• Default tag for registration: dido-pagination

• Props:

  • dido-url:

    • url of DiDo api
    • required

  • dido-filter:

    • filter used for pagination

    • required

    • example:

      {
        "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.detail[0]: { type }
  • widget-unmounted:
    • emitted when widget is mounted
    • event.detail[0]: { type }
  • click-card:
    • emitted when a card id clicked
    • event.detail[0]: { type, datasetId, datafileRid }
  • label-selection-on-card:
    • emitted when a label in a card is clicked
    • event.detail[0]: { card, type, value }

Explore web component

• Default tag for registration: dido-explore
• Props:
  • dido-url:
    • url of DiDo api
    • required
• Events emitted
  • widget-mounted:
    • emitted when widget is mounted
    • event.detail[0]: { type }
  • widget-unmounted:
    • emitted when widget is mounted
    • event.detail[0]: { type }
  • click-card:
    • emitted when a card id clicked
    • event.detail[0]: { type, datasetId, datafileRid }
  • label-selection-on-card:
    • emitted when a label in a card is clicked
    • event.detail[0]: { card, type, value }
  • new-filter:
    • emitted when a new filter is activated
    • event.detail[0]: { itemsType, order: { field, sort }, text, lastModified: { min, max }, temporalCoverage: { from, to }, topics, tags, frequencies, zones, granularities, licenses }

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)