docs: update getting started, development and customization documenta…

…tion (#1275) * update customization guide, better differentiation between default and multi themes, add all changed files during customization * update chapter styling, move "Visual Studio Code Remote Development" to the correct hierarchy position, update headlines and references * add "icons" to the documentation, describe how to integrate and to add icons
intershop · Oct 13, 2022 · f8eb9b9 · f8eb9b9
1 parent 92f6749
commit f8eb9b9
Show file tree

Hide file tree

Showing 6 changed files with 115 additions and 61 deletions.
diff --git a/docs/concepts/progressive-web-app.md b/docs/concepts/progressive-web-app.md
@@ -12,7 +12,7 @@ In order to be a [Progressive Web Application](https://developer.mozilla.org/en-
 ## Web App Manifest
 
 The Web App Manifest enables the PWA to be installable on home screens of mobile devices.
-The application is easily accessible via a generated link and branding is applied to icons and browser colouring so it poses as a native application.
+The application is easily accessible via a generated link and branding is applied to icons and browser coloring so it poses as a native application.
 
 The manifest in the PWA is theme specific and can be customized in the file `src/assets/themes/<theme>/manifest.webmanifest`.
 
@@ -31,4 +31,8 @@ To activate the service worker run
 node schematics/customization/service-worker true
 ```
 
+To run the project as a Progressive Web App with an enabled [Service Worker](https://angular.io/guide/service-worker-getting-started), use `npm run start` to build and serve the application.
+After that open _http://localhost:4200_ in your browser and test it or run a PWA audit.
+Currently only _localhost_ or _127.0.0.1_ will work with the service worker since it requires _https_ communication on any other domain.
+
 You can also activate the service worker specifically for docker builds by supplying the build argument `serviceWorker=true`.
diff --git a/docs/concepts/styling-behavior.md b/docs/concepts/styling-behavior.md
@@ -34,6 +34,23 @@ The assets folder is the place for any static resources like images, colors, etc
 
 Currently the default font families for the Intershop Progressive Web App [Roboto](https://fonts.google.com/specimen/Roboto) and [Roboto Condensed](https://fonts.google.com/specimen/Roboto+Condensed) are defined as npm dependency.
 
+## Icons
+
+As described above, solid [Font Awesome](https://fontawesome.com/) icons are used.
+To integrate an icon
+
+- open the appropriate page icon details, e.g. https://fontawesome.com/icons/print?s=solid&f=classic
+- copy only the name of the icon without the "fa-" prefix, in this case `print`
+  ```html
+  <i class="fa-solid fa-print"></i>
+  ```
+- use the icon name with following syntax
+  ```html
+  <fa-icon [icon]="['fas', 'print']"></fa-icon>
+  ```
+
+If an icon is not available yet, you need to add it to `src\app\core\icon.module.ts` in the `import {}` and the `constructor(){}`.
+
 ## References
 
 [Guide - Multiple Themes](../guides/multiple-themes.md)
diff --git a/docs/guides/customizations.md b/docs/guides/customizations.md
@@ -34,20 +34,33 @@ Based on this initial version of the Intershop PWA (the latest release), any pro
 
 ## Start Customization
 
-To start customizing, **set a theme** for your customization with the script `node schematics/customization/add --default <prefix>`.
-This will:
+The PWA uses themes which include theme specific
 
-- Add an Angular theme configuration, that is used to configure your individual brand. (see [Guide - Multiple Themes](./multiple-themes.md))
-- Add style files for customization under `src/styles/themes/<prefix>`
-- Add the theme as an active theme in `package.json`. (It will replace all active themes if `--default` is used.)
-- Add a prefix `custom` for new Angular artifacts.
-- Customize ESLint to support your new theme files (specifically, the `project-structure` rule).
+- features and configurations
+- overrides for certain file types (HTML, component styles and TypeScript)
+- styles and static assets
 
-After that we recommend to additionally use the prefix `custom` in every component to further help identifying customized components.
+To start customizing, **set a default theme** for your customization with the script
 
 ```bash
-$ node schematics/customization/add brand
+node schematics/customization/add --default <theme-prefix>
+```
+
+It will:
+
+- add an Angular theme configuration in `angular.json` which is used to configure your individual theme. This **default** theme will be used instead of the existing B2B and B2C themes. It is possible to configure and run multiple themes next to each other, see [Guide - Multiple Themes](./multiple-themes.md)).
+- add the theme-prefix as the active theme in `package.json` and replace all active themes (if `--default` is used)
+- add the theme-prefix specific file `environment.<theme-prefix>.ts` which should be used for further theme configuration
+- add initial style files for styling customization under `src/styles/themes/<theme-prefix>`
+- add the theme-prefix to the override schematic `schematics/src/helpers/override/schema.json`
+- change the project prefix for new Angular artifacts from `ish` to `custom`
+- customize ESLint in `.eslintrc.json` to support your new theme files (specifically, the `project-structure` rule)
+
+> **NOTE:** If only one theme is active, PM2 will run the theme-specific SSR process in cluster mode on the default port (see [Building Multiple Themes](../guides/ssr-startup.md#building-multiple-themes)).
+
+After that we recommend to additionally use the prefix `custom` in every component to further help identifying customized components.
 
+```bash
 $ ng g c shared/components/basket/custom-basket-display
 CREATE src/app/shared/components/basket/custom-basket-display/custom-basket-display.component.ts (275 bytes)
 ...
@@ -135,21 +148,35 @@ Here you can just accept either modification and update the test snapshots.
 
 ### Styling
 
-Changing the styling of **existing components** should be done by adding overrides in the custom theme folder under `src/styles/themes`.
-For this you could copy only the `*.scss` files you need to adapt and fit the reference in your themes `style.scss`.
-Or you can start your styling changes by copying the complete set of standard styles to your themes folder right from the start and do all the changes there.
-Or you can come up with your own preferred way for styling adaptions.
+Changing the styling by applying changes to SCSS files should be done in the custom theme folder `src/styles/themes/<theme-prefix>`.
+This folder is created when adding a new theme, see [Start Customization](../guides/customizations.md#start-customization).
+There are two approaches to apply a theme specific styling:
+
+1. Copy only the `*.scss` files you need to change to your themes folder and adjust the file references. All files which are not overwritten in your theme will be taken from the standard and all changes and bugfixes in these files when migrating the PWA will be applied and used in your project.
+2. Copy the complete set of standard `*.scss` files to your themes folder and adjust the file references. All standard changes and bugfixes to `*.scss` files will not be applied to your theme during a PWA migration.
+
 Just putting a brand override file next to the original file in the `src/styles` folder will not lead to the expected results.
-You should not change relevant information in the global style files under `src/styles`.
+The lookup starts with the file `style.scss` in the theme specific folder.
+
+> **Note:** You should
+>
+> - not change global `*.scss` files in `src/styles` and only apply style changes in your theme folder by copying files into the this folder and adjusting file references
+> - not delete the standard theme folders to prevent merge conflicts when migrating the PWA (changes in standard files but deleted in your project).
 
 When styling is done on component level, all styling is encapsulated to exactly this component (default behavior).
+
 You can re-use variables from the global styling on component level by importing only the styling file that defines the theme variables, e.g.
 
 ```
 @import 'variables';
 ```
 
-Be aware that Visual Studio Code will not resolve the import reference correctly but it works in the build PWA version anyways.
+> **Note:** Be aware that Visual Studio Code will not resolve all import references correctly but it works in the build PWA version anyways.
+
+To add static assets (images, favicon, manifest file), create a theme specific folder in `src/assets/themes/<theme-prefix>` and adjust the theme specific references in the `*.scss` files accordingly.
+
+The `index.html` does not support the theme specific overrides, see [Theme Specific Overrides](../guides/customizations.md#theme-specific-overrides).
+Therefore, any theme specific references have to be changed directly in this file.
 
 ### Dependencies
 

diff --git a/docs/guides/development.md b/docs/guides/development.md
@@ -10,6 +10,8 @@ kb_sync_latest_only
 Developing with the Intershop PWA requires to download and install [Node.js](https://nodejs.org) with the included npm package manager.
 Check the project's `package.json` in the `engines` section for the recommended node version.
 
+> **Note:** If you will work with different Node.js based projects or different PWA versions we recommend using a Node Version Manager (see [NVM](https://github.com/nvm-sh/nvm) or [NVM for Windows](https://github.com/coreybutler/nvm-windows)).
+
 Clone or download the Intershop PWA GitHub project to your computer, e.g.
 
 ```bash
@@ -31,30 +33,51 @@ Use `ng serve --open` to start up the development server and open the Progressiv
 
 For actually setting up a customer project based on the Intershop PWA read the [Customization Guide](customizations.md).
 
-## Development Server
-
-Run `ng serve` or `ng s` for a development server.
+## Local Environment Configuration
 
-The project is also configured to support the usage of an own local environment file `environment.development.ts` that can be configured according to your local development environment needs, e.g. with a different icmBaseURL or different configuration options (see the `environment.model.ts` for the available configuration options).
+The project is configured to support the usage of an own local environment file `environment.development.ts` that can be configured according to your local development environment needs, e.g. with a different icmBaseURL or different configuration options (see the `environment.model.ts` for the available configuration options).
 Overrides in this file will be included in the theme environments and override parts of it.
 For production builds, no overrides should be used.
 The docker build automatically creates this file as an empty file.
 The `environment.development.ts` will be ignored by Git so the developer-specific settings will not be committed and accidentally shared.
 It is initially created when running `npm install`.
 
-This local environment configuration will automatically be used if you start the PWA with `ng serve`.
+The default development configuration is set in `angular.json`:
+
+```
+"defaultConfiguration": "b2b,development",
+```
+
+Therefore the b2b related environment file `environment.b2b.ts` is used when starting the server where further B2B theme specific configurations are made.
+This environment file references two more files:
+
+- `environment.model.ts` where "ENVIRONMENT_DEFAULTS" are taken from
+- `environment.development.ts` where you can add your own configuration only for the local development environment, see overrides explanation above.
+
+## Development Server
+
+Run `ng serve` or `ng s` for a development server.
+
+The [local environment configuration](#local-environment-configuration) will automatically be used if you start the PWA with `ng serve`.
 
 Once the server is running, navigate to http://localhost:4200 in your browser to see the application.
 The app will automatically reload if you change any of the source files.
 
 Running `ng serve --port 4300` will start the server on a different port than the default 4200 port, e.g. if one wants to run multiple instances in parallel for comparison.
 
 Running `ng serve --open` will automatically open a new browser tab with the started application.
+
+Running `ng serve --ssl` will run the development server with `https` support.
+
+The development server can be started with different configurations besides the default configuration as well, e.g. `ng serve --configuration "b2c,production"` or a bit shorter `ng s -c=b2c,production`.
+
 The different start options can be combined.
 
 Further options of the development server can be found running `ng serve --help`.
 
-> **Warning:** DO NOT USE webpack-dev-server IN PRODUCTION environments!
+> **Warning:** DO NOT USE the webpack-dev-server IN PRODUCTION environments!
+
+The project can alternatively be run in server side rendering mode, see [Building and Running Server-Side Rendering](ssr-startup.md).
 
 ## Testing Production Setups
 
@@ -98,6 +121,19 @@ Afterwards a clean `npm install` is performed.
 
 :warning: All unstaged files will be deleted!
 
+### Visual Studio Code Remote Development
+
+An alternative development setup for the PWA is provided when using Visual Studio Code Remote - Containers to work in an isolated pre-configured project development environment.
+
+As prerequisite [Docker](https://docs.docker.com/get-docker/) has to be installed on your development machine.
+Furthermore, [Visual Studio Code](https://code.visualstudio.com) with the [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension has to be used as IDE.
+
+After cloning your local working copy (e.g. with VS Code), VSCode will ask you if you want to reopen the folder in a container.
+By doing this, VS Code will prepare the environment for you inside the container.
+It installs Node.js LTS, Angular CLI and also performs all required setup steps to get you started in an isolated environment.
+
+Open a console in VS Code and run `ng serve` to start developing.
+
 ## Debugging
 
 Tips and tools for debugging Angular applications can be found on the Internet.

diff --git a/docs/guides/getting-started.md b/docs/guides/getting-started.md
@@ -16,35 +16,15 @@ After having cloned the project from the Git repository, open a command line in
 
 The project uses Angular CLI which has to be installed globally.
 Run `npm install -g @angular/cli` once to globally install Angular CLI on your development machine.
-Use `ng serve --open` to start up the development server and open the Progressive Web App in your browser.
-
-The project can alternatively be run in production mode with `npm start`.
-
-## Visual Studio Code Remote Development
 
-An alternative development setup for the PWA is provided when using Visual Studio Code Remote - Containers to work in an isolated pre-configured project development environment.
-
-As prerequisite [Docker](https://docs.docker.com/get-docker/) has to be installed on your development machine.
-Furthermore, [Visual Studio Code](https://code.visualstudio.com) with the [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension has to be used as IDE.
-
-After cloning your local working copy (e.g. with VS Code), VSCode will ask you if you want to reopen the folder in a container.
-By doing this, VS Code will prepare the environment for you inside the container.
-It installs Node.js LTS, Angular CLI and also performs all required setup steps to get you started in an isolated environment.
+Use `ng serve --open` to start up the development server and open the Progressive Web App in your browser.
 
-Open a console in VS Code and run `ng serve` to start developing.
+For more information about environment configuration, server and tools consult the according chapters in the [Development Guide](./development.md).
 
 ## Customization
 
 Before customizing the PWA for your specific needs, have a look at our [Customization Guide](./customizations.md) and also have a look at the current [PWA Guide](https://support.intershop.de/kb/index.php?c=Search&qoff=0&qtext=guide+progressive+web+app) first.
 
-## Development Server
-
-Run `ng serve` or `ng s` for a development server.
-
-For more information consult the chapter in the [Development Guide](./development.md#development-server).
-
-> **Warning**: Do not use _webpack-dev-server_ in production!
-
 ## Deployment
 
 Deployments are generated to the _dist_ folder of the project.
@@ -63,12 +43,6 @@ To run the PWA with multiple channels and [Google PageSpeed](https://developers.
 
 We provide templates for [Kubernetes Deployments](../../schematics/src/kubernetes-deployment) and [DevOps](../../schematics/src/azure-pipeline) for Microsoft Azure.
 
-## Progressive Web App (PWA)
-
-To run the project as a Progressive Web App with an enabled [Service Worker](https://angular.io/guide/service-worker-getting-started), use `npm run start` to build and serve the application.
-After that open _http://localhost:4200_ in your browser and test it or run a PWA audit.
-Currently only _localhost_ or _127.0.0.1_ will work with the service worker since it requires _https_ communication on any other domain.
-
 ## Running Tests
 
 Run `npm test` to start an on the fly test running environment to execute the unit tests via [Jest](https://jestjs.io/) once.

diff --git a/docs/guides/multiple-themes.md b/docs/guides/multiple-themes.md
@@ -7,26 +7,22 @@ kb_sync_latest_only
 
 # Multiple Themes
 
-It is possible to create multiple themes for the PWA.
+It is possible to create multiple themes for the PWA and the Intershop Progressive Web App currently uses multi-theming to provide different features, configurations and styles for the B2B an the B2C application.
 This mechanism uses Angular configurations to replace files for each configuration.
 
-The Intershop Progressive Web App currently uses multi-theming to provide different styles for the B2B an the B2C application.
 The styles for B2B are defined in `src/styles/themes/b2b/style.scss`, for B2C in `src/styles/themes/b2c/style.scss`.
 
-Using schematics to start customizing Intershop Progressive Web App prepares a theme for your own custom styling. (See [Customizations - Start Customization](../guides/customizations.md#start-customization))
+## Developing the PWA with several themes
 
-## Developing the PWA with only one Theme
+Before using multiple themes, use schematics to set your default theme: [Customizations - Start Customization](../guides/customizations.md#start-customization).
 
-To configure and run the Intershop PWA with only one project/brand specific theme start the customization by setting the `<brand>` theme as default theme.
+Now add another theme **without** using `--default`:
 
+```bash
+node schematics/customization/add <theme-prefix>
 ```
-node schematics/customization/add --default <brand>
-```
-
-This configures the `<brand>` theme as the only active theme in the `package.json`.
-Besides that, all necessary configurations in `angular.json`, `.eslintrc.json` and `override/schema.json` are made and a new `src/styles/themes/<brand>` folder and `environment.<brand>.ts` is created that should be used for further project development.
 
-> **NOTE:** If only one theme is active, PM2 will run the theme-specific SSR process in cluster mode on the default port (see [Building Multiple Themes](../guides/ssr-startup.md#building-multiple-themes)).
+This will add the theme to the according files and create styling specific folders and files, see [Customizations - Start Customization](../guides/customizations.md#start-customization).
 
 # Further References