@cgdd-bun/dido-widgets

v2.2.3

Published

4 months ago

Widgets Library for DiDo Api as Web Components

0High
0Medium
0Low

charloup

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/[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. 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.detail[0]: { type }
- bad-configuration:
  - emitted when a required prop is not set
  - event.detail[0]: empty
- 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 }
- bad-configuration:
  - emitted when a required prop is not set
  - event.detail[0]: empty
- 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)
- 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.detail[0]: { type }
- bad-configuration:
  - emitted when a required prop is not set
  - event.detail[0]: empty
- 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 }
- bad-configuration:
  - emitted when a required prop is not set
  - event.detail[0]: empty
- 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
- 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.detail[0]: { type }
- widget-unmounted:
  - emitted when widget is mounted
  - event.detail[0]: { type }
- bad-configuration:
  - emitted when a required prop is not set
  - event.detail[0]: empty
- 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 }
- bad-configuration:
  - emitted when a required prop is not set
  - event.detail[0]: empty
- 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 datafile and 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 (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.detail[0]: { type }
- bad-configuration:
  - emitted when a required prop is not set
  - event.detail[0]: empty
- 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 }
- init:
  - emitted when a pagination with new filter is initialized
  - event.detail[0]:
```
{
  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.detail[0]: { type }
- bad-configuration:
  - emitted when a required prop is not set
  - event.detail[0]: empty
- 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
}
```

Global apidoc web component

Default tag for registration: dido-apidoc
Props:
- dido-url:
  - url of DiDo api
  - required
Events emitted
- widget-mounted:
  - emitted when widget is mounted
  - event.detail[0]: { type }
- bad-configuration:
  - emitted when a required prop is not set
  - event.detail[0]: empty
- widget-unmounted:
  - emitted when widget is mounted
  - event.detail[0]: { type }

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:
```
[
  {
    // the external id
    "nid": "5825",
    "type_dido": "dataset",
    "datasetid": "631b03afb61e5c6479370169",
    "datafileRid": "",
    "datafileMillesime": "",
    "created": "2023-05-05",
    // Url encoded
    "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"
  }
]
```
  - 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
- dido-message-service:
  - not required
  - default value is false
  - used to activate the message service
- dido-message-service-type:
  - not required
  - default value is primary
  - possible values are all Quasar colors
  - used for the color of the message service (used only if dido-message-service is true)
- dido-message-service-content:
  - not required
  - default value is 'Un message de service'
  - used for the content of the service message
- dido-message-service-permanent
  - not required
  - default value is false
  - used to set the service message as permanent or dismissible
Events emitted
- widget-mounted:
  - emitted when widget is mounted
  - event.detail[0]: { type }
- bad-configuration:
  - emitted when a required prop is not set
  - event.detail[0]: empty
- widget-unmounted:
  - emitted when widget is mounted
  - event.detail[0]: { type }

Scopes:

didoMessageServiceContent:

slot used for rich-text in service message.
supercharge attribute dido-message-service-content

examples:

a simple positive permanent message:

<dido-catalog
  dido-url="{your_dido_url_api}"
  dido-message-service
  dido-message-service-type="positive"
  dido-message-service-content="un simple message de service dans l'attribut dido-message-service-content de la balise dido-catalog"
  dido-message-service-permanent
></dido-catalog>

a riche negative dismissible message:

<dido-catalog
  dido-url="{your_dido_url_api}"
  dido-message-service
  dido-message-service-type="negative"
>
  <p slot="didoMessageServiceContent">
    <style>
      .text-bold {
        font-weight: bold;
      }
      .text-uppercase {
        text-transform: uppercase;
      }
    </style>
    <span class="text-bold">Le titre du message en gras</span>
    <br /><br />
    On peut mettre tout le texte qui suit en majuscule :
    <span class="text-uppercase"
      >Ceci est un message enrichi qui provient du slot</span
    >
    didoMessageServiceContent
    <span class="text-uppercase">de la balise</span>
    <span class="text-uppercase">dido-catalog</span>
  </p>
</dido-catalog>