API Javascript

Cette page 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ènements 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 

<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.

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 

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 : 

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 :

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 :  

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
data-fr-js-accordions-group Groupe d'accordéon (accordions) 

                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 : 
 
                    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) 

                    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) 

                    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) 

                    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) 

                    dsfr(element).modalButton.focus(); // Met le focus sur l'element
data-fr-js-navigation Navigation principale (navigation) 

                    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) 

                    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) 

                    dsfr(element).tabButton.focus(); // Met le focus sur l'element
data-fr-js-tab-panel Onglets (tab) 

                    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) 

                    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 

                    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 : 

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);
    [...]
})
Title
Tableau récapitulatif des évènements exposés par l’API
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 (accordion),
Menu latéral (sidemenu),
Navigation principale (navigation)		 
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)		 
dsfr.conceal // Fermeture de la modale

dsfr.disclose // Ouverture de la modale
data-fr-js-tab-panel Onglets (tab) 
dsfr.conceal // Fermeture de l'onglet

dsfr.disclose // Ouverture de l'onglet

Contribution

API Analytics