API Javascript

 

Ce document présente le fonctionnement de l’API javascript fournit par l’intermédiaire du système de design de l’État (DSFR).

 

 

Introduction

L’API javascript ou API JS du DSFR est une surcouche javascript qui fournit un ensemble de méthodes et d’évènement liés aux composants du système de design et permettant d’interagir avec ceux-ci.

Elle est initialisée au chargement du script fourni avec le DSFR dsfr.module.min.js et va instancier les classes javascript nécessaires au fonctionnement de la librairie des composants du DSFR.

Présence de l’api

Lorsque l’API JS est initialisée, l’attribut data-fr-js="true" est ajouté sur le noeud html. Son absence ou la valeur false permettent d’induire le mode no-js pour certains composants.

Configuration de l’API du DSFR

L’API du DSFR est configurable en fonction des besoins et des cadres de développement des projets qui sont amenés à l’utiliser.

Par défaut l”API est initialisée en mode: auto et verbose: false , il est toutefois possible de modifier ces options avant l’appel du script du DSFR.

Exemple de configuration de l’API JS :
1 2 3 4 5 6 7 8 9 10 11 <script> // Options disponibles à l'initialisation du DSFR window.dsfr = { verbose: true, mode: 'manual' }; </script> <!-- Script en version es6 module et nomodule pour les navigateurs le ne supportant pas --> <script type="module" src="js/dsfr.module.min.js"></script> <script type="text/javascript" nomodule src="js/dsfr.nomodule.min.js"></script>

 

Verbose

Le mode ‘verbose’ est une option disponible dans le DSFR qui fournit des détails supplémentaires sur ce que fait le framework JS au démarrage ou lors de la navigation, il produit une sortie détaillée à des fins de diagnostic.

Page d’exemple du composant ‘accordéon' en mode 'verbose’

 

Mode

Le mode sélectionné permet de déterminer le contexte dans lequel doit fonctionner le DSFR et de modifier son comportement sur plusieurs paramètres :

  • son lancement : correspondant à la fonction dsfr.start (voir plus Start/Stop), le lancement du moteur de création d’instances

  • la manipulation du DOM : elle est empêchée dans le cas des frameworks dynamiques.

 

Valeurs possibles :
  • 'auto' (default) : choisi automatiquement le mode le plus approprié,

  • 'manual' : le lancement du moteur est laissé à l’utilisateur via la commande : dsfr.start();

  • ‘runtime' : le lancement se fait immédiatement dès l’initialisation du DSFR,

  • 'loaded': le lancement se fait une fois la page totalement chargée,

  • 'vue' : mode pour Vue.js, implémentation à venir

  • 'angular' : mode pour Angular, implémentation à venir

  • 'react' : mode pour React.js, implémentation à venir

 

NB : Il est possible de modifier ces paramètres via la console du navigateur :

1 2 dsfr.verbose = false; dsfr.mode = 'manual';

Start / Stop

Le système de design fournit une l’API pour arrêter la création d’instances JS et la relancer manuellement :

1 2 dsfr.stop(); dsfr.start();

Debug / Inspecteur

Le système de design fournit une API de déboggage pour loger en console les composantes présentes dans la page :

Tree

dsfr.inspector.tree()

Permet de visualiser l’arborescence des instance du DSFR :

Capture d’écran de la console

State

Pour les développeurs contributeurs

dsfr.inspector.state();

Méthodes des composants

Le système de design fournit une l’API par composant pour interagir avec les éléments du DOM.

Exemple de méthode avec la Modale :
1 2 3 4 const element = document.getElementById("myModal5"); // Reference à l'element du DOM dsfr(element).modal.conceal(); // Méthode pour fermer manuellement la modale dsfr(element).modal.disclose(); // Méthode pour ouvrir manuellement la modale

 

Tableau récapitulatif des méthodes exposées par l’API

Attribut

Composants utilisant cet attribut

API

Attribut

Composants utilisant cet attribut

API

data-fr-js-accordions-group

  • Groupe d’accordéon
    (accordions-group)

1 2 3 4 5 6 7 8 dsfr(element).accordionsGroup.index; // {number} index de l'accordéon selectionné (-1 par défaut) dsfr(element).accordionsGroup.current; // {object} instance de l'accordéon selectionné (null par par défaut) dsfr(element).accordionsGroup.hasFocus; // {boolean} indique si le composant est focus dsfr(element).accordionsGroup.length; // {number} nombre d'instances de collapse du groupe dsfr(element).accordionsGroup.members; // {array} tableau des instances de collapse du groupe // exemples : dsfr(element).accordionsGroup.members[1].conceal(); // Fermeture de l'accordéon 2 dsfr(element).accordionsGroup.members[1].disclose(); // Ouverture de l'accordéon 2

data-fr-js-breadcrumb

  • Fil d’ariane (breadcrumb)

En mode SM et moins :

1 dsfr(element).breadcrumb.disclose(); // Ouverture du fil d'ariane

data-fr-js-collapse

  • Accordéon (accordion)

  • Alerte (alert)

  • Fil d’ariane (breadcrumb)

  • Gestionnaire de consentement (consent)

  • Menu latéral (sidemenu)

  • Navigation principale (navigation)

1 2 dsfr(element).collapse.conceal(); // Fermeture de l'element dsfr(element).collapse.disclose(); // Ouverture de l'element

data-fr-js-collapse-button

  • Accordéon (accordion)

  • Alerte (alert)

  • Fil d’ariane (breadcrumb)

  • Gestionnaire de consentement (consent)

  • Menu latéral (sidemenu)

  • Navigation principale (navigation)

1 dsfr(element).collapseButton.focus(); // Met le focus sur l'element

data-fr-js-modal

  • En-tête (header)

  • Gestionnaire de consentement (consent)

  • Modale (modal)

  • Paramètre d'affichage (display)

1 2 dsfr(element).modal.conceal(); // Fermeture de la modale dsfr(element).modal.disclose(); // Ouverture de la modale

data-fr-js-modal-button

  • En-tête (header)

  • Gestionnaire de consentement (consent)

  • Modale (modal)

  • Paramètre d'affichage (display)

1 dsfr(element).modalButton.focus(); // Met le focus sur l'element

 

data-fr-js-navigation

  • Navigation principale (navigation)

1 2 3 4 5 6 7 8 dsfr(element).navigation.index; // {number} index du menu selectionné (-1 par défaut) dsfr(element).navigation.current; // {object} instance du menu selectionné (null par par défaut) dsfr(element).navigation.hasFocus; // {boolean} indique si le composant est focus dsfr(element).navigation.length; // {number} nombre d'instances de collapse de la navigation dsfr(element).navigation.members; // {array} tableau des instances de collapse de la navigation // exemples : dsfr(element).navigation.members[1].conceal(); // Fermeture du sous-menu 2 dsfr(element).navigation.members[1].disclose(); // Ouverture du sous-menu 2

data-fr-js-sidemenu-list

  • Menu latéral (sidemenu)

1 2 3 4 5 6 7 dsfr(element).sidemenuList.index; // {number} index du sous-menu selectionné (-1 par défaut) dsfr(element).sidemenuList.current; // {object} instance du sous-menu selectionné (null par par défaut) dsfr(element).sidemenuList.hasFocus; // {boolean} indique si le composant est focus dsfr(element).sidemenuList.length; // {number} nombre d'instances de collapse du groupe dsfr(element).sidemenuList.members; // {array} tableau des instances de collapse du groupe // exemples : dsfr(element).sidemenuList.members[1].disclose(); // Ouverture du sous-menu 2

data-fr-js-tab-button

  • Onglets (tab)

1 dsfr(element).tabButton.focus(); // Met le focus sur l'element

data-fr-js-tab-panel

  • Onglets (tab)

1 2 3 dsfr(element).tabPanel.conceal(); // Fermeture de l'onglet dsfr(element).tabPanel.disclose(); // Ouverture de l'onglet dsfr(element).tabPanel.focus(); // Met le focus sur l'onglet

data-fr-js-tabs-group

  • Onglets (tab)

1 2 3 4 5 6 7 dsfr(element).tabsGroup.index; // {number} index de l'onglet selectionné (-1 par défaut) dsfr(element).tabsGroup.current; // {object} instance de l'onglet selectionné (null par par défaut) dsfr(element).tabsGroup.hasFocus; // {boolean} indique si le composant est focus dsfr(element).tabsGroup.length; // {number} nombre d'instances de collapse du groupe dsfr(element).tabsGroup.members; // {array} tableau des instances de collapse du groupe // exemples : dsfr(element).tabsGroup.members[1].disclose(); // Selection de l'onglet 2

data-fr-scheme

 

1 dsfr(element).scheme.scheme; // {string} valeur du theme (light par défaut | dark | system)

Événements

Le système de design fournit des événements personnalisés pour les actions uniques de la part de certains composants réactifs.

Exemple d’évènement avec la Modale :
1 2 3 4 5 6 7 8 9 10 11 12 13 const element = document.getElementById("myModal5"); // Reference à l'element du DOM // Ajoute un listener de l'event de fermeture de la modale element.addEventListener('dsfr.conceal', (e) => { console.log(e); [...] }) // Ajoute un listener de l'event d'ouverture de la modale element.addEventListener('dsfr.disclose', (e) => { console.log(e); [...] })

 

Tableau récapitulatif des évènements exposés par l’API

Attribut

Composants utilisant cet attribut

Events

Attribut

Composants utilisant cet attribut

Events

data-fr-js-collapse

  • Accordéon (accordion)

  • Alerte (alert)

  • Fil d’ariane (breadcrumb)

  • Gestionnaire de consentement (consent)

  • Groupe d’accordéon (accordions-group)

  • Menu latéral (sidemenu)

  • Navigation principale (navigation)

1 2 dsfr.conceal // Fermeture de l'element dsfr.disclose // Ouverture de l'element

data-fr-js-modal

  • En-tête (header)

  • Modale (modal)

  • Paramètre d'affichage (display)

1 2 dsfr.conceal // Fermeture de la modale dsfr.disclose // Ouverture de la modale

data-fr-js-tab-panel

  • Onglets (tab)

1 2 dsfr.conceal // Fermeture de l'onglet dsfr.disclose // Ouverture de l'onglet