Préambule
- Ce TP permet de créer son premier projet vuejs avec vue-cli et de comprendre l'organisation générale d'une application SPA créée via vue-cli.
- Le contexte est celui d'un savant fou, Dr Mad, qui peut acheter des virus dans une boutique spécialisée, les triturer dans son laboratoire, et revendre ses inventions sur le dark web.
- Ce TP permet également de découvrir quelques éléments basiques de la syntaxe vuejs en écrivant quelques composants simples.
- A noter que certaines parties du sujet consiste à copier/coller du code dans certains fichiers, sans fournir d'explications détaillées. Dans ce cas, celles-ci seront données lors des cours dédiés à la syntaxe vuejs ou aux plugins.
- En conclusion, ce TP est plutôt un tutoriel de découverte qu'un véritable exercice.
0°/ Installer l'environnement de développement
- Si ce n'est déjà fait, installer node, npm, serve. Pour cela, consulter l'article : support : Installation de node,serve & config. idea
1°/ Créer le projet avec vite + vue-router + pinia
1.1°/ Créer un canevas de base
- Dans un terminal, taper : npm create vue@latest
- Dans le premier menu, taper le nom du projet : drmad
- Dans le menu suivant, utilisez les flèches et la barre d'espace pour sélectionner les plugins router et pinia, comme suivant ;
|
Vue.js - The Progressive JavaScript Framework |
- Appuyez directement sur entrée pour passer les options expérimentales, puis sélectionner Yes pour créer un projet vierge, comme suivant :
|
Vue.js - The Progressive JavaScript Framework |
- Ensuite, vite va créer un répertoire drmad,
- Allez dans le répertoire drmad puis lancez npm install pour télécharger les modules node nécessaires au projet.
- Il y a notamment :
- package.json : fichier décrivant les différent modules nodejs utilisés, leur dépendances et certaines options de configuration.
- node_modules : où est stocké le code des modules.
- src : les sources de l'application.
- Sauf exception, on a besoin d'intervenir uniquement sur les fichiers de src.
- src contient :
- App.vue : décrit la page principale de l'application. Le fichier est structuré comme tous les fichiers .vue, avec une partie <template> décrivant le html, une partie <script> contenant du javascript et notamment tout ce qui est associé à vuejs (data, methods, ...), et enfin une partie <style> avec le CSS pour formater l'affichage.
- main.js : crée l'instance de vue. On modifie ce fichier quand on veut ajouter à la vue des modules/plugins après la création (par ex, vue-router, vuetity, ...).
- router : le répertoire contenant le fichier de définition des "routes" de l'application. ATTENTION ! Ce ne sont pas les routes que l'on pourrait utiliser pour faire des requêtes à une API. Il s'agit de routes "internes" à l'application, c.a.d. ce qui permet de passer d'une partie de l'application à une autre.
- stores : le répertoire contenant le définition du dépôt central de données. En effet, l'application est construite en assemblant des composants. Quand ceux-ci doivent manipuler des données en commun, la meilleure solution consiste à utiliser un tel dépôt. En effet, en vuejs basique (donc sans vuex), il est facile de passer des données entre un composant père et un fils, mais c'est plutôt fastidieux de le faire entre des frères, cousins, ...
1.2°/ Tester le projet
- Pour vérifier que tout est en place, il suffit de lancer la compilation et le serveur de test : npm run dev
- Par défaut, le serveur web de test est configuré pour que l'URL de l'application soit : http://localhost:5173
- Utiliser un navigateur pour vérifier que l'application est accessible.
- Si tout est Ok, arrêter le serveur de test (ctrl+c)
1.3°/ Passer le projet sous Idea
- Pour cela, consulter le chapitre 3 de l'article : support : Installation de node, serve & config. idea
- Si vous avez suivi correctement les indications, un clic sur la flèche verte permet de compiler le projet et lancer un serveur de test (NB : ça lance la commande npm run dev).
- Vous pouvez laisser le serveur tourner : chaque fois que vous modifierez les sources, idea compilera de nouveau le projet et s'il n'y a pas d'erreur, la page du navigateur sera réactualisée.
2°/ Compléter la structure du projet
- Comme dit en cours, une application SPA bien conçue permet de développer le front-end indépendamment du back-end.
- Cela implique deux choses préalable au développement :
- créer/avoir une source de données "locale" à l'application, c.a.d. qui ne nécessite pas de faire des requêtes à un serveur (par ex, une API) pour les obtenir.
- définir précisément le format des données que le front va envoyer/recevoir du back si celui-ci était implémenté. A l'heure actuelle, on utilise généralement des objets JSON (ou des tableaux d'objets)
- Pour le premier point, il n'est pas possible d'utiliser un fichier ou une BdD locale sur la machine qui fait tourner l'application. En effet, celle-ci s'exécute dans un navigateur, qui n'a donc pas accès aux ressources de la machine. La seule solution consiste a inclure les données dans l'application, par exemple en écrivant un fichier JS avec plein de tableau de données, qui sera inclut lors de la compilation.
- Pour le second point, cela consiste à définir le protocole de communication entre le front et le back. Il n'y a pas de méthode absolue pour créer ce protocole. Cependant, la méthode proposée est ce qui se rapproche le plus d'une solution universelle, facilement exploitable et réutilisable pour n'importe quel projet.
- Une fois ces deux points acquis, il est ensuite possible de créer des fonctions dites de "service" qui vont simuler les futurs accès à l'API, mais en utilisant les données locales. Comme le reste de l'application se base uniquement sur ces fonctions, il devient très facile de changer l'application pour qu'elle interroge l'API au lieu de la source locale.
2.1°/ Créer la source de données "locale"
- Comme indiqué ci-dessus, ce TP n'utilise pas une (ou des) API comme source de données. Celle-ci va être locale, sous la forme d'un fichier JS importé dans les fonctions de service.
- Le problème principal d'un fichier vient du fait que l'application finale va envoyer des requêtes pour obtenir des données, mais également pour mettre à jour des données.
- Or, on ne peut pas écrire dans un fichier du côté front-end (en principe). En revanche, rien n'empêche que ce fichier crée initialement des objets en mémoire et contienne des fonctions de manipulation de ces objets.
- Ces fonctions sont exportées et donc accessibles aux services.
- Au final, il y aura donc 2 ensembles d'objets : un représentant la source de données (dans un fichier), un représentant les données manipulées par l'application à un instant t (en mémoire)
- Mais quand l'API sera pleinement opérationnelle, il ne restera plus que le second ensemble.
- L'inconvénient de cette technique est qu'il faut créer des objets et que cela peut être fastidieux, surtout si on écrit directement en JSON.
- Pour faciliter cette tâche, on peut créer des classes représentant ces objets pour ensuite les instancier, ce qui rend le code un peu plus lisible.
- Le second inconvénient est qu'il faut en gros créer des données qui ont à peu près le même format que celles qui sont stockées sur la BdD de l'API, mais sans aller chercher/mettre à jour dans cette BdD. C'est donc du travail en plus.
- Pour ce TP, créer la source locale consiste à télécharger le fichier [ datasource.tgz ] dans src, puis la décompacter. Cela crée un sous-répertoire datasource, avec dedans le fichier data.js,
- Ce dernier contient différents tableaux avec des données "brutes", c.a.d. comme celles qui pourraient être en BdD côté back.
2.2°/ Le protocole d'échange entre front et back
- Si le cahier des charges de l'application est complètement défini, il est possible de faire une liste de toutes les requêtes que le front va pouvoir faire au back pour obtenir des données.
- Cela implique de définir :
- quels sont les paramètres de ces requêtes, donc quelles données envoie les front pour que le back puisse traiter la requête.
- quel est le format de la réponse du back, en cas de succès de la requête, MAIS également en cas d'erreur.
- Généralement, on essaie de définir des format de réponse qui soient unifiés, afin de simplifier l'écriture du front, notamment pour détecter le succès ou échec d'une requête.
-
Le système le plus simple et universel pour mettre cela en place consiste un objet JSON avec une structure globale unique, du type : { error: code_erreur, status: code_status, data: données } avec :
- error :valeur représentant le code de l'erreur (ou 0 si pas d'erreur)
- status : valeur représentant le statut de la requête, qui sert de deuxième information sur le traitement de la requête. Dans le cas d'une API REST via http, status est souvent initialisé avec le statut http de la requête, par exemple 200, 201, 400, 404, etc. L'application émettrice de la requête peut se servir ou non de cette information pour réagir au résultat de la requête.
- data : les données demandées s'il n'y a pas d'erreur, ou bien un message/objet d'erreur, si code_erreur est différent de 0.
- C'est ce principe qui est utilisé pour ce TP.
- Cependant, quand la requête est un succès, il faut tout de même définir quel est le format du champ data, pour que le front sache récupérer les données demandées correctement.
- Cela permet également d'écrire les fonctions de service afin qu'elles puissent renvoyer des données selon ce même format, en partant de celles qui se trouvent dans la source locale.
2.3°/ Les services d'accès aux données.
- Comme dit ci-dessus, le principe est d'écrire des méthodes qui vont renvoyer des données au même format que celle de l'API, MAIS soit en allant chercher ces données dans un fichier (NB : il est également possible de les générer à la demande)
- Quand l'API sera fonctionnelle, on pourra remplacer ces méthodes par celles qui vont faire les requêtes sur l'API de façon transparente.
- Pour mettre en place ce mécanisme, tout en prévoyant de pouvoir accéder à l'API, on définit des services d'accès aux données.
- La première étape est de créer un répertoire dédié aux services.
- Pour cela, dans src, créez un sous-répertoire nommé services.
- La deuxième étape est de créer un (ou plusieurs) fichier avec des fonctions qui vont "simuler" toutes les requêtes prévues à l'API.
- Chaque fonction accède à la source locale pour récupérer des données, les met en forme avec la structure qui a été déterminée en 2.2, et retourne le résultat.
- Pour ce TP, seules 4 requêtes sont utilisées :
- se loguer,
- récupérer une liste de virus,
- récupérer le solde d'un compte bancaire,
- récupérer les transactions d'un compte bancaire.
- Cela implique de créer un fichier avec 4 fonctions renvoyant les données au bon format.
- Ce fichier est écrit en partie (2 fonctions sur les 4)et téléchargeable : [ localsource.service.js ] (NB : clic bouton droit pour pouvoir télécharger)
- Une fois téléchargé, déplacez-le dans le répertoire services.
|
ATTENTION : le fait d'utiliser une source locale en mémoire a des effets de bord qui n'existent pas avec une source distante et qui peuvent conduire à des comportements étranges, tels que la non-réactivité de l'application malgré des modifications de ses données. Cela arrive quand l'application utilise directement les objets de la source locale pour modifier leur valeur (mais pas si on se contente de lire leur valeur). Pour éviter ces comportements, il faut coder les fonctions de localsource.service.js d'une façon bien précise : elles ne doivent jamais renvoyer directement les objets créés dans data.js MAIS créer de nouveaux objets, soit en clonant ceux qui existent, soit en prenant juste les informations nécessaire. Par exemple, la fonction shopLogin() ne renvoie pas un objet tel que stocké dans le tableau shopuser de data.js. Elle construit et renvoie un nouvel objet en initialisant juste les champs nécessaires. En revanche, la fonction getAllViruses() contrevient à ce principe. Cependant, comme l'application ne va jamais modifier le contenu des objets se trouvant dans le tableau items de data.js, cela ne pose pas de problème. Cela reste tout de même risqué si l'application évolue et que l'on doive finalement faire des modifications de ce tableau. |
- La dernière étape est d'écrire des fonctions qui vont jouer le rôle d'interface entre le reste de l'application et la source locale.
- En effet, les fonctions de localsource.service.js NE DOIVENT JAMAIS être appelées par les composants de l'application. Ceux-ci doivent obligatoirement passer par d'autres fonctions de service, indépendante du type de la source de données (locale ou API).
- Pour améliorer la maintenance du code, on créer généralement autant de fichiers de service qu'il y a de domaines de fonctionnalités.
- Dans ce TP, il y a deux domaines : la boutique de virus et les comptes bancaires, d'où la création de 2 fichiers :
- téléchargez : [ shop.service.js ] (NB : clic bouton droit pour pouvoir télécharger) puis déplacez-le dans services.
- créez dans services un fichier vide : bankaccount.service.js
- Ces deux fichiers seront complétés au fur et à mesure du TP, mais le premier contient déjà un exemple de comment écrire un triplet de fonctions pour chaque requête en vue d'obtenir des données. Par exemple, dans shop.service.js :
- getAllVirusesFromLocalSource() qui va chercher des données dans la source locale, grâce à la fonction définie dans localsource.service.js
- getAllVirusesFromAPI() qu'il faudra écrire et surtout utiliser quand l'API sera fonctionnelle
- getAllViruses() qui appelle l'une ou l'autre fonction et qui, en l'absence d'erreur, va renvoyer le résultat.
- Il y a exactement le même triplet pour les fonctions permettant de se loguer à la boutique.
- L'explication détaillée de comment écrire ces méthodes est donnée en section 4.
2.4°/ Remarque sur la structuration des données pour le front (pour information car non utilisé dans ce TP)
- Une application SPA peut assez fréquemment faire appel à une API qui renvoie plus de données que nécessaire pour le front, ou bien différentes API qui utilisent différentes structurations des données renvoyées.
- C'est presque toujours le cas quand on n'écrit pas soi-même les APIs que le front va utiliser.
- Ces différences de format peuvent être source de bug assez facilement, surtout si les API sont modifiées par la suite.
- C'est pourquoi on fait du découplage avec un front qui utilise sa propre structuration des données.
- Pour mettre en place ce découplage, il existe plusieurs solutions. La plus efficace et ouverte nécessite :
- que l'on définisse des classes pour représenter les données manipulées en interne par le front,
- que ces classes contiennent des méthodes permettant de "convertir" des données JSON reçues en objets, et inversement.
- que l'on extrait de ces objets les données nécessaires pour interroger les API. Cela peut se faire à différents endroits du code, par exemple dans le store ou encore dans les fonction de service.
- L'autre avantage d'écrire des classes est que l'on peut définir dans ces classes des méthodes de manipulation de ces objets, notamment pour mettre à jour leurs attributs.
- Cela est utile notamment quand la modification d'un objet ne nécessite pas de faire immédiatement une requête à l'API pour sauvegarder le changement.
3°/ Une première application
3.1°/ Objectif
- L'objectif de cette version est de pouvoir afficher :
- une page contenant la liste des virus disponibles à la vente
- une page permettant de se loguer à la boutique
- L'affichage de l'une ou l'autre est pilotée grâce à vue-router, en fonction de "routes" (c.a.d. l'URL) que l'on utilise. En l'occurrence, si on tape comme URL :
- localhost:8080/shop/items, on affiche la liste des items en vente, c.a.d. des virus,
- localhost:8080/shop/login, on affiche un formulaire de login classique et en dessous, les informations de l'utilisateur si l'authentification est correcte.
- Pour réaliser cet objectif, il faut écrire un fichier pour configurer vue-router à cet effet.
- En effet, il est possible dans une application vue d'utiliser un principe de "routage", basé sur l'URL demandée, pour afficher tel ou tel composant dans le navigateur.
- C'est possible puisque dans une application SPA, l'URL peut changer sans pour autant que cela provoque une nouvelle demande de page au serveur.
- Dans ce TP, toutes les données sont en mémoire, via l'import des tableau de data.js
- L'application récupère ces données grâce aux méthodes de service exportées par shop.service.js et bankaccount.service.js
- Les questions fondamentales sont :
- où appelle-t-on ces méthode de service ?
- où va-t'on stocker ce que l'on récupère ?
- Réponse aux 2 questions :
- soit dans chaque composant devant manipuler des données,
- soit dans un dépôt central de données (= un store)
- Choisir entre les 2 solutions est simple :
- si des données ne sont manipulées que par un seul composant de l'application, on peut stocker dans les données locales du composant
- sinon, on stocke dans un store.
- Dans ce TP, on va utiliser le store pour tout stocker, mais dans une application réelle, le store pourrait contenir bien moins d'informations.
- Il existe plusieurs plugins vuejs pour créer un store mais le plus versatile est pinia. C'est pour cela que le projet a été créé avec le plugin déjà intégré.
3.2°/ Mise en place initiale
- en étant à la racine du projet, installer le module js uuid : npm install uuid
- télécharger l'archive [ vuejs-tp1-canevas.tgz ] dans le répertoire src, puis décompactez-la.
- cette archive va créer/écraser les fichiers suivants :
- App.vue
- views/ShopLoginView.vue et views/VirusesView.vue
- router/index.js
- stores/shop.js
- Si vous avez fait correctement ces étapes, Idea devrait recompiler les nouvelles sources sans erreur.
- La page centrale affiche un message de bienvenu.
- Vous pouvez tester les URLs indiquées plus haut :
- localhost:8080/shop/items,
- localhost:8080/shop/login. Rq : si vous tapez un login incorrect, un message d'erreur apparaît dans la console de l'inspecteur.
Quelques explications sur ces fichiers :
stores/shop.js :
- un store est créé grâce à l'intégration du plugin pinia dans le projet.
- C'est un objet avec différents attributs permettant de créer un "dépot" centralisé de données, accessible à tous les composants.
- Pour éviter d'avoir un énorme fichier store illisible, on créer généralement plusieurs fichiers qui centralisent chacun une partie des données, pour un des "domaines fonctionnels" de l'application.
- C'est pourquoi ce TP utilise deux stores puisqu'il y a deux domaines : la boutique et la banque.
- Il existe différentes syntaxes pour créer un store pinia mais la solution la plus pertinente est d'utiliser celle qui est similaire à ce que l'on trouve dans <script setup> des composants :
- on utilise la fonction defineStore() (fournie par pinia), à laquelle on passe en paramètre un nom pour le store, ainsi qu'une fonction qui définit le contenu du store.
- pour écrire le contenu de cette fonction :
- on définit un "state", à savoir les variables locales du store, grâce à la fonction ref(). Contrairement aux variables locales des composants, ces variables de store seront quand même accessibles par tous les composants de l'application.
- on utilise computed() pour définir des variables dont la valeur est calculée à partir des variables locales, ou d'autres variables computed.
- on définit des fonction pour faire des traitement qui vont mettre à jour les variables locales. A noter que ces fonctions peuvent être asynchrones (par ex, pour appeler une API)
- defineStore() renvoie une fonction d'accès au store, qui est exportée et donc utilisable dans les composants de l'application. NB : on peut nommer cette fonction comme l'on veut mais l'usage est d'utiliser un nom du type useXXXStore.
- NB : les fonctionnalités basique et avancées de pinia seront abordées dans un cours dédié
router/index.js :
- le routeur est créé grâce à l'intégration du plugin vue-router dans le projet.
- ce routeur est configuré grâce au contenu du fichier index.js, qui définit des "routes".
- une route est, au minimum, définie par un chemin (comme ceux pour accéder à un fichier), par exemple /shop/items, et un composant qui va être inséré dans le DOM lorsque l'on "suit" la route.
- le composant sera inséré dans l'application à l'endroit où se trouve la balise <router-view>. En l’occurrence, cette balise est placée dans le template de App.vue.
- de ce fait, on a l'impression que l'application est multi-page, comme en PHP, alors qu'en fait, il n'y a qu'une seule page (SPA) dont on change certaines parties en fonction de la route suivie.
- Par exemple, si on analyse le fichier index.js, on voit que demander au navigateur l'URL localhost:8080/shop/items va déclencher la création d'une instance du composant VirusesView et son insertion dans le DOM à la place de la balise <router-view> utilisée dans App.
- S'il y avait déjà un composant inséré à cet emplacement, il est détruit et remplacé par le nouveau.
- NB : les fonctionnalités basique et avancées de vue-router seront abordées dans un cours dédié
App.vue :
- à la fin du template, il y a une balise <router-view>. Comme indiqué ci-dessus, cela indique à vue-router l'emplacement où il doit insérer un composant en fonction de la route suivie.
- useShopStore() (importé au début de <script>) est la fonction exportée par le store shop.js. Cette fonction renvoie un objet (mis ici dans une variable shopStore) permettant d'accéder à tout le store directement.
- Pour utiliser les éléments du store, il suffit d'utiliser cette variable suivie du nom de l'élément, que l'on soit dans le template ou dans le script.
- Par exemple, a la fin, on utilise onMounted()pour appeler la fonction du store qui récupère la liste des virus et la stocke dans le store. Pour cela, il suffit d'appeler shopStore.getAllViruses().
3.3°/ Affichage du solde d'un compte bancaire
NB : cette partie est à réaliser en autonomie et vous devez intervenir sur plusieurs fichiers, certains devant être créés, d'autres seulement modifiés.
localsource.service.js :
- importer le tableau bankaccounts (exporté par data.js),
- compléter la fonction getAccountAmount(number). Le paramètre number est une chaîne de caractère représentant l'identifiant d'un compte( cf. champ number dans data.js). Elle doit :
- vérifier que number est défini, non vide. Sinon, elle renvoie un objet d'erreur (comme dans shopLogin() )
- vérifier que number existe dans bankaccounts et si oui, renvoyer un objet dont error = 0, et data contient la valeur du champ amount. Sinon, elle renvoie un objet d'erreur
- ajouter cette fonction à l'export.
bankaccount.service.js (à remplir) : il faut écrire un code très similaire à celui de shop.service.js, avec comme différences :
- définir les fonctions getAccountAmountFromLocalSource(number) et getAccountAmout(number).
- la première fait appel à LocalSource.getAccountAmount(number).
- la deuxième appelle la première et renvoie soit un résultat, soit un objet d'erreur (comme dans getAllViruses() ),
- exporter getAccountAmount().
stores/bank.js (à créer en s'inspirant de shop.js):
- importer le service des comptes bancaires (par ex, sous le nom BankService),
- ajouter dans le state une variable accountAmount, initialisée à 0,
- en s'inspirant de getAllViruses(), ajouter dans actions une fonction getAccountAmount() qui utilise BankService.getAccountAmount()afin de récupérer le solde d'un compte bancaire
views/BankAccountView.vue (à créer) :
- copier/coller le code de ShopLoginView
- modifier script pour :
- définir une variable locale number servant à stocker la valeur d'un champ de saisie,
- mettre en place l'accès au store de bank.js, grâce à un variable bankStore.
- modifier template pour :
- n'avoir qu'un seul champ de saisie, pour mettre l'identifiant du compte (dans nimber)
- quand on clique sur le bouton, appeler la fonction bankStore.getkAccountAmount()
router/index.js :
- en s'inspirant de la route /shop/login, ajouter une route /bank/account qui permet d'afficher le composant BankAccountView.
- Si vous avez écrit correctement ces différents codes, l'URL localhost:8080/bank/account devrait permettre d'afficher le formulaire et si vous fournissez un id correct, d'afficher le détail du compte.
3.4°/ Affichage des transactions liées à un compte bancaire
NB : cette partie est à réaliser en autonomie et vous devez modifier plusieurs fichiers.
L'objectif est de modifier BankAccountView afin de lister les transactions liées à un numéro de compte. Cela impose :
- de modifier localsource.service.js pour compléter la méthode qui récupère les transactions à partir d'un numéro de compte,
- de modifier bankaccount.service.js pour définir les fonctions qui vont appeler celles de localsource.service.js
- de modifier store/bank.js pour ajouter un champ de type tableau (initialisé vide) dans le state (par exemple nommé accountTransactions), ainsi que la fonction permettant de le mettre à jour via une fonction de service.
- de modifier le template de BankAccountView pour ajouter un bouton qui va utiliser l'action dans le store pour chercher les transactions (au lieu du solde), et afficher celles-ci sous forme de liste à puce (cf. VirusesView pour un exemple), uniquement s'il existe des transactions (cf. ShopLoginView et le v-if comme exemple)
Remarque : cette fonctionnalité ne nécessite pas de nouvelle route puisque c'est au travers d'interaction avec les boutons de BankAccountView que l'on peut charger les données qu'il affiche.
4°/ Conclusion
- On remarque que la structure générale de l'application permet d'ajouter facilement des fonctionnalités de manière incrémentale. Qui plus est, on part souvent de code existant qui peut être copié/modifié pour les développer.
- Sans une structuration de ce type et les plugins utilisés, le développement du front serait moins découplé de celui du back, l'apparition conditionnelle des composants serait compliquée à mettre en place, et la gestion des données partagées entre composants serait plus que fastidieuse.
- Il n'y a au final que l'aspect purement graphique qui manque à cette première application. Pour cela, on utilise des plugins proposant des composants graphiques plus ou moins complexes, comme par exemple vuetify, qui sera abordé dans un cours dédié.