Ajouter des composants personnalisés
Avec le framework React, vous pouvez créer vos propres composants depuis zéro. Ces composants peuvent être utilisés pour deux choses : les paramètres dynamiques et les graphiques
Objectif
Avec le framework React, vous pouvez créer vos propres composants depuis zéro. Ces composants peuvent être utilisés pour deux choses : les paramètres dynamiques et les graphiques.
À tout moment, n'hésitez pas à consulter le Guide technique pour en savoir plus sur les composants personnalisés !
Utiliser un composant personnalisé comme paramètre dynamique
Générer un composant
Voyons comment créer un composant personnalisé et comment l'utiliser comme paramètre dynamique.
À titre d'exemple, nous allons vous montrer étape par étape comment créer ce composant de groupe de cases à cocher :
Pour générer un composant, vous pouvez utiliser notre script préconstruit en exécutant la commande ci-dessous :
Sélectionnez le générateur component, nommez-le DynamicParameterCheckbox et répondez « No » à la dernière question, comme indiqué ci-dessous :
Il est important que le nom de votre composant commence par DynamicParameter pour qu'il soit enregistré comme paramètre dynamique
Ce script génère un dossier dans src/components contenant trois fichiers :
DynamicParameterCheckbox.jsxDynamicParameterCheckbox.lessindex.js
Déclarer un composant
Avant de commencer à travailler sur le composant lui-même, prenons une minute pour voir comment le déclarer et l'utiliser.
Suivez ces étapes pour déclarer le nouveau composant :
-
Allez dans
src/components/index.js -
Importez le composant en ajoutant cette ligne en haut du fichier :
-
Déclarez-le en ajoutant son nom à l'objet components
Vous pouvez maintenant appeler ce composant dans vos fichiers de configuration en spécifiant son alias. Pour obtenir l'alias d'un composant, transformez son nom du camelCase au kebab-case (DynamicParameterCheckbox devient dynamic-parameter-checkbox), puis retirez-en "dynamic-parameter" et/ou "chart".
Ici, l'alias du composant est checkbox. Allez maintenant dans config/menus/sidebar.json et changez la propriété component de dynamic-weekday en "checkbox" (c'est-à-dire l'alias).
Allez sur la page de votre application, remarquez que le composant dynamic-weekday a changé.
Le composant s'affiche mais n'est pas encore fonctionnel : son comportement est défini dans la section suivante.
Modifier un composant
Le framework utilisé dans ce guide sera React.
Nous allons vous guider étape par étape pour créer vos composants, mais si vous rencontrez des difficultés parce que vous n'êtes pas familier avec ce framework, vous pouvez consulter la documentation ici.
De plus, puisque nous travaillons avec des composants fonctionnels, nous allons utiliser l'une des dernières fonctionnalités disponibles, les React Hooks. Vous pouvez consulter cette page pour plus d'informations.
Commençons par modifier DynamicParameterCheckbox.jsx
Puisque ce composant est déclaré comme un dynamic-parameter, certaines props lui sont déjà automatiquement transmises par la logique de flux de données de la Platform. Ces props peuvent être journalisées lors du premier rendu du composant, en utilisant le hook useEffect.
Commencez par importer useEffect et useState (dont vous aurez besoin plus tard) en modifiant la première ligne du fichier :
Ajoutez ensuite props aux arguments du composant fonctionnel :
Enfin, ajoutez le hook useEffect à l'intérieur de cette fonction, juste avant l'instruction return.
Votre composant fonctionnel devrait être défini comme suit :
Ouvrez le panneau console de votre navigateur, vous devriez pouvoir voir les props.
Comme vous pouvez le voir, la plupart de ces props sont transmises dans sidebar.json lors de la définition du dynamic-parameter.
La seule exception est items, qui est le résultat d'une requête interne interrogeant le champ spécifié dans dictionary (week_day dans ce cas)
Créons maintenant les checkboxes.
Pour y parvenir, vous devrez installer un petit package : react-checkbox-group. Faites-le en exécutant :
Ce package vous permet d'utiliser un composant de groupe de cases à cocher. Vous pouvez maintenant l'importer en ajoutant cette ligne en haut du fichier :
Ajoutez une variable booléenne expanded à l'état du composant pour pouvoir afficher ou masquer le CheckboxGroup à l'aide d'une petite icône flèche :
Changez l'instruction return de la fonction comme suit :
La section titre utilise props.title. Cela signifie que vous devez transmettre une prop title dans la définition de dynamic-weekday dans config/menus/sidebar.json, comme indiqué ci-dessous : (l'élément HTML a également été retiré puisqu'il est désormais redondant)
Enfin, stylisez votre composant en modifiant DynamicParameterCheckbox.less, à l'aide de l'extrait de code ci-dessous.
DynamicParameterCheckbox.less
Votre dynamic-parameter a maintenant une belle apparence, mais il ne fonctionne pas encore correctement.
Il y a un problème, vous ne pouvez cocher aucune case !
La raison est que vous devez lier CheckboxGroup à notre composant dynamic-parameter. Pour ce faire, vous devez ajouter un tableau à l'état de votre composant. Il gardera une trace des options sélectionnées, alors nommez-le selectedOptions :
Ajoutez une fonction onChange pour mettre à jour le tableau que vous venez de définir :
Enfin, vous devez ajouter les deux propriétés (onChange et value, un tableau contenant selectedOptions) à CheckboxGroup. Liez-les en modifiant l'instruction return :
La dernière étape consiste à lier ce dynamic-parameter au store global redux pour lui permettre d'affecter les requêtes des graphiques. Nous allons utiliser les hooks React Redux pour une approche plus moderne et rationalisée. Ajoutez ces lignes aux imports en haut du fichier :
Ensuite, à l'intérieur de votre composant fonctionnel DynamicParameterCheckbox, accédez à l'état Redux et à la fonction dispatch à l'aide des hooks. Placez ces lignes à l'intérieur de la fonction de votre composant :
-
useSelector: ce hook vous permet d'extraire des données de l'état du store Redux. Ici, nous récupérons la valeur associée à props.id depuis la partie querystring de votre état Redux. Cette variable options se mettra automatiquement à jour à chaque fois que l'état Redux change pour cet ID spécifique. -
useDispatch: ce hook renvoie une référence vers la fonction dispatch du store Redux. Vous utiliserez cette fonction dispatch pour envoyer des actions afin de mettre à jour le store.
À l'intérieur de votre composant fonctionnel DynamicParameterCheckbox, créez une fonction utilitaire updateModel pour envoyer vos actions au store global :
Cette fonction utilise maintenant la fonction dispatch obtenue depuis useDispatch pour envoyer l'action set, mettant à jour la querystring dans le store Redux.
Ensuite, mettez à jour votre fonction onChange pour simplement appeler updateModel avec les nouvelles options :
Pour vous assurer que l'état interne de votre composant (selectedOptions) est synchronisé avec l'état du store Redux (notamment après un rafraîchissement de page ou des changements externes à l'état Redux pour ce paramètre), mettez à jour votre hook useEffect comme suit :
Ce hook useEffect s'exécutera chaque fois que la valeur options (qui provient directement de votre store Redux via useSelector) change. Il maintient l'état local selectedOptions de votre composant synchronisé avec l'état Redux global, offrant une vue cohérente du paramètre dynamique.
Votre paramètre dynamique est maintenant connecté au store global. Vous pouvez vous en assurer car les graphiques connectés à dynamic-weekday sont affectés par ce paramètre dynamique.
Vous avez créé votre premier paramètre dynamique personnalisé.
Le code final est disponible ici.
Ajouter une barre de recherche
Ajoutons un second paramètre dynamique pour pouvoir filtrer par station.
Générez un nouveau composant :
Sélectionnez le générateur component. Nommez-le DynamicParameterAutocompleteBox et répondez « No » à la dernière question.
Remplacez le contenu du fichier .jsx nouvellement généré par ceci :
DynamicParameterAutocompleteBox.jsx
Déclarez-le dans src/components/index.js
en important votre nouveau composant et en l'ajoutant à l'objet components défini dans le fichier.
Allez dans config/dashboards/rides-analytics.json, cherchez le panel dont l'id est search-bar et remplacez-le par un dynamic-parameter comme suit :
Enfin, retirez tout l'objet dyn-stations de config/menus/sidebar.json, car il est redondant avec la nouvelle barre de recherche.
Utiliser un composant personnalisé comme graphique
Dans cette section, vous apprendrez à créer un composant personnalisé et à l'utiliser comme graphique.
À titre d'exemple, vous allez créer un composant de carte interactive à l'aide de la bibliothèque react-leaflet. Le résultat final ressemblera à ceci :
Commençons par créer le composant à l'aide du script, comme d'habitude.
Sélectionnez le générateur component, nommez-le ChartMap et répondez « No » à la dernière question.
Il est important que le nom de votre composant de graphique commence par 'Chart', afin qu'il soit reconnu et enregistré correctement.
Déclarez-le dans src/components/index.js.
Vous pouvez maintenant l'utiliser dans votre dashboard analytics. Allez dans rides-analytics.json, et ajoutez le nouveau graphique ainsi que son titre au panel custom-map :
Comme les dynamic-parameters, les graphiques reçoivent également automatiquement certaines propriétés lors de leur montage. Voyons à quoi elles ressemblent.
Comme d'habitude, importez useEffect et useState en modifiant la première ligne du fichier ChartMap.jsx :
Ajoutez ensuite props aux arguments du composant fonctionnel :
Enfin, ajoutez un hook useEffect à l'intérieur de cette fonction, juste avant l'instruction return.
Votre composant fonctionnel final devrait ressembler à ceci :
Ouvrez le panneau console de votre navigateur, vous devriez pouvoir voir les props transmises à ce composant.
La plupart de ces props proviennent de la définition du graphique dans config/dashboards/rides-analytics.json.
L'exception est data, qui est un JSON représentant le résultat de la requête associée au graphique. Ce JSON se veut aussi générique que possible, il peut donc être un peu fastidieux à manipuler.
Dans cet exemple -- et dans la plupart des cas -- l'objet JSON est trop complexe, nous utilisons donc cette fonction utilitaire pour l'aplatir et le rendre bien plus facile à manipuler :
Copiez-collez l'extrait de code ci-dessus entre les imports et ChartMap, puis mettez à jour le contenu de votre hook useEffect pour visualiser les nouveaux résultats aplatis :
Pour afficher ces résultats sur la carte, vous devez stocker ces données dans l'état du composant. Déclarez un tableau à l'intérieur du composant ChartMap comme ceci :
Mettez à jour useEffect pour modifier ce tableau au lieu de journaliser les résultats :
Maintenant que vous avez préparé les données, voyons comment créer la carte.
Importez maintenant les composants react-leaflet en ajoutant cette ligne en haut de votre fichier :
Allez dans ChartMap.less et modifiez la feuille de style à l'aide de l'extrait de code ci-dessous :
ChartMap.less
Retournez dans ChartMap.jsx et définissez vos paramètres de carte par défaut (center, zoom, minZoom) juste en dessous de votre state :
Modifiez l'instruction return de votre fonction pour afficher une carte vide centrée sur Chicago :
Ajoutez maintenant des circle markers à l'intérieur de LeafletMap, juste en dessous du TileLayer, pour représenter les stations :
Vous pouvez personnaliser vos circle markers en ajoutant des props pour contrôler leur taille, leur épaisseur, leur couleur, etc. Vous pouvez trouver la documentation complète ici
Ci-dessous, un extrait de code qui change la couleur des cercles et rend leur taille proportionnelle au nombre de trajets.
Ensuite, ajoutez un popup pour afficher le nom de la station et le nombre de trajets qui lui sont associés lors du clic sur un cercle.
Ajoutez-le à l'intérieur de CircleMarker comme indiqué ci-dessous :
Vous pouvez faire en sorte que le nombre moyen de trajets suive les règles de formatage spécifiées dans config/formatter.json pour rides, en utilisant FpMeasure.
Importez FpMeasure :
Modifiez la valeur du popup :
Si vous jouez un peu avec votre carte, vous remarquerez qu'elle continue de se recharger lorsque vous changez vos paramètres dynamiques. Vous pouvez désactiver ce comportement en ajoutant une propriété noReload dans les options de configuration de votre graphique, dans config/dashboards/rides-analytics.json :
Réorganisez vos cercles par clusters pour éviter les chevauchements ; c'est assez simple grâce à la bibliothèque react-leaflet-markercluster.
Importez le composant MarkerClusterGroup :
Puis enveloppez vos circle markers dans MarkerClusterGroup comme ceci :
Vous avez créé votre premier composant personnalisé.
Le code final est disponible ici.
Pour en savoir plus sur la création de vos composants personnalisés, consultez le Guide technique !
Publier votre application locale sur la Data Platform
Maintenant que vous avez terminé votre application en local, il est temps de la connecter à la platform.
Vous pouvez le faire soit en chargeant l'application sous forme de fichier zip, soit en la connectant à un repository git.
Importer votre application en tant que fichier zip
Tout d'abord, vous devez exporter votre application au format zip. Votre fichier zippé ne doit pas contenir les dossiers suivants : node_modules, forepaas, webpack, .git.
Vous pouvez également utiliser notre script préconstruit pour zipper votre application ; pour générer un fichier zip prêt à être chargé sur votre Projet, exécutez simplement cette commande.
Un fichier zip portant le même nom que le dossier de votre application sera généré.
Ensuite, vous pouvez soit créer une nouvelle application à l'aide de ce fichier .zip en suivant ces étapes, soit modifier une application existante et charger le fichier zip pour créer une nouvelle version de votre application :
Connecter votre application à un repository git
Pour relier un repository git à la platform, veuillez suivre ce guide.
Une fois votre application chargée, buildez-la puis déployez-la.
Votre superbe application est maintenant déployée sur la Data Platform !
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.