Découvrir les fichiers de configuration d'une application

Objectif

Ce guide couvre les fichiers de configuration d'une application Data Platform : ce que contient chaque répertoire, puis comment modifier la configuration globale, un attribut d'API, le sélecteur de dates de la sidebar et un dashboard.

Comprendre les fichiers de l'application

Comprendre l'architecture de l'application

Vous disposez maintenant d'une application complète. L'arborescence de votre application doit ressembler à ceci :

├── config
├── node_modules
├── forepaas
├── public
├── scripts
└── src

Clarifions le contenu de chaque répertoire :

• config : ce dossier contient l'essentiel de la configuration de l'application. Dans ce dossier, vous pouvez définir et mettre à jour vos fichiers de configuration pour les dashboards, les menus, les styles, les traductions, etc. Le fichier le plus important ici est global.json, il permet de déclarer et d'utiliser tous ces fichiers de configuration. (expliqué juste après)
• forepaas : c'est l'équivalent de node_modules pour la platform. Il contient tous les composants de base nécessaires pour intégrer votre application à la Data Platform. Tous les packages listés dans /forepaas.json sont installés ici.
• node_modules : le dossier node_modules contient les bibliothèques téléchargées depuis npm. Il est basé sur /package.json.
• public : ce dossier contient tous les fichiers statiques (polices, icônes, images...). Vous pouvez accéder à un fichier stocké dans ce dossier via l'URL /assets/{subfolder}/{name}.{extension}.
  Par exemple, l'URL permettant d'accéder à favicon.png (et de l'afficher dans une balise <img>) situé dans assets/img est `/assets/img/favicon.png
• scripts : ce dossier contient des scripts utiles que vous pouvez utiliser pour générer des composants, des dashboards, ou pour zipper ce Projet afin de le charger facilement sur la platform.
• src : dans ce dossier, vous pouvez créer ou mettre à jour vos propres composants et services personnalisés. Nous vous apprendrons à le faire dans les prochaines étapes de ce tutoriel.

Comprendre les fichiers de configuration

Le fichier de configuration globale est global.json.

Ce fichier représente le point d'entrée de votre application.
C'est là que vous déclarez vos variables d'environnement, vos routes, vos dashboards, et bien d'autres champs importants.

Ouvrez global.json situé dans le dossier config.
Au départ, il ressemble à ceci :

{
  "authentication": "{{ENV.CAM_URL}}",
  "api": "{{ENV.API_URL}}",
  "application_name": "{{ENV.APP_NAME || 'ForePaaS'}}",
  "debug": "{{ENV.DEBUG}}",
  "loader": "spinner",
  "lang": "fr",
  "version": 3,
  "storage": {
    "type": "sessionStorage"
  },
  "root": "/rides-analytics",
  "menu": [
    "file://config/menus/header.json",
    "file://config/menus/sidebar.json"
  ],
  "dashboarding": {
    "/rides-analytics": "file://config/dashboards/rides-analytics.json"
  },
  "style": "file://config/style.json",
  "reportings": "file://config/reportings.json",
  "i18n": {
    "en": "file://config/i18n/en.json"
  },
  "formatter": "file://config/formatter.json"
}

Expliquons ci-dessous les champs les plus importants :

• authentication : fait référence à l'URL d'authentification, elle doit avoir la forme suivante : https://{api-subdomain}.eu.dataplatform.ovh.net/cam?app_id={app_id}.
  Par défaut, elle est définie comme une variable d'environnement. Il est important de la conserver ainsi pour déployer votre application en production. Veuillez consulter cette partie pour comprendre comment surcharger ce champ à des fins de développement local.

• api : de même que ci-dessus, mais fait référence à l'URL de l'API, elle doit avoir la forme suivante : https://{api-subdomain}.eu.dataplatform.ovh.net/{api-alias}.

• application_name : le titre de votre application

• root : le chemin racine de votre application.

• menu : un tableau contenant vos fichiers de configuration de menus.
  Le header et la sidebar sont déjà définis par défaut.

• dashboarding : un objet permettant de définir vos dashboards. L'attribut est l'URL du dashboard, et la valeur est le fichier de configuration du dashboard.

• style : le fichier de configuration de style. Il permet de styliser les composants. Certains composants sont déjà stylisés à cet endroit.

• i18n : un objet permettant de définir toutes vos langues prises en charge. L'attribut est l'alias de la langue, et la valeur est le fichier de configuration de traduction associé à la langue.

• formatter : le fichier de configuration du formatter. Il permet de formater les données, d'arrondir les nombres, d'ajouter des unités, etc.
  Certains champs sont déjà formatés par défaut.

Modifier les fichiers de configuration

Maintenant que vous connaissez mieux l'architecture de l'application, vous pouvez enfin la modifier !

Surcharger le fichier de configuration globale

La première étape consiste à relier votre application locale au service d'authentification et à l'API créée précédemment sur votre Projet. Comme nous avons seulement besoin que ces changements s'appliquent localement, nous ne voulons pas modifier directement global.json. Nous allons créer un autre fichier global-override.json pour le surcharger à la place.

• Créez global-override.json dans le dossier config
• Copiez-collez ce json dans votre nouveau fichier :

{
    "authentication": "https://{api-subdomain}.eu.dataplatform.ovh.net/cam?app_id={app_id}",
    "api": "https://{api-subdomain}.eu.dataplatform.ovh.net/{api-alias}"
}

Il y a trois variables que vous devez remplacer :

• {api-subdomain} : connectez-vous à la platform, allez dans les paramètres de votre API, cette variable est référencée comme le « Subdomain » dans le panneau Domain Name System
• {api-alias} : cette variable peut être extraite du « Domain » en supprimant eu.dataplatform.ovh.net/

• app_id : rendez-vous sur la page Identity Access Manager. Dans l'onglet Application, allez modifier votre application. Cette variable est référencée comme « Id » dans les informations de l'application.

Enregistrez tous les fichiers. L'application exécutée localement affiche maintenant une vue un peu plus avancée que celle que vous aviez à la fin du guide de démarrage.

L'image suivante montre à quoi cela ressemblera au premier démarrage après avoir configuré le global-override.json, mais comme vous pouvez le voir, il semble y avoir un problème avec la case de sélection des jours fériés et l'affichage des données de l'historique des trajets. La section suivante explique comment résoudre ces problèmes.

Ajouter l'attribut cat_holiday à votre API

Vous remarquerez peut-être que dans la sidebar, le sélecteur des jours fériés ne s'affiche pas correctement. C'est le cas car vous n'avez aucun attribut exposé lié aux jours fériés dans le cadre du guide de démarrage.

Pour résoudre ce problème, vous devez :

• Ajouter un attribut de type chaîne nommé cat_holiday à la table dataset_history.
• Construire la table dataset_history et régénérer l'Action DPE correspondante.
• Dans le DPE, modifier l'Action Aggregate de la table pour créer correctement l'attribut cat_holiday avec le code ci-dessous.

CASE 
WHEN chicago_calendar_full.christmas_holidays=1 THEN 'Christmas Holidays'
WHEN chicago_calendar_full.summer_holidays=1 THEN 'Summer Break'
WHEN chicago_calendar_full.spring_holidays=1 THEN 'SpringBreak'
WHEN chicago_calendar_full.public_holiday=1 THEN 'Bank Holiday'
WHEN chicago_calendar_full.autumn_holidays=1 THEN 'Fall Holidays'
WHEN chicago_calendar_full.sport_holidays=1 THEN 'Sport Holidays'
ELSE 'off leave'
END

• Relancer le workflow correspondant.
• Vider le cache dans Application Services.

Maintenant, relancez simplement votre application et le Holidays Selector devrait s'afficher correctement.

Modifier la plage du date-picker dans sidebar.json

La raison pour laquelle le graphique rides-history affiche « no data » est que le date-picker n'est pas configuré pour correspondre à la plage réelle du dataset. Actuellement, le date-picker de la sidebar n'affiche qu'une plage de dates allant d'aujourd'hui à un an en arrière, en raison de sa configuration. Comme notre dataset des fichiers Chicago couvre les années 2015 à 2020, nous devons mettre à jour le fichier sidebar.json en modifiant des champs spécifiques pour que le date-picker inclue la plage complète de nos données.

Pour résoudre ce problème, vous devez :

• aller dans sidebar.json
• trouver les champs startAt, minDate, maxDate, endAt.
• remplacer la section ci-dessus par le code ci-dessous.

"startAt": "2015-01-01",
"minDate": "2015-01-01",
"maxDate": "2020-12-31",
"endAt": "2020-12-31"

Maintenant, il ne vous reste plus qu'à enregistrer et relancer votre application, et le data-picker devrait afficher la plage entre 2015 et 2020.

Maintenant que le date-picker est corrigé, testons-le ! Sélectionnez une plage, par exemple du 1er janvier 2015 au 1er janvier 2016.

Vous devriez maintenant voir le graphique rides-history se remplir de données. Si le graphique semble dispersé ou incorrect, c'est probablement parce que les données ne sont pas triées par date. Pour corriger cela, ouvrez rides-analytics.json et ajoutez l'extrait suivant à la définition de la requête rides-history :

"order": {
  "yearmonth": "asc"
}

Changer l'attribut utilisé pour le sélecteur de stations dans la sidebar

Actuellement, lorsque vous interagissez avec le sélecteur « Stations » dans la sidebar, vous voyez une liste d'identifiants de stations bruts. Bien que cela soit techniquement correct, ce n'est pas très convivial pour l'utilisateur ! Améliorons cela en affichant plutôt les noms réels des stations, afin de rendre le processus de sélection beaucoup plus clair.

Pour y parvenir :

• Naviguez vers le fichier de configuration sidebar.json.
• Repérez la définition du composant qui possède l'ID dyn-stations.
• Mettez à jour la propriété attribute au sein du dictionnaire de ce composant avec station_name. Cela indique au composant de récupérer et d'afficher les noms lisibles issus de votre dataset.
• Ensuite, vous constaterez peut-être que le graphique Top 7 Stations affiche actuellement des valeurs station_id plutôt que des noms de stations plus lisibles. Pour corriger cela, appliquez un changement similaire à celui effectué précédemment :
  • ouvrez votre fichier rides-analytics.json et repérez la configuration du graphique « Top 7 Stations ».
  • Puis, mettez à jour son champ scale pour utiliser station_name.

Modifier un dashboard

Comme vous l'avez vu dans global.json, votre application dispose déjà d'un dashboard appelé rides-analytics.

Dans cette partie, vous allez voir comment modifier le fichier de configuration du dashboard pour changer la disposition et la position des éléments.

Commençons par ouvrir rides-analytics.json dans config/dashboards. Vous allez d'abord créer un panel et contrôler la hauteur, la largeur et la position d'un élément.

Pour créer un panel, ajoutez ces quelques lignes à la fin du tableau items Ce sera un espace réservé pour votre future barre de recherche, donnons-lui donc l'id search-bar.

{
    "type": "panel",
    "id" : "search-bar",
    "sizeX": 100,
    "sizeY": 100,
    "row": 0,
    "col": 0,
    "items": []
}

• type : représente le type de l'élément. Il peut s'agir d'un composant fourni par défaut par la Platform ou d'un composant spécifique.
• id : l'id de votre élément.
• size X : représente la largeur de l'élément. La valeur doit être comprise entre 0 et 100, car elle représente un pourcentage de la largeur de l'élément conteneur.
• size Y : représente la hauteur de l'élément.
• row : représente le décalage de ligne.
• col : représente le décalage de colonne.

Après avoir ajouté le panel, l'application ressemble à ceci :

Maintenant, modifiez le panel pour réduire sa hauteur en changeant la valeur de sizeY à 19.
Ensuite, déplacez tous les autres panels vers le bas en modifiant la valeur de row pour chacun d'eux. Ajoutez 20 à la valeur actuelle pour repousser les autres panels.

Maintenant, pour garantir la meilleure expérience de visualisation possible lorsque nous introduirons notre carte interactive personnalisée plus loin dans le tutoriel, nous allons apporter une mise à jour stratégique à la disposition du dashboard. Ce n'est pas qu'une question d'esthétique ; c'est conçu pour permettre à la carte de coexister harmonieusement avec le reste de votre dashboard. Dans ce cadre, nous ajouterons également un nouveau panel qui servira d'espace réservé idéal pour notre carte interactive.

Remplacez l'intégralité du contenu de votre fichier rides-analytics.json par la configuration fournie ci-dessous. Après l'enregistrement, vous observerez la disposition mise à jour du dashboard.

{
  "name": "Rides analytics",
  "width": 100,
  "height": 100,
  "margin": [
    10,
    10
  ],
  "description": "",
  "items": [
    {
      "type": "panel",
      "id" : "search-bar",
      "sizeX": 100,
      "sizeY": 19,
      "row": 0,
      "col": 0,
      "items": [
      ]
    },
    {
      "type": "panel",
      "id": "custom-map",
      "sizeX": 75,
      "sizeY": 99,
      "row": 20,
      "col": 0,
      "items": []
    },
    {
      "type": "panel",
      "id": "top-stations-container",
      "sizeX": 24,
      "sizeY": 99,
      "row": 20,
      "col": 76,
      "items": [
        {
          "type": "chart",
          "chart": {
            "id": "chart-7843335",
            "component": "recharts.bar-horizontal",
            "options": {},
            "request": {
              "data": {
                "limit": 7,
                "fields": {
                  "rides": [
                    "sum"
                  ]
                }
              },
              "scale": {
                "fields": [
                  "station_name"
                ]
              },
              "order": {
                "rides": "desc"
              }
            }
          },
          "sizeX": 100,
          "sizeY": 86,
          "row": 6,
          "col": 0
        },
        {
          "type": "html",
          "content": "Station top 7",
          "customclass": "chart-title",
          "sizeX": 100,
          "sizeY": 5,
          "row": 0,
          "col": 0
        }
      ]
    },
    {
      "type": "panel",
      "id": "rides-history-container",
      "sizeX": 75,
      "sizeY": 70,
      "row": 120,
      "col": 0,
      "items": [
        {
          "type": "html",
          "content": "Rides history",
          "customclass": "chart-title"
        },
        {
          "type": "chart",
          "chart": {
            "id": "chart-4992931",
            "component": "recharts.line",
            "request": {
              "data": {
                "fields": {
                  "avg_rides_per_day_per_station": [
                    "select"
                  ]
                }
              },
              "scale": {
                "fields": [
                  "yearmonth"
                ]
              },
              "filter": {},
              "order": {
                "yearmonth": "asc"
              }
            },
            "options": {
              "yAxis": {
                "domain": [
                  0,
                  6000
                ]
              }
            },
            "dynamic-parameters": [
              "dynamic-date",
              "dynamic-holidays",
              "dynamic-stations"
            ]
          },
          "sizeX": 100,
          "sizeY": 55,
          "col": 0,
          "row": 9
        }
      ]
    },
    {
      "type": "panel",
      "id": "weekly-seasonality-container",
      "sizeX": 24,
      "sizeY": 135,
      "row": 120,
      "col": 76,
      "items": [
        {
          "type": "chart",
          "chart": {
            "id": "chart-3259339",
            "component": "recharts.donut",
            "request": {
              "data": {
                "fields": {
                  "avg_rides_per_day_per_station": [
                    "select"
                  ]
                }
              },
              "scale": {
                "fields": [
                  "week_day_label"
                ]
              }
            },
            "options": {}
          },
          "sizeX": 103,
          "sizeY": 61,
          "row": 29,
          "col": 0
        },
        {
          "type": "html",
          "content": "Weekly seasonality",
          "customclass": "chart-title",
          "sizeX": 93,
          "sizeY": 12,
          "row": 0,
          "col": 0
        }
      ]
    },
    {
      "type": "panel",
      "id": "rides-temperature-container",
      "sizeX": 37,
      "sizeY": 64,
      "row": 191,
      "col": 0,
      "items": [
        {
          "type": "chart",
          "chart": {
            "id": "chart-6930201",
            "component": "recharts.bar",
            "request": {
              "data": {
                "fields": {
                  "avg_rides_per_day_per_station": [
                    "select"
                  ]
                }
              },
              "scale": {
                "fields": [
                  "cat_temperature"
                ]
              }
            },
            "options": {}
          },
          "sizeX": 100,
          "sizeY": 54,
          "row": 6,
          "col": 0
        },
        {
          "type": "html",
          "content": "Rides per Temperature",
          "customclass": "chart-title",
          "sizeX": 100,
          "sizeY": 8,
          "row": 0,
          "col": 0
        }
      ]
    }
  ],
  "url": "/rides-analytics",
  "path": "",
  "tags": []
}

La disposition de votre page rides analytics est maintenant prête.

Nous allons maintenant apprendre à ajouter un nouveau dashboard à notre application.

Générer un dashboard

Pour générer un nouveau dashboard, créez un nouveau fichier json dans config/dashboards.
Vous pouvez accélérer le processus en utilisant notre script

yarn generate

À l'aide des touches fléchées, choisissez dashboard, puis saisissez le nom de votre nouveau dashboard (« learn » dans ce cas)

Pour relier votre dashboard à votre application, modifiez global.json en ajoutant une nouvelle entrée dans la section dashboarding.

"/learn": "file://config/dashboards/learn.json"

La clé représente le chemin URL de votre nouveau dashboard.
La valeur représente le chemin vers le fichier .json associé à ce dashboard.

Votre nouvelle page de dashboard devrait maintenant être accessible à l'adresse http://localhost:3333/#/learn.

Dernière étape, nous devrons activer l'accès à ce dashboard depuis l'interface.

Pour ce faire, allez dans config/menus/header.json et ajoutez cette entrée dans le tableau items du conteneur tabs :

{
  "type":"link",
  "text":"Rides",
  "url":"/rides-analytics"
},
{
  "type": "link",
  "text": "Learn",
  "url": "/learn"
}

Cela nous permettra de basculer facilement entre les deux dashboards que nous avons.

Vous progressez bien !

Vous connaissez maintenant l'architecture de l'application et savez comment y travailler localement.
Abordons le sujet de la page suivante : personnaliser votre application. Il existe plusieurs façons de styliser vos composants :

• Utiliser des modèles de style : cela permet de définir des modèles qui seront appliqués par défaut.

• Styliser au niveau du composant : le style ne sera appliqué qu'à un composant spécifique. Vous pouvez y parvenir en passant certaines props lors de la déclaration d'un graphique ou d'un paramètre dynamique.
  Exemple : allez dans config/dashboards/rides-analytics.json et consultez le champ options à l'intérieur du graphique en ligne situé dans le panel rides-history-container.

• Styliser au niveau du module (pour un paramètre dynamique uniquement) : le style sera appliqué à tous les paramètres dynamiques de ce type. Exemple : propriétés passées à l'intérieur de select-box dans style.json

• Styliser au niveau du module (par ex. recharts) : le style sera appliqué à tous les composants du module.
  Exemple : propriétés passées à l'intérieur de recharts dans style.json

• Styliser au niveau du type de composant (par ex. recharts-bar) : le style sera appliqué à tous les composants qui partagent le type de composant spécifié
  Exemple : propriétés passées à l'intérieur de recharts-bar dans style.json

Découvrons maintenant comment créer et modifier des graphiques.

Aller plus loin

Si vous avez besoin d'une formation ou d'une assistance technique pour la mise en oeuvre de nos solutions, contactez votre commercial ou cliquez sur ce lien pour obtenir un devis et demander une analyse personnalisée de votre projet à nos experts de l’équipe Professional Services.

Posez vos questions, faites-nous part de vos commentaires et interagissez directement avec l’équipe qui développe la Data Platform sur le canal Discord dédié.

Si vous avez besoin d'une assistance concernant vos services OVHcloud, créez une demande depuis notre centre d'aide.

Rejoignez notre communauté d'utilisateurs.