Documentation du Widget Graphique de Base

Aperçu​

Le widget BasicChart permet de créer et d'afficher des graphiques interactifs basés sur la bibliothèque Chart.js. Il offre une grande flexibilité dans la configuration des données, des styles et des types de graphiques pour visualiser vos données de manière claire et attrayante.

Types de Graphiques Supportés​

Le widget supporte plusieurs types de graphiques :

• Line : Graphique en ligne
• Bar : Graphique à barres
• Doughnut : Graphique en anneau
• Pie : Graphique circulaire
• PolarArea : Graphique en aire polaire
• Radar : Graphique radar

Configuration de Base​

Paramètres Globaux​

Nom du Widget​

• Champ : Name
• Description : Nom d'affichage du widget
• Type : Texte

Variable/Modèle​

• Champ : Variable/Model
• Description : Nom de la variable qui stockera les données du graphique
• Type : Texte
• Requis : Oui

Configuration du Graphique​

Type de Graphique​

• Champ : Chart Type
• Description : Sélectionne le type de graphique à afficher
• Options : Line, Bar, Doughnut, Pie, PolarArea, Radar
• Par défaut : Line

Type de Données​

• Champ : Data type
• Description : Source des données pour le graphique
• Options :
  • Collection : Données d'une collection de base de données
  • Report : Données d'un rapport généré
  • External databases : Données d'une base de données externe

Source de Données​

• Champ : Data
• Description : Sélection de la source spécifique basée sur le type choisi
• Dépend de : Type de données
• Configuration :
  • Si "Collection" : Liste des collections disponibles
  • Si "Report" : Liste des rapports disponibles
  • Si "External databases" : Liste des connexions de base de données

Annotation de l'Axe Y​

• Champ : Y-Axis annotation (préfixe @)
• Description : Texte à afficher à côté des valeurs de l'axe Y (par ex., €, $, %)
• Type : Texte optionnel
• Exemple : "@€" affichera "€100" au lieu de "100"

Configuration des Jeux de Données​

Chaque graphique peut contenir plusieurs jeux de données pour comparer différentes séries de données.

Ajout d'un Jeu de Données​

1. Cliquer sur le bouton "+ Dataset"
2. Configurer chaque jeu de données individuellement

Configuration du Jeu de Données​

Label du Jeu de Données​

• Champ : Label
• Description : Nom affiché dans la légende pour ce jeu de données
• Type : Texte

Couleur de Remplissage​

• Champ : Color (sélecteur de couleur)
• Description : Couleur utilisée pour représenter ce jeu de données
• Type : Couleur avec support de la transparence alpha

Requête de Données​

• Champ : Query (bouton Edit)
• Description : Requête pour récupérer les données de la source
• Format : JSON
• Exemple pour Collection :

[
  {
    "$match": {
      "status": "active"
    }
  },
  {
    "$group": {
      "_id": "$category",
      "total": { "$sum": "$amount" }
    }
  }
]

Colonne de Données​

• Champ : Data column
• Description : Nom du champ contenant les valeurs numériques à afficher
• Type : Texte
• Exemple : "total", "count", "value"

Configuration des Labels​

• Option : Use labels (bouton radio par jeu de données)
• Description : Désigne quel jeu de données fournira les labels pour l'axe X
• Champ Associé : Nom de la colonne des labels
• Exemple : "category", "date", "name"

Configuration Avancée​

Validation​

Le widget hérite des options de validation standard :

• Available : Contrôle si le widget est disponible selon l'écran
• Visible : Contrôle la visibilité basée sur des conditions
• Required : Non applicable pour ce type de widget
• Disable : Contrôle l'état désactivé du widget

Style​

Classes CSS​

• Champ : Class
• Description : Classes CSS personnalisées à appliquer au widget
• Type : Texte (noms de classes séparés par des espaces)

Classes Dynamiques​

• Bouton : Icône pinceau
• Description : Permet de définir des classes CSS conditionnelles
• Format : Objet JSON avec des conditions

Exemples d'Utilisation​

Graphique à Barres Simple​

1. Type de Graphique : Bar
2. Type de Données : Collection
3. Source : Sélectionner une collection de commandes
4. Jeu de Données 1 :
   • Label : "Ventes Mensuelles"
   • Couleur : Bleu (#3498db)
   • Requête :

• Colonne de données : "total"
• Utiliser les labels : Coché
• Colonne des labels : "_id"

Graphique Circulaire avec Plusieurs Sources​

1. Type de Graphique : Pie
2. Type de Données : Collection
3. Jeu de Données 1 :
   • Label : "Distribution par Catégorie"
   • Requête pour regrouper par catégorie
   • Colonne de données : "count"

Graphique en Ligne Temporel​

1. Type de Graphique : Line
2. Annotation de l'Axe Y : "@€"
3. Plusieurs Jeux de Données pour comparer différentes périodes ou métriques

Propriétés Techniques​

Variables Générées​

Le widget génère automatiquement les variables suivantes :

• {model} : Contient les données du graphique
• {model}_chart : Instance Chart.js pour des manipulations avancées

Méthodes Disponibles​

renderChart()​

Reconstruit le graphique avec de nouvelles données

getChart()​

Retourne l'instance Chart.js actuelle

setChart(chart)​

Définit une nouvelle instance Chart.js

Événements​

Mises à Jour des Requêtes​

Le graphique se met à jour automatiquement lorsque les variables de requête changent.

Bonnes Pratiques​

Performance​

• Limiter le nombre de points de données pour des performances optimales
• Utiliser des requêtes optimisées avec des agrégations côté base de données
• Éviter de recréer le graphique trop fréquemment

Design​

• Choisir des couleurs contrastées pour la lisibilité
• Utiliser des labels explicites pour les jeux de données
• Ajouter des annotations d'unités lorsque nécessaire

Données​

• S'assurer que les colonnes de données contiennent des valeurs numériques
• Gérer les cas de données manquantes dans vos requêtes
• Utiliser des regroupements appropriés pour éviter la surcharge d'informations

Dépannage​

Problèmes Courants​

Le graphique ne s'affiche pas​

• Vérifier que la source de données est correctement configurée
• S'assurer que la requête retourne des données
• Vérifier les noms des colonnes de données et de labels

Données incorrectes​

• Valider la syntaxe de la requête JSON
• Vérifier les permissions d'accès à la source de données
• Tester la requête indépendamment du widget

Problèmes de style​

• Vérifier les classes CSS personnalisées
• S'assurer que les couleurs sont au format hexadécimal valide
• Contrôler les dimensions du conteneur parent

Messages d'Erreur​

Les erreurs de configuration sont affichées directement dans l'interface avec des indications de résolution.

Fonctionnalités Avancées​

Jeux de Données Multiples​

Vous pouvez ajouter plusieurs jeux de données pour comparer différentes séries de données sur le même graphique. Chaque jeu de données peut avoir :

• Des requêtes différentes
• Des couleurs différentes
• Des sources de données différentes
• Des labels partagés ou individuels

Réactivité du Graphique​

Le graphique s'adapte automatiquement à la taille de son conteneur et fournit un comportement réactif sur différentes tailles d'écran.

Fonctionnalités Interactives​

Les graphiques incluent une interactivité intégrée telle que :

• Des infobulles au survol montrant les valeurs exactes
• Clic sur la légende pour afficher/masquer les jeux de données
• Effets d'animation lors des mises à jour de données

Stylisation Personnalisée​

Au-delà de la configuration de base, vous pouvez :

• Appliquer des classes CSS personnalisées pour un style avancé
• Utiliser des classes dynamiques basées sur les conditions de données
• Contrôler les dimensions et la disposition du graphique

Intégration avec d'Autres Composants​

Le widget BasicChart peut être intégré avec d'autres composants de formulaire pour créer des tableaux de bord dynamiques où :

• Les composants de filtre mettent à jour les requêtes du graphique
• La sélection de données affecte l'affichage du graphique
• Les interactions avec le graphique déclenchent des mises à jour d'autres composants