3.32 Procédures-règles de l'application Angular

3.32.1 - Recréer un workspace Angular avec des applications et un librairie commune

Les informations/documentations/sources utiles :

Les commandes à exécuter :

  • pour initialiser le workspace : ng new frontend --createApplication=false --directory=frontend --interactive=false
  • pour créer un projet : ng generate application etatcivil --style=scss --routing=false
  • ajouter Material au projet : ng add @angular/material --project=etatcivil
  • pour créer une librairie : ng generate library framework
  • pour déclarer un service partagé :
    • il est possible d’utiliser la commande : ng generate service validation --project=framework
    • attention à ne pas faire apparaitre le service dans le module de la librairie mais d’utiliser l’anotation @Injectable({ providedIn: 'root' }) (cf. documentation de l’anotation @Injectable)

3.32.2 - Créer une nouvelle application de démarche

Les étapes à réaliser pour créer une application de démarche sont :

  • créer l’application Angular
    • modifier le fichier package.json et remplacer xxxxxx par le code de la démarche (en minuscule) dans la commande creationDemarche
    • exécuter la commande npm run creationDemarche (ou yarn à la place de npm)
    • remettre le code xxxxxx dans la commande creationDemarche dans le package.json
    • sur le modèle des commandes existantes, dans le package.json, en respectant l’ordre alphabétique
      • créer les commandes xxxxxx-start, xxxxxx-startcoverage, xxxxxx-build-prod, xxxxxx-compodoc et xxxxxx-analyseBundle
      • ajouter ces commandes dans les all-*
      • (les commentaires dans ce json sont obligatoires et sur le modèle "//commande : mon commentaire":"")
    • dupliquer un fichier assembly/xxxxxx-assembly.xml et en personnaliser le contenu avec le code de la démarche
    • éditer le pom.xml du projet front pour
      • y ajouter l’exécution gitInfos-xxxxxx sur le modèle des existants
      • y ajouter l’exécution zip-xxxxxx sur le modèle des existants
    • déclarer le nouveau répertoire de source dans le fichier tsconfig.json à la racine du projet front
  • pour initialiser l’application Angular
    • supprimer, s’ils existent, les fichiers src/favicon.ico et src/app/app-routing.module.ts
    • dupliquer le fichier tsconfig.doc.json présent à la racine d’un autre projet dans ce nouveau projet
    • dans le fichier angular.json, trouver le nouveau projet puis
      • trouver ses 2 attributs styles pour y mettre le même contenu que celui des autres projets (au delta du code de la démarche)
      • trouver ses 2 attributs assets pour y mettre le même contenu que celui des autres projets (au delta du code de la démarche)
      • trouver l’attribut schematics pour y mettre le même contenu que celui des autres projets
      • recréer la partie build-coverage à la place de la partie test
      • ajouter les éléments nécessaires pour que la configuration de la démarche soit identique (au code de démarche près) aux autres (trop de modifications et trop changeante pour être listées ici)
    • dans le répertoire projects/nouvelleDemarche,
      • supprimer le fichier .eslintrc.json
      • supprimer les fichiers tsconfig.spec.json et src/app/app.component.spec.ts
      • récupérer la page index.html d’une autre démarche en changeant le contenu de la balise title et la balise base
      • récupérer le répertoire des fichiers d’environnement (src/environments) en remplaçant le code de la démarche
      • récupérer le composant app.component dans son ensemble (TS et HTML) depuis une autre démarche (etatcivil par exemple) sans oublier de retirer du HTML le code des pages spécifiques (etatcivil n’en a pas)
      • récupérer le app.module depuis une autre démarche en en retirant les spécificités de la démarche (s’il y en a)
      • récupérer le répertoire cypress à la racine d’un autre projet (autre qu’edition), le dupliquer dans la nouvelle démarche
      • remplacer le code de la démarche dans le fichier src/cypress/e2e/e2e.cy.ts
  • configurer la démarche
    • créer la configuration publique de la démarche dans le fichier assets/bouchonapi/param.json du code Angular de la démarche (nom à définir en cohérence avec celui indiqué dans le fichier e2e.cy.ts)
    • supprimer le fichier src/assets/.gitkeep (qui ne sert plus à rien car un répertoire existe maintenant)
    • créer un brouillon dans le répertoire assets/bouchonapi du code Angular de la démarche
    • créer la configuration privée de la démarche dans le répertoire 2-code/socle/socle-dbconfiguration/src/test/resources/db (ainsi que les templates de document à générer)
  • tester
    • supprimer le contenu de la base de données avec la commande . ./outils.sh PURGE DB (qui supprime le répertoire 2-code/socle/.embedmongo avant de démarrer la base de données MongoDB du socle (pour forcer l’initialisation)
    • depuis les logs de démarrage de la base de données, vérifier que le nombre de configurations publiques, de configurations privées et de templates de document sont bien insérés
    • démarrer la démarche avec la commande npm run xxxxxx-start (ou yarn à la place de npm)
    • la démarche doit être fonctionnelle
    • arrêter l’application
    • activer tous les bouchons
    • démarrer l’application avec la commande npm run xxxxxx-startcoverage (ou yarn à la place de npm)
    • démarrer les tests E2E avec la commande npm run e2e (ou yarn à la place de npm)
  • documenter la démarche
  • vérifier la cohérence de la démarche vis-à-vis des autres : exécuter la procédure du chapitre suivant
  • dans le code Java, dans le projet socle-soumission, dans les classes SoumissionReelleServiceTest et GenerationServiceDepuisSourcesFrontTest, sur le modèle des tests existants, créer un test pour réaliser une soumission avec la configuration et les données du brouillon de la nouvelle démarche
  • dans le projet IAS, dans le répertoire 2-code\ias\ansible, déclarer la nouvelle démarche dans :
    • le playbook 03-deployer.yml sur le modèle de celui d’arnaqueinternet (en respectant l’ordre alphabétique)
    • dans le fichier de variables de chaque inventaire (fichier inventory/*/group_vars/all/default.yml), ajouter la nouvelle démarche dans les variables applications_web_front et version_front

3.32.3 - Vérifier la cohérence d’une démarche

Cette procédure ne s’applique au pied de la lettre que pour les démarches sans code spécifique. Elle permet de vérifier la cohérence entre les démarches et la bonne prise en compte de modifications globales (ajout d’une librairie ou d’une fonctionnalité) :

  • ouvrir l’outil KDIFF
  • ouvrir ensemble les répertoires 2-code/front/projects/bibliotheque et 2-code/front/projects/xxxx avec xxxx le code de la démarche à comparer
  • ne doivent être différents que :
    • le code de la démarche dans le fichier cypress/e2e/e2e.cy.ts et potentiellement le nom des brouillons
    • le contenu des fichiers src/assets/bouchonapi/brouillon.json et src/assets/bouchonapi/param.json car ils sont totalement spécifiques à chaque démarche
    • le contenu des fichiers src/environments/environments.ts et src/environments/environments.prod.ts car ils contiennent le code de la démarche
    • le contenu des fichiers src/index.html, src/environments/environments.ts et src/environments/environments.prod.ts car ils contiennent le code de la démarche

3.32.4 - Ajouter un nouveau type de contenu

Tout type de contenu dispose des attributs suivants (@see ContenuDeBloc dans configurationdemarchecontenubloc.model.ts) :

cliquer ici pour afficher le contenu

Pour ajouter un type de contenu, il faut :

  • déclarer un nouveau type dans TypeContenuDeBloc (@see configurationdemarchecontenubloc.model.ts)
  • associer ce nouveau type avec les catégories définies dans UtilitaireModel (@see utilitaire.model.ts)
  • déclarer une nouvelle classe avec les spécificités du contenu à gérer dans configurationdemarchecontenubloc.model.ts (si nécessaire)
  • enrichir la méthode ConfigurationService.transtyperContenuDeBloc pour transtyper les objets JSON dans le bon type TS
  • créer le composants TS du nouveau type de contenu
  • déclarer ce nouveau composant Angular dans le module.ts
  • ajouter un GETTER dans le composant FmkContenuComponent (en respectant l’ordre alphabétique des méthodes)
  • ajouter une balise <fmk-contenuxxxxx dans la partie HTML du composant FmkContenuComponent (en respectant l’ordre alphabétique des composants)

Côté Java, il faut aussi :

  • déclarer le type de contenu dans une des constantes de la classe ValidationSoumissionServiceImpl
  • les champs de type autocompletion des composants complexes dans ValidationSoumissionServiceImpl.LISTE_SOUS_CHAMPS_AUCOMPLETION_DANS_COMPOSANT_COMPLEXE

Côté Editeur, il ne faut pas oublier de :

  • vérifier les impacts sur le formulaire d’un contenu

Côté documentation, il faut enfin :

  • ajouter le nouveau type de composant à la liste du chapitre 2.6
  • décrire le nouveau type de contenu dans le chapitre 2.10.2.2

3.32.5 - A savoir sur un type de contenu

Concernant le fonctionnement d’un type de contenu, quelques éléments à savoir :

  • ne jamais utiliser une méthode/interface de hook du cycle de vie Angular (OnChange, OnInit…)
  • pour exécuter du code au chargement du composant, il suffit de surcharger la méthode protected initialiserComposant(contenu: ContenuDeBloc): void {}

3.32.6 - Ajout/retrait/modification d’un attribut dans un type de contenu ou une classe du package model

En cas de modification d’une classe décrivant un type de contenu (ou une classe de la grappe de données des configurations publiques/inernes) pour y ajouter une un attribut saisissable dans un JSON (pas une donnée calculée), il est nécessaire de réaliser des modifications dans d’autres classes du projet :

  • dans ConfigurationService : si l’attribut ajouté/modifié/supprimé est un type complexe (objet ou tableau), il est nécessaire de l’initialiser au cas où il serait absent de la configuration chargée en JSON.
  • dans l’application d’édition de démarche, le/les composants graphiques doivent être adaptés à la structure de données
  • dans l’éventuelle classe Java équivalente, la modification doit aussi être appliquée
  • dans la démarche bibliotheque, un exemple doit être fourni

3.32.7 - Comment ajouter un nouveau type de validation de champ

Il existe deux types de validation de champ : les paramétrables et les autres. Par exemple dateAvant-7j est une validation paramétrable et required ne l’est pas.

Côté FRONT, pour ajouter une validation, il faut :

  • modifier la classe Validation dans le fichier configurationdemarchecontenubloc.model.ts pour ajouter le nom de la validation (ou la partie fixe si c’est une validation paramétrable)
  • modifier la classe ValidationService pour ajouter le contrôle lui-même (en s’inspirant du code existant). Attention, si la validation est paramétrable, l’objet retourné par la méthode de validation doit contenir la partie fixe et non la variable v.
  • modifier le fichier fmk.messagesvalidation.html pour ajouter le message d’erreur associé à la validation
  • modifier la méthode ContenuMonoTestUtils.definirMauvaiseValeur pour y fournir une mauvaise valeur pour la nouvelle validation
  • ajouter la nouvelle validation dans le second if de la méthode ContenuMonoTestUtils.validerLesValidationDunContenuMonoChamp
  • si la validation est paramétrable, enrichir le calcul de la variable nomClasseAssocieAvalidation de la méthode ContenuMonoTestUtils.validerLesValidationDunContenuMonoChamp
  • modifier la configuration de la démarche bibliotheque pour y ajouter un champ avec cette nouvelle validation
  • modifier les données de brouillon de la démarche bibliotheque pour y ajouter une bonne valeur pour le nouveau champ
  • si la bonne valeur n’est pas une valeur fixe (mais une valeur dépendante du jour par exemple), modifier la méthode ContenuMonoTestUtils.definirBonneValeur pour y ajouter une gestion spécifique de cette validation
  • lancer les tests E2E de la démarche bibliotheque
  • modifier la démarche devant utiliser cette nouvelle validation
  • lancer les tests E2E de cette démarche

Côté BACK, pour ajouter une validation, il faut :

  • modifier la classe ValidationEnum pour ajouter le nom de la validation (ou la partie fixe si c’est une validation paramétrable)
  • modifier la méthode ValidationSoumissionServiceImpl.verifierValidationDuneValeur pour ajouter le contrôle lui-même (en s’inspirant du code existant).
  • tester la nouvelle validation en modifiant les classes SoumissionObjectMother et ValidationServiceTest
    • pour enrichir les cas passants existants
    • ajouter des cas bloquants et aux limites
  • lancer les tests automatisés sur projet socle-soumission

3.32.8 - Règles de développement dans le code spécifique d’une démarche

  • aucune fonctionnalité du framework ne doit être enrichie. Il faut enrichir le framework (type de contenu, validation…)
  • toute souscription (alias appel à une méthode subscribe()) doit être détruite à la fin de la vie du composant qui réalise la souscription. La seule exception concerne les composants immortels (comme les AppComponent) pour lesquels un commentaire explicite est obligatoire. Pour réaliser cela,
    • soit le composant détruit lui-même la souscription dans sa méthode ngOnDestroy (prendre modèle sur la classe AbstractComponent)
    • soit le composant hérite de AbstractComponent et utilise les méthodes declarerSouscription et declarerSouscriptions pour ajouter la souscription créée à la liste des souscriptions à détruire

3.32.9 - Intégration de la charte graphique de l’état (DSFR)

La documentation est disponible ici : https://gouvfr.atlassian.net/wiki/spaces/DB/pages/223019574/D+veloppeurs. La dépendance à DSFR (en version 1.1 au 10/11/2021) se fait via NPM/YARN. Pour intégrer les CSS DSFR à l’application, la configuration //build/options/styles est correctement renseignée dans le fichier angular.json. La feuille de style projects/framework/src/assets/stylesDSFR.scss est dédiée aux styles ajoutés à DSFR pour l’amender ou la compléter pour les besoins de la PSL.

3.32.10 - Validation W3C du code HTML généré

Pour valider le code HTML généré dans une démarche, il faut :

  • dans une démarche donnée, recopier le contenu du fichier src/environments/environment.ts dans le fichier src/environments/environment.prod.ts
  • depuis l’invite de commande, exécuter un xx-build-prod de la démarche
  • lancer le serveur http via la commande npm http-start
  • pour chaque écran de la démarche
    • dans les outils de développement, dans l’onglet Elements, sélectionner la balise html et copier tout le contenu de la page
    • aller sur le site du validateur W3C
    • coller le code HTML
    • lancer la validation
    • interpréter les résultats
      • la balise doctype n’est pas copiée dans la procédure mais est bien présente dans le code de la page. Donc cette erreur peut être ignorée.
      • le contenu @charset “UTF-8” vient des CSS de la DSFR
      • l’attribut type de la balise style est généré automatiquement par Angular
      • le rôle banner sur la balise header est demandée explicitement par la documentation DSFR
      • le rôle main sur la balise main est demandée explicitement par la documentation DSFR : lien 1 et lien 2
      • le rôle navigation sur la balise nav est demandée explicitement par la documentation DSFR
      • l’attribut contentinfo sur la balise footer est demandée explicitement par la documentation DSFR

3.32.11 - Quelques rappels TS/JS

Voici quelques liens à consulter pour (re)découvrir quelques bases de TypeScript/Javascript :