Graphiques D3

Last modified by Aurelie Bertrand on 2023/05/11 10:24

Principe général

d3main.png

Wikipedia :

D3.js (ou D3 pour Data-Driven Documents) est une bibliothèque graphique JavaScript qui permet l'affichage de données numériques sous une forme graphique et dynamique. Il s'agit d'un outil important pour la conformation aux normes W3C qui utilise les technologies courantes SVGJavaScript et CSS pour la visualisation de données. Intégrée dans une page web HTML, la bibliothèque JavaScript D3.js utilise des fonctions pré-construites de JavaScript pour sélectionner des éléments, créer des objets SVG, les styliser, ou y ajouter des transitions, des effets dynamiques ou des infobulles.

DigDash offre la possibilité de construire des modèles de visualisation basés sur d3.js.

Cela permet aux utilisateurs qui le souhaitent d'enrichir leur bibliothèque de graphes, afin d'exploiter d'autres types de flux que ceux proposés par défaut.

Modèles (templates) D3 dans Digdash

Dans DigDash, D3 correspond à un type de visualisation générique comportant un certain nombre de sous-modèles, à l'instar des visualisations de type jauge, barre d'énergie ou infographie.

La différence avec les types précédemment cités réside dans le fait de pouvoir gérer ces modèles (création, édition, suppression).

Chaque modèle est associé à un certains nombre de fichiers (essentiellement javascript et CSS) permettant d'une part de recevoir les données aplaties d'un modèle de rendu (via la fonction de plugin) puis d'autre part de construire la visualisation à partir de ces données.

Ce principe peut être représenté par le schéma suivant :

d3archi.PNG

De droite à gauche :

  • Chaque flux de type D3 est basé sur un modèle du type de visualisation principal D3.
  • Chaque modèle est nommé et est associé à un certain nombre de fichiers qui doivent être présents sur le serveur de document D3templates

Comme indiqué sur le schéma, un même fichier peut être exploité par plusieurs modèles à la fois (comme par exemple un fichier de version d3js). Il conviendra donc d'être prudent quant à la manipulation de ces fichiers de ressources, qui peut impacter plusieurs modèles et donc plusieurs flux.

Le dossier D3templates

Le serveur de documents D3templates est le dossier suivant (situé dans votre répertoire d'installation de DigDash Entreprise) :

${DOSSIER DE CONFIGURATION DIGDASH}/Enterprise Server\${DOMAINE CONCERNE}\config\web\public\

  • Si le dossier D3templates n'existe pas, il vous faut l'importer : 
    • Rendez-vous dans le dossier "Add-on" à la racine du répertoire d'installation
    • Copier le dossier "D3templates"
    • Coller ce dossier dans ${DOSSIER DE CONFIGURATION DIGDASH}/Enterprise Server\${DOMAINE CONCERNE}\config\web\public\
  • Vous disposez maintenant des fichiers de configuration des graphiques par défaut prédéfinis D3JS dans DigDash.

La fonction de plugin

Chaque modèle doit être construit avec une fonction javascript spécifique : la fonction de plugin. C'est cette fonction qui permet de recevoir les données en entrée d'un flux DigDash afin de générer un graphe.

Il n'y a pas de règles particulières quant à la dénomination de cette fonction mais il est conseillé de suivre la convention suivante : {NOM_MODELE}PluginDD

Cette fonction doit impérativement se trouver dans un des fichiers javascript associé au modèle.

La fonction de plugin prend en entrée trois paramètres :

  • ddjson : l'objet contenant les informations du flux en cours d'édition (datamodel-sélection, n-uplets dimensionnels, mesures, palette de couleur) sous une forme exploitable par le développeur
  • ddobj (déprécié) : un objet généré par la logique DigDash contenant la totalité des informations du flux en cours d'édition
  • exportCallback : la fonction de callback a exécuter pour l'intégration du flux dans une fabrique de document / pour l'export

Plus de détails dans la page de documentation Ajouter un graphique D3.

Gestionnaire de modèles D3

Le gestionnaire est une interface en deux parties.

A gauche, la liste des modèles D3.

A droite, la configuration du modèle sélectionné, ainsi que la possibilité d'éditer le contenu des fichiers associés, fichiers qui seront chargés dans le DOM au rendu d'un flux.

d3manager1.png

Un modèle peut être désigné comme modèle par défaut afin d'être automatiquement sélectionné à la création d'un flux de type D3.

Gestion des fichiers de ressources

Il est possible de gérer les liens modèle-fichiers via le menu contextuel :

d3manager2.PNG

Si le fichier existe dans le répertoire D3templates, il est possible de le sélectionner directement (Choisir des fichiers existants sur le serveur...) via l'interface de gestionnaire de documents.

Sinon, il peut être importé, ou créé ex-nihilo, et ajouté à D3templates.

Il est possible d'éditer directement le contenu d'un fichier dans l'éditeur de code.

Une référence à un fichier peut être supprimée d'un modèle D3 (Retirer du modèle) : cela ne supprime pas le fichier en question qui reste présent dans le dossier D3templates. Le fichier ne sera plus chargé dans la page de rendu des flux utilisant ce modèle.

De même, la suppression d'un modèle D3 ne supprime pas les fichiers associés dans D3templates.

Bien nommer ses fichiers

La gestion de sous-dossiers dans le répertoire D3templates n'étant provisoirement pas prise en charge, il est conseillé de nommer intelligemment les fichiers afin de s'y retrouver plus facilement.

Un fichier propre à un modèle devrait respecter la convention suivante :

{nomDuModèle}_{rôleDuFichier}.{extension}

Exemples : textReport_plugin.js, circlePacking_style.css

Un fichier commun à plusieurs modèles devrait respecter la convention suivante :

{nomDuGroupeCommun}_{rôleDuFichier}.{extension}

Exemple : common_tooltip.js

Ainsi les fichiers d'un même modèle sont alphabétiquement regroupés.

Dupliquer un modèle existant

Lors de la duplication d'un template D3, vous avez la possibilité de dupliquer des fichiers afin que leurs modifications n'impactent que le modèle nouvellement créé. C'est en général souhaité pour le fichier contenant la fonction de plugin ou les fichiers de construction graphique.

La convention de nommage décrite précédemment reste fortement recommandée.

d3duplicate.PNG

Création de flux D3 dans DigDash

La documentation pratique pour la mise en œuvre de modèles D3 pour la création de flux est détaillée à la page suivante : Ajouter un graphique - D3.