Tutoriel pour apprendre à bien organiser son projet Angular : Structure

Nicolas GARIN (Soat)

Aujourd'hui, dans la plupart des cas, lorsque vous commencez un projet Angular (1.x) vous pensez à une architecture MVC. Il y a beaucoup de manières de coder en Angular, mais il y en a particulièrement une qui est, selon moi, plus claire. Dans cet article, je vais vous montrer comment monter un projet modulaire, avec de bonnes pratiques, facile à maintenir et à comprendre, puis nous verrons quels en sont les avantages.

Ce tutoriel n'a pas la prétention de vous montrer la bonne voie à suivre pour coder en Angular, il y a autant de manières de développer que de développeurs.

Commentez ♪

- Titre : Tutoriel pour apprendre à bien organiser son projet Angular : Structure

- Auteur : Nicolas GARIN (Soat)

- Parution : 6 décembre 2016

- Licence : Copyright ® 2016 Nicolas GARIN. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.

Sommaire

- I. Organisation des fichiers

- I-A. Le pattern MVC

- I-B. Une organisation orientée « components »

- I-C. « Encapsulation »

- I-D. Modules

- I-E. Déclaration des composants

- I-F. ControllerAs

- I-G. Les routes

- I-H. Les grosses applications

- II. Conclusion

- III. Remerciements

I - Organisation des fichiers

I-A - Le pattern MVC

1. source

2. /assets

3. /favicon

4. /fonts

5. /images

6. /bower_components

7. /angular

8. /angular-routes

9. /controllers

10. /home.controller.js

11. /articles-list.controller.js

12. /article-detail.controller.js

13. /directives

14. /article

15. /article.directive.js

16. /_article.directive.html

17. /filters

18. /translate.filter.js

19. /partials

20. /_footer.html

21. /_header.html

22. /_home.html

23. /resources

24. /locale-fr_FR.json

25. /sass

26. /_directives.scss

27. /_fonts.scss

28. /_global.scss

29. /screen.scss

30. /services

31. /locale.service.js

32. /article.service.js

33. /app.config.js

34. /app.module.js

35. /app.routes.js

36. /index.html

Voici un modèle MVC comme on les « aime » : Les contrôleurs d'un côté, les vues de l'autre, etc. Logiquement c'est ce vers quoi on va se tourner et c'est aussi la logique que j'ai adoptée à mes débuts. Le principal problème que je vois ici est que lorsque j'ai envie d'ajouter ou de modifier une nouvelle fonctionnalité dans une page, il est nécessaire que j'aille chercher le contrôleur, le service, la directive, le template, etc. Cela devient rapidement plus compliqué lorsqu'on a une application avec plus de 10 contrôleurs. AngularJS nous permet de gérer nos projets d'une manière plus simple et claire.

I-B - Une organisation orientée « components »

1. source

2. /assets

3. /images

4. /favicon

5. /fonts

6. /bower_components

7. /angular

8. /angula-routes

9. /components  // Les composants qui composent la logique de notre application (controlleurs, routes, partials...)

10. /home

11. /_home.html

12. /_home.scss

13. /home.controller.js

14. /home.routes.js

15. /articles

16. /article-list.routes.js

17. /list

18. /_articles-list.html

19. /_articles-list.scss

20. /articles-list.controller.js

21. /detail

22. /_article-detail.html

23. /_article-detail.scss

24. /article-detail.controller.js

25. /modules // Tous les composants de notre application qui sont réutilisables même en dehors de notre application

26. /translate

27. /locale.service.js

28. /translate.module.js

29. /translate.filter.js

30. /resources

31. /locale-fr_FR.json

32. /sass

33. /_fonts.scss

34. /_global.scss

35. /screen.scss

36. /services

37. /article.service.js

38. /shared // Tous les composants de notre application qui sont réutilisables et propres à notre application

39. /article

40. /_article.directive.html

41. /_article.directive.scss

42. /article.directive.js

43. /_footer.html

44. /_head.html

45. /main.controller.js

46. /app.config.js

47. /app.module.js

48. /index.html

Vous pouvez récupérer ce projet sur git : https://github.com/SoatGroup/angular-organisation

Il est vrai que de prime abord, cette structure peut paraître compliquée, mais ce n'est qu'une question d'habitude. Il faut imaginer notre application Angular comme plusieurs petites applications MVC, cela nous permet une meilleure modularité et lisibilité (après adaptation). Nous ne classons plus nos fichiers par rapport à leur catégorie mais par rapport au sujet auquel ils appartiennent.

Ici, comme vous pouvez le voir, les composants sont individuels, par exemple si je décide de supprimer le dossier app/components/articles, cela ne posera aucun problème. Un développeur va plus facilement s'y retrouver afin de modifier ou d'ajouter une fonctionnalité dans un fichier ou dans plusieurs qui sont liés entre eux. D'un simple coup d'œil on est capable d'identifier le contenu. De plus, on se rapproche d'une organisation typique d' Angular 2, plus simple si on veut franchir le cap.

Components

Ce qu'on appelle « component » ici va correspondre aux différentes parties de notre application (article de blog, page d'accueil, liste de résultats, etc.), il va comprendre un controller, une vue, un scss et une route. Comme dit plus haut, chaque component est individuel, en gros il ne dépend pas des autres et fonctionne comme une petite application MVC.

Dans le cas du component « articles », on peut constater qu'il y deux sous-dossiers : « list » et « detail ». En effet, dans le cas où il y a plusieurs sous-sections il est préférable de faire des sous-dossiers, toujours pour une question de lisibilité.

Modules

Le dossier « modules » va contenir tous les modules externes à l'application ou tous les modules qu'on peut réutiliser dans une autre application. Ici par exemple, j'ai développé un petit module de traduction, celui-ci pourra être utilisé à peu près n'importe où. Ce qui n'est pas du tout le cas dans notre première structure en MVC.

Ressources

Nous allons mettre ici toutes nos données statiques, par exemple les fichiers de langues.

Services

J'ai préféré mettre mes services dans un dossier à part car il m'est souvent arrivé d'utiliser certains services à plusieurs endroits, mais vous êtes libres de les mettre avec vos components s'ils leur sont propres.

Shared

Dans « shared » nous allons mettre toutes nos directives, les vues qui apparaissent à plusieurs endroits dans l'application, nos filtres, etc. Avez-vous remarqué comment sont organisées les directives ? Cela peut vous sembler proche de ce qui est fait avec les components, c'est effectivement le cas car nous sommes dans une démarche qui est de nous rapprocher d'une structure type d'AngularJS 2. (Pour information : Nous pourrions ne pas utiliser de directive, je vous laisse lire la documentation).

I-C - « Encapsulation »

Afin d'éviter les conflits de scope, variables, fonctions… et surtout pour rester modulaire, il est conseillé d'encapsuler vos composants dans une fonction anonyme :

1. (function() {

2. // Mon composant…

3. })();

I-D - Modules

Il faut éviter de déclarer les modules en les affectant à une variable :

1. var app = angular.module('MonModule', ['AutreModule']);

Pourquoi ? Parce que dans une architecture modulaire cela n'a pas lieu d'être. De plus, souvenez-vous, nous encapsulons tous nos composants dans une fonction anonyme qui a son propre scope, du coup impossible d'accéder à la variable app partout… Et c'est tant mieux :). Donc le mieux reste :

1. angular

2. .module('Blog', [

3. 'Translate'

4. ]);

I-E - Déclaration des composants

Que ce soit pour une directive, un controller ou un service, il est recommandé de les déclarer avec une fonction nommée plutôt qu'anonyme.

Pas bon :

1. angular

2. .module('Blog')

3. .controller('Home', function() {

4. // …

5. }]);

Bon :

1. angular

2. .module('Blog')

3. .controller('HomeController', [HomeController]);

5. ///////////////

7. function HomeController() {

8. // …

9. }

C'est quand même beaucoup plus lisible, non ?

I-F - ControllerAs

Je ne vais pas vous énumérer les avantages d'utiliser le controllerAs plutôt que le $scope, beaucoup d'articles en parlent, je vais juste vous montrer une syntaxe plus claire.

1. angular

2. .module('Blog')

3. .controller('HomeController', [HomeController]);

5. ///////////////

7. function HomeController() {

8. var vm = this;

10. // Attributs

12. vm.title = 'Bienvenue sur mon blog';

13. vm.news = [];

15. // Méthodes

17. vm.more = more;

19. ///////////////

21. // Définition des méthodes

23. function more(key) {

24. vm.news[key].more = ! vm.news[key].more;

25. }

26. }

Même principe pour les directives, les services, etc.

I-G - Les routes

Comme vous l'avez vu dans mon organisation, il y a un fichier routes par composant, cela permet une meilleure modularité et d'y ajouter un resolver… Prenons notre exemple d'articles, afin d'éviter les chargements asynchrones dans le controller après le chargement de la route, ou afin de gérer les erreurs avant même d'atterrir dans le controller, c'est mieux de charger les données au moment de router :

1. angular

2. .module('Blog')

3. .config(['$routeProvider', articlesRoutes]);

5. ///////////////

7. function articlesRoutes($routeProvider) {

8. $routeProvider

9. .when('/article/:idArticle', {

10. controller: 'ArticleDetailController',

11. controllerAs: 'articleVm',

12. templateUrl: 'partials/_article-detail.html',

13. resolve: {

14. data: ['$q', 'article', getDataArticleDetai]

15. }

16. });

18. ///////////////

20. function getDataArticleDetai($q, article) {

21. var defer = $q.defer();

23. resolve();

25. return defer.promise;

27. ///////////////

29. function resolve() {

30. article

31. .get()

32. .then(fetchArticle, handeError);

34. ///////////////

36. function fetchMenu(data) {

37. defer.resolve(data);

38. }

40. function handeError(data) {

41. defer.reject(data);

42. }

43. }

44. }

45. }

I-H - Les grosses applications

Dans le cas où votre application a du succès, elle a besoin de grosses évolutions et vous êtes en pattern MVC. Votre dossier controllers contient 28 fichiers, vous n'osez même pas compter le nombre de vues et votre fichier scss contient 2000 lignes… Pas très pratique tout ça, ça donne envie de « repartir from scratch ». Dans le cas d'une petite application comme la nôtre, une structure MVC ne pose pas de problème, mais mieux vaut s'habituer à avoir de bonnes pratiques dès le départ.

La structure que je vous ai présentée est très bien adaptée pour de grosses applications. Elle vous permet une meilleure lisibilité et maintenabilité sur vos différents composants. Ajouter ou supprimer une fonctionnalité n'a jamais été aussi simple, presque aussi simple que de supprimer ou d'ajouter un dossier.

Prenez aussi l'habitude de nommer vos fichiers de manière claire (si ce n'est pas déjà fait), par exemple pour un controller : detail.controller.js, un service : article.service.js, etc.

Dans un prochain article je parlerai de l'automatisation des tâches avec Gulp pour ce type de projet, puis nous aborderons la phase de compilation, de minification et d'exécution.

II - Conclusion

Il est très important de garder un code clair et facile à maintenir, surtout lorsqu'on travaille dans une équipe. Organiser ses projets de façon modulaire apporte une grande souplesse et une meilleure clarté, c'est ce qu'Angular nous propose. De plus, il est à noter que cette architecture vous permettra à terme de migrer plus facilement vers Angular 2 qui propose une architecture orientée composant.

Cette structure, comme vu plus haut, permettra de plus facilement se retrouver dans son code et donc de le maintenir ou de le déboguer plus simplement. Votre code sera plus simple à faire évoluer, ajouter un nouveau component, un nouveau module, une nouvelle directive, etc., n'interfèrera pas avec le reste de votre application (il est encore plus simple de supprimer une fonctionnalité). En ce qui concerne les tests, vous pourrez les intégrer dans chaque composant de manière plus claire.

III - Remerciements

Nous tenons à remercier la société Soat qui nous a autorisés à publier ce tutoriel.

Nous remercions également Winjerome pour la mise au gabarit et Maxy35 pour la relecture orthographique.