Excel Editor SPA

Summary

• 1. Presentation
  • 1.1. SPA, API & Insomnia
  • 1.2. Diagrams
    • 1.2.1. Global architecture
    • 1.2.2. Authentication & JWT
• 2. Prerequisites
  • 2.1. Docker Compose CLI
• 3. Installation
  • 3.1. To the very first cloning of the project
  • 3.2. The following times
• 4. Screenshots
  • 4.1. Login page
  • 4.2. Admin (Upload, Read, Write & delete)
    • 4.2.1. No data
    • 4.2.2. Upload (choose a file)
    • 4.2.3. Upload (results)
    • 4.2.4. Read (table with data)
    • 4.2.5. Write (edit)
    • 4.2.6. Write (create)
    • 4.2.7. Delete
  • 4.3. User (Read only)
  • 4.4. Loading (Progress bar & Spinner)
• 5. Upload Excel files
• 6. Main technical constraints for the study
• 7. Style Guide
  • 7.1. Angular coding style guide
  • 7.2. JSON naming convention
• 8. Codacy configuration
  • 8.1. Code coverage
  • 8.2. ESLint
  • 8.3. Stylelint
• 9. PHPStorm configuration
  • 9.1. Configure a remote Node.js interpreter
  • 9.2. Configure ESLint
  • 9.3. Configure Prettier & Reformat files
  • 9.4. Configure Stylelint
• 10. Resources & Inspiration
  • 10.1. Standalone components
  • 10.2. Container & Presentational Components
  • 10.3. Observable Data Services
  • 10.4. OnPush Change Detection
  • 10.5. Design Patterns in Angular
  • 10.6. Angular Resolvers
  • 10.7. Angular Service Layers
    • 10.7.1. When to Use a Store And Why?
    • 10.7.2. Alternative solutions in the Angular world, other than a store
    • 10.7.3. Alternative to Redux: MobX
  • 10.8. RxJs Mapping Operators
  • 10.9. HTTP request & Cache
  • 10.10. JWT, Authentication & Permissions
  • 10.11. Error handling & Best practices
    • 10.11.1. Error on login
    • 10.11.2. Error on add an existing group
    • 10.11.3. Error if the user is not allowed to delete a group
    • 10.11.4. Throw a simple new Error in a page
  • 10.12. Architecture
    • 10.12.1. Best pratices
    • 10.12.2. public-api.ts
  • 10.13. Material
  • 10.14. Angular Dev Tools
  • 10.15. Skeleton Loading
• 11. Troubleshooting
  • 11.1. [webpack-dev-server] Disconnected!
  • 11.2. Input type "file" isn’t supported by matInput
• 12. Comments, suggestions?
• 13. License

1. Presentation

1.1. SPA, API & Insomnia

Study of a complete application, with a SPA (Angular) and an API (Symfony), which allows users to connect, and to be able, according to their rights, to import Excel data and modify them online.

Excel Editor SPA	https://github.com/jprivet-dev/excel-editor-spa
Excel Editor API	https://github.com/jprivet-dev/excel-editor-api
Excel Editor Insomnia	https://github.com/jprivet-dev/excel-editor-insomnia

⬆ Back to top

1.2. Diagrams

1.2.1. Global architecture

⬆ Back to top

1.2.2. Authentication & JWT

⬆ Back to top

2. Prerequisites

2.1. Docker Compose CLI

❗	Be sure to install the latest version of Docker Compose CLI plugin.

⬆ Back to top

3. Installation

3.1. To the very first cloning of the project

1. $ git clone [email protected]:jprivet-dev/excel-editor-spa.

2. $ cd excel-editor-spa.

3. $ make install: This command will execute the following commands:

   • $ make build: Build or rebuild fresh images if necessary.

   • $ make start: Create and start containers (alias: $ make up).

4. Open your browser on http://localhost:4200.

⚠️	To use Excel Editor SPA, you will need to install also Excel Editor API, an API made with Symfony.

⬆ Back to top

3.2. The following times

1. Just launch the project with $ make start command.

2. Open your browser on http://localhost:4200.

💡	$ make stop: Stop and remove containers, networks (alias: $ make down). $ make: See all available make commands.

⬆ Back to top

4. Screenshots

4.1. Login page

⬆ Back to top

4.2. Admin (Upload, Read, Write & delete)

4.2.1. No data

⬆ Back to top

4.2.2. Upload (choose a file)

⬆ Back to top

4.2.3. Upload (results)

⬆ Back to top

4.2.4. Read (table with data)

⬆ Back to top

4.2.5. Write (edit)

⬆ Back to top

4.2.6. Write (create)

⬆ Back to top

4.2.7. Delete

⬆ Back to top

4.3. User (Read only)

⬆ Back to top

4.4. Loading (Progress bar & Spinner)

⬆ Back to top

5. Upload Excel files

The Excel files are uploaded and renamed (with a unique indentifier) in the uploads folder of the Excel Editor API.

💡	You can test and upload the Excel files in the data folder of the Excel Editor API.

⬆ Back to top

6. Main technical constraints for the study

• Use of the latest version of Angular.

• No NgRx Store: the objective is to study in depth the observable data services and principles.

• Only Angular Material UI: no merge with Bootstrap, tailwindcss, or other CSS frameworks.

• Use mainly the code generation commands (ng generate).

• The project must be dockerized.

• The project must have a consistent and correct code coverage.

• The data imported from the excel file are in French: this force us to dissociate the specific language of the data (in French) from the "technical" language of the framework (in English).

⬆ Back to top

7. Style Guide

7.1. Angular coding style guide

📎	https://angular.io/guide/styleguide

⬆ Back to top

7.2. JSON naming convention

📎	https://stackoverflow.com/questions/5543490/json-naming-convention-snake-case-camelcase-or-pascalcase https://google.github.io/styleguide/jsoncstyleguide.xml?showone=Property_Name_Format#Property_Name_Format

That project (API & SPA) use the camelCase format for the property names of JSON responses:

{
  "thisPropertyIsAnIdentifier": "identifier value"
}

⬆ Back to top

8. Codacy configuration

8.1. Code coverage

Duplicate CODACY_PROJECT_TOKEN.sh:

$ cp scripts/CODACY_PROJECT_TOKEN.sh.dist scripts/CODACY_PROJECT_TOKEN.sh

And define the API token CODACY_PROJECT_TOKEN (see https://app.codacy.com/gh/jprivet-dev/excel-editor-spa/settings/coverage).

The file scripts/CODACY_PROJECT_TOKEN.sh is ignored by Git and imported by scripts/reporter.sh.

The file scripts/reporter.sh generates code coverage (a lcov.info with Instanbul) and uploads the coverage reports on Codacy.

📎	https://github.com/codacy/codacy-coverage-reporter https://github.com/karma-runner/karma-coverage

💡	Karma: generate code coverage using Istanbul.

⬆ Back to top

8.2. ESLint

Codacy scans the ESLint configuration in the .eslintrc.json file in this repository root.

💡	PHPStorm can also use ESLint. See Configure ESLint.

📎	More information on: https://eslint.org/ https://app.codacy.com/p/497934/patterns/list?engine=f8b29663-2cb2-498d-b923-a10c6a8c05cd https://docs.codacy.com/repositories-configure/configuring-code-patterns/

⬆ Back to top

8.3. Stylelint

Codacy scans the Stylelint configuration in the .stylelintrc file in this repository root.

We need to install stylelint-config-standard-scss:

$ npm install --save-dev stylelint stylelint-config-standard-scss

And create a .stylelintrc.json configuration file:

{
  "extends": "stylelint-config-standard-scss"
}

Use the $ make stylelint command to execute Stylelint on the src folder.

💡	PHPStorm can also use Stylelint. See Configure Stylelint.

📎	More information on: https://app.codacy.com/p/497934/patterns/list?engine=1f03328a-086e-459e-bfa3-73e56f01020f https://docs.codacy.com/repositories-configure/configuring-code-patterns/ https://stylelint.io/user-guide/configure/ https://stylelint.io/user-guide/get-started/

⬆ Back to top

9. PHPStorm configuration

❗	The following configuration are provided for PHPStorm 2022.3.1

9.1. Configure a remote Node.js interpreter

1. Go in Settings (Ctrl+Alt+S) > Languages & Frameworks > Node.js.

2. In Node interpreter, click on …​ and Add Remote…​.

3. In the Configure Node.js Remote Interpreter window, choose excel-editor-spa-node:latest and click on OK.

4. In the Settings window, click on OK.

⬆ Back to top

9.2. Configure ESLint

🔥	Before you start: Configure a remote Node.js interpreter.

Configure in Settings (Ctrl+Alt+S) > Languages & Frameworks > JavaScript > Code Quality Tools > ESLint :

After the configuration, you can see the ESLint alerts in your code. For example:

⚠️

If you have this error: ESLint: Can’t run process: failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: exec: \"node\": executable file not found in $PATH: unknown: Is that the Node.js interpreter is badly configured. See Configure a remote Node.js interpreter.

📎	More information on https://www.jetbrains.com/help/phpstorm/eslint.html

⬆ Back to top

9.3. Configure Prettier & Reformat files

🔥	Before you start: Configure a remote Node.js interpreter.

Configure in Settings (Ctrl+Alt+S)> Languages & Frameworks > JavaScript > Prettier :

After the configuration, you can reformat your code :

• With the shortcut Ctrl+Alt+Maj+P.

• From the contextual menu (Right click > Reformat with Prettier).

💡	It’s possible to reformat on save.

To reformat on save, Go in Settings (Ctrl+Alt+S)> Languages & Frameworks > JavaScript > Prettier, and check On save option:

If you click on All actions on save…​, you will see the list of all activated actions:

💡	I also use the Optimize import option. This removes unused imports and organizes import statements in the current file. See https://www.jetbrains.com/help/phpstorm/creating-and-optimizing-imports.html#optimize-imports.

📎	More information on https://www.jetbrains.com/help/phpstorm/prettier.html

⬆ Back to top

9.4. Configure Stylelint

🔥	Before you start: Configure a remote Node.js interpreter.

Configure in Settings (Ctrl+Alt+S)> Languages & Frameworks > JavaScript > Prettier :

❗	For the moment I have an error in PHPStorm with a missing module. I tried to install v8-compile-cache, but nothing works: However, everything works with the $ make stylelint command. Search still in progress…​

📎	More information on https://www.jetbrains.com/help/phpstorm/using-stylelint-code-quality-tool.html

⬆ Back to top

10. Resources & Inspiration

10.1. Standalone components

This project does not yet use completely the standalone components (introduced in Angular 14).

💡	Generate a standalone component: $ ng g c myComponent --standalone

📎	https://angular.io/guide/standalone-components

⬆ Back to top

10.2. Container & Presentational Components

• https://blog.angular-university.io/angular-component-design-how-to-avoid-custom-event-bubbling-and-extraneous-properties-in-the-local-component-tree/

• https://medium.com/@dan_abramov/smart-and-dumb-components-7ca2f9a7c7d0

This project is inspired by this pattern (which can quickly become an anti-pattern if applied dogmatically).

What are the main points?

• Container (or Smart) components:

  • Components that are aware of the service layer (no @Input, no @Output).

  • Top-level components: highest level of components, only for components attached to a route.

  • Examples: UserPage, FollowersSidebar, StoryContainer, FollowedUserList.

• Presentational components:

  • Components that receive inputs and emit events, nothing else (no services, only @Input and @Ouput).

  • Examples: Sidebar, Story, UserInfo, List

• A presentational component can contain a container component: it allows for logic for interaction with the service layer to be put deeply into the component tree (if that is where it makes the most sense to have it), also to simplify the intermediate components and avoids code repetition.

In practice its actually much more practical to mix and match the multiple types of component design as we need, and use different types of components at different levels of the tree as necessary - mixing the different features as much as we need.

— ANGULAR UNIVERSITY

⬆ Back to top

10.3. Observable Data Services

• https://blog.angular-university.io/how-to-build-angular2-apps-using-rxjs-observable-data-services-pitfalls-to-avoid/

This project uses simple stores with Observable Data Services, instead of @ngrx/store.

⬆ Back to top

10.4. OnPush Change Detection

• https://blog.angular-university.io/onpush-change-detection-how-it-works/

⬆ Back to top

10.5. Design Patterns in Angular

• https://dev.to/armandotrue/design-patterns-in-angular-part-i-3ld7

• https://martinfowler.com/eaaCatalog/repository.html

⬆ Back to top

10.6. Angular Resolvers

• https://indepth.dev/tutorials/angular/indepth-guide-how-to-implement-resolver-in-angular

• https://www.tektutorialshub.com/angular/angular-resolve-guard/

• https://devtobecurious.fr/ameliorer-vos-routes-avec-le-resolver-dans-angular-pour-un-meilleur-chargement/

• https://openclassrooms.com/fr/courses/7471281-perfectionnez-vous-sur-angular/7717976-resolvez-les-donnees

• https://angular.fr/routing/resolver.html

⬆ Back to top

10.7. Angular Service Layers

10.7.1. When to Use a Store And Why?

• https://blog.angular-university.io/angular-2-redux-ngrx-rxjs/

• https://medium.com/@dan_abramov/you-might-not-need-redux-be46360cf367#.z9abvda1k

You’ll know when you need Flux. If you aren’t sure if you need it, you don’t need it.

— ANGULAR UNIVERSITY

10.7.2. Alternative solutions in the Angular world, other than a store

• Inject services deep in the component tree.

• Inject components or services into each other if we feel they are inherently tightly coupled.

• Create shared data services that might or might not store the data.

10.7.3. Alternative to Redux: MobX

• https://github.com/mobxjs/mobx-angular

⬆ Back to top

10.8. RxJs Mapping Operators

• https://blog.angular-university.io/rxjs-higher-order-mapping/

⬆ Back to top

10.9. HTTP request & Cache

• https://blog.angulartraining.com/how-to-cache-the-result-of-an-http-request-with-angular-f9aebd33ab3

💡	Use shareReplay: https://www.learnrxjs.io/learn-rxjs/operators/multicasting/sharereplay

⬆ Back to top

10.10. JWT, Authentication & Permissions

• Communicating with backend services using HTTP: https://angular.io/guide/http

• Angular Authentication With JWT: https://blog.angular-university.io/angular-jwt-authentication/

• Angular Authentication: Using Route Guards : https://medium.com/@ryanchenkie_40935/angular-authentication-using-route-guards-bf7a4ca13ae3

• JWT debugger: https://jwt.io/

• Angular permissions based on roles | Part 1. Roles, permissions and Permission Manager: https://medium.com/@rjlopezdev/angular-permissions-based-on-roles-part-1-roles-permissions-and-permission-manager-f3dde1bc82bb

📎	The authentication service of this project is mainly inspired by https://github.com/auth0/auth0-angular.

⬆ Back to top

10.11. Error handling & Best practices

• https://angular.io/api/core/ErrorHandler

• https://blog.angular-university.io/rxjs-error-handling/

• https://medium.com/angular-in-depth/expecting-the-unexpected-best-practices-for-error-handling-in-angular-21c3662ef9e4

• https://www.intertech.com/angular-best-practice-rxjs-error-handling/

• https://itnext.io/how-to-handle-your-run-time-errors-in-your-angular-application-8d72fefbf8a4

• https://www.stacktracejs.com/

• https://angular.io/guide/router-tutorial#adding-a-404-page

10.11.1. Error on login

API response

{
    "code":401,
    "message":"Invalid credentials."
}

Angular HttpErrorResponse

{
    "headers": {
        "normalizedNames": {},
        "lazyUpdate": null
    },
    "status": 401,
    "statusText": "OK",
    "url": "https://localhost/api/login_check",
    "ok": false,
    "name": "HttpErrorResponse",
    "message": "Http failure response for https://localhost/api/login_check: 401 OK",
    "error": {
        "code": 401,
        "message": "Invalid credentials."
    }
}

Normalized error

{
    "status": 401,
    "name": "HttpErrorResponse",
    "message": "Http failure response for https://localhost/api/login_check: 401 OK",
    "url": "https://localhost/api/login_check",
    "detail": "Invalid credentials."
}

⬆ Back to top

10.11.2. Error on add an existing group

API response

{
    "type": "https://tools.ietf.org/html/rfc2616#section-10",
    "title": "An error occurred",
    "status": 400,
    "detail": "Object(App\\Entity\\Data).nomDuGroupe:\n    The music group \"Nirvana\" already exists. (code 23bd9dbf-6b9b-41cd-a99e-4844bcf3077f)\n",
    "class": "Symfony\\Component\\HttpKernel\\Exception\\HttpException",
    "trace": ['...']
}

Angular HttpErrorResponse

{
    "headers": {
        "normalizedNames": {},
        "lazyUpdate": null
    },
    "status": 400,
    "statusText": "OK",
    "url": "https://localhost/api/data",
    "ok": false,
    "name": "HttpErrorResponse",
    "message": "Http failure response for https://localhost/api/data: 400 OK",
    "error": {
        "type": "https://tools.ietf.org/html/rfc2616#section-10",
        "title": "An error occurred",
        "status": 400,
        "detail": "Object(App\\Entity\\Data).nomDuGroupe:\n    The music group \"Nirvana\" already exists. (code 23bd9dbf-6b9b-41cd-a99e-4844bcf3077f)\n",
        "class": "Symfony\\Component\\HttpKernel\\Exception\\HttpException",
        "trace": ['...']
    }
}

Normalized error

{
    "status": 400,
    "name": "HttpErrorResponse",
    "message": "Http failure response for https://localhost/api/data: 400 OK",
    "url": "https://localhost/api/data",
    "detail": "Object(App\\Entity\\Data).nomDuGroupe:\n    The music group \"Nirvana\" already exists. (code 23bd9dbf-6b9b-41cd-a99e-4844bcf3077f)\n",
    "exception": "HttpException"
}

⬆ Back to top

10.11.3. Error if the user is not allowed to delete a group

API response

{
    "type": "https://tools.ietf.org/html/rfc2616#section-10",
    "title": "An error occurred",
    "status": 403,
    "detail": "You do not have sufficient rights to delete a music group.",
    "class": "Symfony\\Component\\HttpKernel\\Exception\\AccessDeniedHttpException",
    "trace": ['...']
}

Angular HttpErrorResponse

{
    "headers": {
        "normalizedNames": {},
        "lazyUpdate": null
    },
    "status": 403,
    "statusText": "OK",
    "url": "https://localhost/api/data/78",
    "ok": false,
    "name": "HttpErrorResponse",
    "message": "Http failure response for https://localhost/api/data/78: 403 OK",
    "error": {
        "type": "https://tools.ietf.org/html/rfc2616#section-10",
        "title": "An error occurred",
        "status": 403,
        "detail": "You do not have sufficient rights to delete a music group.",
        "class": "Symfony\\Component\\HttpKernel\\Exception\\AccessDeniedHttpException",
        "trace": ['...']
    }
}

Normalized error

{
    "status": 403,
    "name": "HttpErrorResponse",
    "message": "Http failure response for https://localhost/api/data/78: 403 OK",
    "url": "https://localhost/api/data/78",
    "detail": "You do not have sufficient rights to delete a music group.",
    "exception": "AccessDeniedHttpException"
}

⬆ Back to top

10.11.4. Throw a simple new Error in a page

With

throw new Error('Parameter is not a number!');

JavaScript Error

Error: Uncaught (in promise): Error: Parameter is not a number!
Error: Parameter is not a number!
    at new PageNotFoundComponent (page-not-found.component.ts:14:11)
    at NodeInjectorFactory.PageNotFoundComponent_Factory [as factory] (page-not-found.component.ts:15:4)
    at getNodeInjectable (core.mjs:3523:44)
    at instantiateRootComponent (core.mjs:12592:23)
    at createRootComponent (core.mjs:14035:23)
    at ComponentFactory.create (core.mjs:13912:17)
    at ViewContainerRef.createComponent (core.mjs:23230:47)
    at RouterOutlet.activateWith (router.mjs:2569:39)
    at ActivateRoutes.activateRoutes (router.mjs:3003:40)
    at router.mjs:2952:18
    at resolvePromise (zone.js:1211:31)
    at resolvePromise (zone.js:1165:17)
    at zone.js:1278:17
    at _ZoneDelegate.invokeTask (zone.js:406:31)
    at Object.onInvokeTask (core.mjs:26261:33)
    at _ZoneDelegate.invokeTask (zone.js:405:60)
    at Zone.runTask (zone.js:178:47)
    at drainMicroTaskQueue (zone.js:585:35)

Normalized error

{
    "name": "Error",
    "message": "Uncaught (in promise): Error: Parameter is not a number!\nError: Parameter is not a number!\n    at new PageNotFoundComponent (http://localhost:4200/main.js:892:15)\n    at NodeInjectorFactory.PageNotFoundComponent_Factory [as factory] (http://localhost:4200/main.js:895:81)\n    at getNodeInjectable (http://localhost:4200/vendor.js:52246:38)\n    at instantiateRootComponent (http://localhost:4200/vendor.js:62953:21)\n    at createRootComponent (http://localhost:4200/vendor.js:64667:21)\n    at ComponentFactory.create (http://localhost:4200/vendor.js:64517:19)\n    at ViewContainerRef.createComponent (http://localhost:4200/vendor.js:75063:43)\n    at RouterOutlet.activateWith (http://localhost:4200/vendor.js:113096:33)\n    at ActivateRoutes.activateRoutes (http://localhost:4200/vendor.js:113679:28)\n    at http://localhost:4200/vendor.js:113625:12"
}

⬆ Back to top

10.12. Architecture

10.12.1. Best pratices

• https://dev-academy.com/angular-architecture-best-practices/

• https://www.simform.com/blog/angular-best-practices/

• https://medium.com/dev-jam/5-tips-best-practices-to-organize-your-angular-project-e900db08702e https://angular.io/guide/styleguide#lift

• https://stackoverflow.com/questions/70924931/angular-structure-best-practices-coremodule

• https://michelestieven.medium.com/organizing-angular-applications-f0510761d65a

10.12.2. public-api.ts

• https://tomastrajan.medium.com/the-best-way-to-architect-your-angular-libraries-87959301d3d3

• https://angular.io/guide/creating-libraries

• Using public_api.ts in libraries instead of piling everything in index.ts: nrwl/nx#155

⬆ Back to top

10.13. Material

• Installation: https://material.angular.io/guide/getting-started

• Material Symbols: https://fonts.google.com/icons

⬆ Back to top

10.14. Angular Dev Tools

• https://angular.io/guide/devtools

⬆ Back to top

10.15. Skeleton Loading

• https://www.npmjs.com/package/ngx-skeleton-loader

• https://codepen.io/fadzrinmadu/pen/jOBLRzm

⬆ Back to top

11. Troubleshooting

11.1. [webpack-dev-server] Disconnected!

When I use Slow 3G network conditions:

I got the following console error on Chrome:

[webpack-dev-server] Disconnected! index.js:551
[webpack-dev-server] Trying to reconnect...
[webpack-dev-server] Disconnected! index.js:551
[webpack-dev-server] Trying to reconnect...
...

This is a problem when using SSL. See angular/angular-cli#4839.

📎	No problem with Fast 3G.

⬆ Back to top

11.2. Input type "file" isn’t supported by matInput

Whaaaaat !??

ERROR Error: Input type "file" isn't supported by matInput.

💡

Workaround : angular/components#3262 (comment) https://stackoverflow.com/questions/52622061/how-to-use-input-type-file-in-angular-material <button type="button" mat-raised-button (click)="fileInput.click()">Choose File</button> <input hidden (change)="onFileSelected()" #fileInput type="file" id="file"> onFileSelected() { const inputNode: any = document.querySelector('#file'); if (typeof (FileReader) !== 'undefined') { const reader = new FileReader(); reader.onload = (e: any) => { this.srcResult = e.target.result; }; reader.readAsArrayBuffer(inputNode.files[0]); } }

⬆ Back to top

12. Comments, suggestions?

Feel free to make comments/suggestions to me in the Git issues section.

⬆ Back to top

13. License

"Excel Editor SPA" is released under the MIT License

---

⬆ Back to top