Front-end

Angular 19 - docs
Node 22 LTS/jod - compatibilité des versions

Librairies

Voir package.json - code

Dépendences

• Bootstrap 5.3.3 - docs => Framework CSS
• ng-bootstrap 18 - docs => Composants Angular pour l'intéractivité des composants Bootstraps
• font-awesome 6 (free icons) - docs => Librairie d'icônes
  • liste des icônes (gratuites)
• angular-fontawesome 1 (tree-shakeable) - docs => Wrapper Angular pour faciliter l'utilisation des icônes FontAwesome
• ngx-translate 17.x - docs => Gestion des libellés et de l'internationalisation
• auth0/angular2-jwt - docs => Gestion simplifié des JWT
• @angular/cdk 19.x - docs => CDK implémentant des comportements pour construire certains composants (ex: tree structure / stepper)
• ngx-spinner 19.x - docs => Gestion des spinners de chargement
• @ng-select 14.9.0 - docs => Composant liste déroulante améliorée
• ngx-mask 19.x - docs => Directives de masques (format) de champs input
• ng2-file-upload 8.x - docs => Gestion de l'upload de fichier
• date-fns 3.x - docs => Gestion des dates
• file-saver - docs => Gestion du téléchargement des fichier
• filesize - docs => Affichage lisible de format de taille de fichier
• papaparse - docs => Librairie de parsing de fichiers CSV
• @ng-web-apis/common 5.x - docs => Accès et abstraction des APIs web (ex: clipboard, notifications, etc.)

Tools

• eslint + prettier + stylelint => linting et formattage
• jasmine + karma => tests (à mettre en place éventuellement, couverture = 0% aujourd'hui)
• source-map-explorer - docs => permet d'analyser la taille du bundle ESBuild final avec les scripts du projet build:stats puis analyze

Structure

Arborescence (outdated)

• app/ => sources de l'application
• assets/ => static files (images, etc.)
• environments/ => variables d'environnements (décrit plus bas dans Configurations)
• locales/ => fichier de traductions
• theme/ => theme scss + variables + extract minimal de bootstrap
• styles.scss => point d'entrée scss, import des librairies externes
• main.ts => point d'entrée angular

Sources

• core/ => chargé initialement dans l'app Angular (contient les fonctionnalitées et configurations principales de l'appli)
• modules/ => modules de feature qui seront "lazy-loaded" lors de l'appel à cette route (ex: les modules authentifiés ne sont pas envoyés dans le bundle initial)
• shared/ => composants réutilisés dans l'application (à importer dans les modules utilisant ces fonctionnalitées), des composants "standalone" (docs) pourrait aussi être définis ici, il faut s'assurer que le composant est bien indépendant.
• utils/ => fonctions et constantes de type utils (ex: date-utils)
• app.component.ts => code d'initialisation de l'app (ex: initialisation du service de traduction)
• app.module.ts => module racine
• app-routing.module.ts => module de routing racine, l'import des autres modules en lazy load se fait ici

Core

• adapter => des classes intégrant une fonctionnalitée facilement utilisable dans l'appli (ex: utilisation du SubSink pour unsubscribe)
• auth => gestion de la partie authentification (token, ..)
• guards => guard pour protéger les accès aux routes front de l'appli
• http => customisation du HttpClient pour les appels au back (définition d'intercepteur,...)
• i18n => configuration de l'internationalisation
• services => autres services (ex: storage service, logger)
• ui => contient le squelette global de l'appli (header, footer, etc.) et certaines pages non authentifiées (homepage, login, 404)

Modules

• ici le module admin englobe les composants des routes authentifiées sous l'url /admin.
  Le package events correspond à la page de la liste des évènements, etc.
  Les routes sont définies dans admin-routing.

Shared

• components => les macro composants (ex: datatable)
• ui => les composants d'interface assez simple (ex: une alerte, un message d'erreur de formulaire,..)
• on pourra rajouter d'autres types d'éléments shared, ex: des directives,..

Configurations

Path alias

Afin d'avoir des imports plus concis, des alias de paths ont été définis.
Ils sont utilisés par Visual Studio Code lors de l'ajout d'un import (voir config typescript.preferences.importModuleSpecifier si cela ne fonctionne pas bien - la valeur devrait être : shortest).

La configuration se trouve dans tsconfig.json :

"paths": {
      "@env/*": ["environments/*"],
      "@shared/*": ["app/shared/*"],
      "@utils*": ["app/utils*"],
      // ...
 }

Environnements

Angular docs

Les variables d'environnements se trouvent dans les fichiers sous le dossier src/environments .

• environment.common.ts => variables communes
• environment.ts => hérite de common, surcharge pour la PROD
• environment.development.ts => hérite de common, surcharge pour la dev

En dev, le fichier environment est remplacé par celui de dev (voir config angular.json => architect.build.configurations.development.fileReplacements)

Back-end Interaction

Construction d'une requête pour le back :

1. Un service "Api" étend BaseApi qui lui donne accès au _baseUrl à concatener avant l'url de la ressource. Cette url de base récupère la valeur apiUrl configurée dans le fichier du bon environnement depuis le dossier src/config. (ex: en mode dev le build injecte src/config/dev/config.json puis surcharge avec src/config/local/config.json si présent).
2. Appel de ce service via le HttpClient en concaténant la baseUrl http://localhost:8080 et le path de la feature /ma-feature (ex: http://localhost:8080/events pour faire récupérer une liste d'événements)
3. Action des HttpInterceptor (ajout de token JWT + gestion du refresh, gestion des erreurs en retour, ..).

remarque

Le proxy Angular proxy.conf.json basé sur webpack n'est pas configuré (docs). On se sert plutôt de mockoon pour faire du mock en configurant le fichier de config local vers l'url de mockoon (ex: http://localhost:3000).

Configuration de l'application

La configuration se fait dans app.config.ts (standalone) qui est chargée dans le fichier d'entrée main.ts.

Routes

CustomRouteReuseStrategy

Pour améliorer la gestion de la réutilisation des composants Angular lors de la navigation entre des routes similaires avec des paramètres différents, une CustomRouteReuseStrategy a été introduite.

{ provide: RouteReuseStrategy, useClass: CustomRouteReuseStrategy }

Située dans custom-route-reuse-strategy.ts, cette stratégie étend la classe BaseRouteReuseStrategy d'Angular. Elle surcharge la méthode shouldReuseRoute pour vérifier également la présence d'une fonction reuse. Chaque route peut définir une fonction personnalisée reuse dans les données (data) pour contrôler si la route doit être réutilisée ou recréée.

reuse?: (future: ActivatedRouteSnapshot, curr: ActivatedRouteSnapshot) => boolean;

Cela permet d'éviter d'avoir à s'abonner manuellement aux changements de paramètres dans les composants et les services, en garantissant que l'arbre des composants est entièrement recréé lors de la navigation entre différentes instances d'une même route (ex: détail d'une convention avec un id différent).

Exemple : Route de Détail d'une Convention

Dans conventions.routes.ts, la route de détail est configurée pour empêcher la réutilisation si le paramètre id change :

export const CONVENTION_DETAIL_ROUTE: CustomRoute = {
  path: ':id',
  // ...
  data: {
    reuse: (future: ActivatedRouteSnapshot, curr: ActivatedRouteSnapshot) => {
      return curr.paramMap.get('id') === future.paramMap.get('id');
    },
  },
  // ...
};