From a60d8f3b82f810011125a8f7ddb046d1ab6a2faf Mon Sep 17 00:00:00 2001 From: MGlatter Date: Wed, 24 May 2023 17:05:59 +0200 Subject: [PATCH] chore: adjustments after reviewing documentation --- docs/concepts/configuration.md | 94 ++++++++++++------------ docs/concepts/pwa-building-blocks.md | 4 +- docs/concepts/styling-behavior.md | 27 ++++--- docs/guides/customizations.md | 66 ++++++++--------- docs/guides/migrations.md | 21 +++--- docs/guides/multi-site-configurations.md | 41 ++++++----- docs/guides/ssr-startup.md | 6 +- docs/guides/themes.md | 92 +++++++++++------------ 8 files changed, 178 insertions(+), 173 deletions(-) diff --git a/docs/concepts/configuration.md b/docs/concepts/configuration.md index 268631d8f9..a6139451dc 100644 --- a/docs/concepts/configuration.md +++ b/docs/concepts/configuration.md @@ -17,15 +17,15 @@ In addition, the PWA, when run with Angular Universal, consists of a server-side ### Angular CLI Environments -The standard way of configuring an Angular Application can be done by managing multiple environment files that are part of the project's source tree, usually located in _src/environments._ To choose one configuration, you have to supply the parameter when building the Angular Application. -See [Guide - Building and Running Server-Side Rendering](../guides/ssr-startup.md) and [Configuring application environments](https://angular.io/guide/build#configure-environment-specific-defaults) for further information. +The standard way of configuring an Angular Application is managing multiple environment files that are part of the project's source tree, usually located in _src/environments._ To choose one configuration, you have to supply the parameter when building the Angular Application. +See [Guide - Building and Running Server-Side Rendering](../guides/ssr-startup.md) and [Configuring Application Environments](https://angular.io/guide/build#configure-environment-specific-defaults) for further information. -Properties supplied with environment files should not be accessed directly in artifacts. -Instead, you need to provide them via `InjectionToken`s to be used in components, pipes or services. -Standard `InjectionToken`s are defined in [`injection-keys.ts`](../../src/app/core/configurations/injection-keys.ts). -To create new keys for the standard PWA, use this file; project customizations should create their own file next to it. +Do not access properties supplied with environment files directly in artifacts. +Instead, you need to provide them via `InjectionTokens` to be used in components, pipes, or services. +Standard `InjectionTokens` are defined in [`injection-keys.ts`](../../src/app/core/configurations/injection-keys.ts). +Use this file to create new keys for the standard PWA; project customizations should create their own file next to it. -First extend the [`environment.model`](../../src/environments/environment.model.ts) to support your new property. +First, extend the [`environment.model`](../../src/environments/environment.model.ts) to support your new property. Then define an `InjectionToken` that can be used to access a certain property later on: ```typescript @@ -35,7 +35,7 @@ export const PROPERTY = createEnvironmentInjectionToken('property'); The new token is automatically initialized with the default value from the Angular CLI environment files. To override it in tests, you can provide it in the `TestBed` configuration. -To inject the property with dependency injection use the helper [`InjectSingle`](../../src/app/core/utils/injection.ts) to properly inherit type information: +To inject the property with dependency injection, use the helper [`InjectSingle`](../../src/app/core/utils/injection.ts) to properly inherit type information: ```typescript import { Inject } from '@angular/core' @@ -48,15 +48,15 @@ import { InjectSingle } from 'ish-core/utils/injection'; constructor(@Inject(PROPERTY) private property: InjectSingle) ``` -As can be seen here, only build-time and deploy-time configuration parameter can be supplied this way. +As can be seen here, only build-time and deploy-time configuration parameters can be supplied this way. ### Node.js Environment Variables When running the application in Angular Universal mode within a _Node.js_ environment, we can additionally access the process environment variables via _process.env_. -This method provides a way to configure the application at deploy time, e.g., when using docker images. +This method provides a way to configure the application at deploy time, e.g., when using Docker images. Configuration can then be consumed and passed to the client side via state transfer using Angular's [TransferState](https://angular.io/api/platform-browser/TransferState). -To introduce a new `TransferState` key it should be added to the [`state-keys.ts`](../../src/app/core/configurations/state-keys.ts). +To introduce a new `TransferState` key, add it to the [`state-keys.ts`](../../src/app/core/configurations/state-keys.ts). ```typescript export const NEW_KEY = makeStateKey('newKey'); @@ -64,7 +64,7 @@ export const NEW_KEY = makeStateKey('newKey'); The actual transfer is handled by the [`app.server.module.ts`](../../src/app/app.server.module.ts) where the mapping of the environment variable is done. -Accessing the transferred state in a service or a component is pretty straight forward: +Accessing the transferred state in a service or a component is done as follows: ```typescript import { NEW_KEY } from 'ish-core/configurations/state-keys'; @@ -80,7 +80,7 @@ if (!SSR) { ### NgRx Configuration State -Previous ways were mainly handling deployment- or build-time-related means to configure an Angular application. +The previous ways were mainly handling deployment- or build-time-related means to configure an Angular application. All further configuration that has some kind of runtime flexibility, especially configuration that is retrieved via REST calls from the ICM, has to be handled in the NgRx store and to be used throughout the application with selectors. Effects and actions should be used to manipulate those settings. @@ -99,9 +99,9 @@ In general, properties available at build time can only be supplied by Angular C ### Deployment Settings -Deployment settings do not influence the build process and therefore can be set in more flexible manners. +Deployment settings do not influence the build process and, therefore, can be set in more flexible manners. The main criteria of this category is the fact that deployment settings do not change during runtime. -The most common way of supplying them can be implemented by using Angular CLI environment files and `InjectionToken`s for distribution throughout the application's code. +The most common way of supplying them can be implemented by using Angular CLI environment files and `InjectionTokens` for distribution throughout the application's code. An example for this kind of settings are breakpoint settings for the different device classes of the application touch points. @@ -112,12 +112,12 @@ Deployment settings can also be set by using `TransferState` to use environment The most flexible kind of settings, which can also change when the application runs, are runtime settings. Angular CLI environment files cannot provide a way to handle those. Only the NgRx store can do that. -Therefore only NgRx means should be used to supply them. +Thus, only NgRx means should be used to supply them. Nevertheless, default values can be provided by environment files and can later be overridden by system environment variables. Everything managed in the NgRx state is accumulated on the server side and sent to the client side with the initial HTML response. -To access these properties we provide the [`StatePropertiesService`](../../src/app/core/utils/state-transfer/state-properties.service.ts), which takes care of retrieving the configuration either from the configuration state, an environment variable or the environment.ts (in that order). +To access these properties, we provide the [`StatePropertiesService`](../../src/app/core/utils/state-transfer/state-properties.service.ts), which takes care of retrieving the configuration either from the configuration state, an environment variable or the _environment.ts_ (in that order). ### Configurations REST Resource @@ -133,9 +133,9 @@ The ICM configurations information can be accessed through the [`getServerConfig At first, the PWA has to be connected with the corresponding ICM. This can be done by modifying environment files or by setting the environment variable `ICM_BASE_URL` for the process running the _Node.js_ server. The latter is the preferred way. -See also [Guide - Building and Running Server-Side Rendering](../guides/ssr-startup.md) +See also [Guide - Building and Running Server-Side Rendering](../guides/ssr-startup.md). -Independent of where and how you deploy the Angular Universal application, be it in a docker container or plain, running on Azure, with or without service orchestrator, setting the base URL provides the most flexible way of configuring the PWA. +Independent of where and how you deploy the Angular Universal application, be it in a Docker container or plain, running on Azure, with or without service orchestrator, setting the base URL provides the most flexible way of configuring the PWA. Refer to the documentation for mechanisms of your environment on how to set and pass environment variables. ### Settings for Channels and Applications @@ -151,26 +151,26 @@ Of course, the ICM server must supply appropriate REST resources to leverage fun ### Available Feature Toggles -| feature toggle | description of enabled feature | +| Feature Toggle | Description of Enabled Feature | | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -| compare | product compare feature (additional configuration via `dataRetention` configuration options) | -| contactUs | allows the user to contact the website provider via a contact web form | -| extraConfiguration | fetch extra configuration information from _Configuration_ CMS component for [configurable themes etc.](../guides/themes.md#configurable-theme) | -| productNotifications | product notifications feature for price and in stock notifications | -| rating | display product ratings | -| recently | display recently viewed products (additional configuration via `dataRetention` configuration options) | -| storeLocator | display physical stores and their addresses | +| compare | Product compare feature (additional configuration via `dataRetention` configuration options) | +| contactUs | Allow the user to contact the website provider via a contact web form | +| extraConfiguration | Fetch extra configuration information from _Configuration_ CMS component for [configurable themes etc.](../guides/themes.md#configurable-theme) | +| productNotifications | Product notifications feature for price and in stock notifications | +| rating | Display product ratings | +| recently | Display recently viewed products (additional configuration via `dataRetention` configuration options) | +| storeLocator | Display physical stores and their addresses | | **B2B Features** | | -| businessCustomerRegistration | create business customers on registration | -| costCenters | cost center feature | -| messageToMerchant | write a message to the merchant at checkout | -| orderTemplates | order template feature | -| punchout | punchout feature | -| quickorder | quick order page and direct add to cart input | -| quoting | quoting feature | +| businessCustomerRegistration | Create business customers on registration | +| costCenters | Cost center feature | +| messageToMerchant | Write a message to the merchant at checkout | +| orderTemplates | Order template feature | +| punchout | Punchout feature | +| quickorder | Quick order page and direct add to cart input | +| quoting | Quoting feature | | **B2C Features** | | -| guestCheckout | allow unregistered guest checkout | -| wishlists | wishlist product list feature | +| guestCheckout | Allow unregistered guest checkout | +| wishlists | Wishlist product list feature | | **Third-party Integrations** | | | maps | Google Maps integration for locating stores (used with the `storeLocator` feature, additional configuration via `gmaKey`) | | sentry | Sentry error tracking and monitoring (additional configuration via `sentryDSN`) | @@ -180,7 +180,7 @@ Of course, the ICM server must supply appropriate REST resources to leverage fun ### Configuring Features The configuration of features can be done statically by the Angular CLI environment property `features` (string array) or the environment parameter `FEATURES` (comma-separated string list). -To configure it dynamically, use the PWA URL parameter `features` (comma-separated string list) during URL rewriting in the reverse proxy. (see [Concept - Multi-Site Handling][concept-multi-site]) +To configure it dynamically, use the PWA URL parameter `features` (comma-separated string list) during URL rewriting in the reverse proxy (see [Concept - Multi-Site Handling][concept-multi-site]). ### Programmatically Switching Features @@ -188,6 +188,10 @@ Various means to activate and deactivate functionality based on feature toggles **Guard** +Add the Guard as `canActivate` to the routing definition. +Additionally, you have to supply a `data` field called `feature`, containing a string that determines for which feature the route should be active. +If the feature is deactivated, the user is sent to the error page on accessing. + ```typescript const routes: Routes = [ { @@ -199,10 +203,6 @@ const routes: Routes = [ ... ``` -Add the Guard as `canActivate` to the routing definition. -Additionally, you have to supply a `data` field called `feature`, containing a string that determines for which feature the route should be active. -If the feature is deactivated, the user is sent to the error page on accessing. - **Directive** ```html @@ -239,27 +239,27 @@ Switching features in tests can be triggered by calling [`FeatureToggleModule.sw You can set the default locale statically by modifying the order of the provided locales in the Angular CLI environment files. The first locale is always chosen as the default one. -To dynamically set the default locale, use the URL parameter `lang` when rewriting the URL in the reverse proxy (see [Concept - Multi-Site Handling][concept-multi-site]). +To set the default locale dynamically, use the URL parameter `lang` when rewriting the URL in the reverse proxy (see [Concept - Multi-Site Handling][concept-multi-site]). ## Extend Locales -To add other languages except English, German or French: +To add other languages except English, German, or French: 1. Add the locale to the ICM channel configuration. -2. Create a new json-mapping-file with all translations, e.g., `src/assets/i18n/nl_NL.json`. +2. Create a new json mapping file with all translations, e.g., `src/assets/i18n/nl_NL.json`. 3. (optional) Add the new language switch translation keys to other locales: - _example de_DE.json_ + _example de_DE.json_: ``` "locale.nl_NL.long": "Niederländisch", "locale.nl_NL.short": "nl", ``` -4. (optional) Add the locale specific currency filter to the environments under `src/environments`, e.g. +4. (optional) Add the locale-specific currency filter to the environments under `src/environments`, e.g., ```typescript localeCurrencyOverride: { @@ -280,7 +280,7 @@ To add other languages except English, German or French: registerLocaleData(localeNl); ``` -7. Add new json-mapping-file import to `LOCAL_TRANSLATIONS` injection token in the [`InternationalizationModule`](../../src/app/core/internationalization.module.ts) provider: +7. Add new json mapping file import to `LOCAL_TRANSLATIONS` injection token in the [`InternationalizationModule`](../../src/app/core/internationalization.module.ts) provider: ```typescript providers: [ diff --git a/docs/concepts/pwa-building-blocks.md b/docs/concepts/pwa-building-blocks.md index 574df81dd3..c76e8e6cf9 100644 --- a/docs/concepts/pwa-building-blocks.md +++ b/docs/concepts/pwa-building-blocks.md @@ -35,7 +35,7 @@ Nginx enables the following features to be used in an Intershop PWA deployment: - Uncomplicated caching of PWA server-side rendering responses provided by the upstream Angular Universal server. - Handling of multiple channels via URL parameters in conjunction with SSR (see [Multi-Site Handling](multi-site-handling.md)). -- Customizable compression for downstream services +- Customizable compression for downstream services. - Device type detection to ensure a correct pre-render, adapted to the incoming user agent. For an overview of the ever-growing list of third party integrations relating to nginx and deployment in general, see [Third-party Integrations](../README.md#third-party-integrations). @@ -68,7 +68,7 @@ Read on for a step-by-step walkthrough of the initial connection request. 6. The initial page response is displayed to the user and the Angular Client application boots up in the browser. -7. Once booted up, additional REST Calls are directed straight to the ICM and the PWA acts as a single-page application. No further HTML pages are requested. +7. Once booted up, additional REST calls are directed straight to the ICM, and the PWA acts as a single-page application. No further HTML pages are requested. ## Deployment Without Nginx diff --git a/docs/concepts/styling-behavior.md b/docs/concepts/styling-behavior.md index 9b94f17a95..cba4dd447b 100644 --- a/docs/concepts/styling-behavior.md +++ b/docs/concepts/styling-behavior.md @@ -18,7 +18,7 @@ The styling integration is configured in the _/src/themes/main.scss_ of the proj Instead of the Bootstrap 3 Glyphicons, the current styling uses free solid icons of [Font Awesome](https://fontawesome.com/). The styling itself is integrated into the project as global style via a _style.scss_ that is referenced in the _angular.json_ and is compiled automatically (see also [Guide - Themes](../guides/themes.md)). -Throughout the whole Intershop Progressive Web App, there are almost no component specific `styleUrls` or `styles` properties. +Throughout the whole Intershop Progressive Web App, there are almost no component-specific `styleUrls` or `styles` properties. The [Javascript part of Bootstrap](https://getbootstrap.com/docs/4.6/getting-started/javascript/) for the behavior is not directly used from the Bootstrap dependency since this implementation is jQuery based and not really suited to work in an Angular environment. For Bootstrap 4, [ng-bootstrap](https://ng-bootstrap.github.io) provides _Bootstrap widgets the angular way_. @@ -37,17 +37,20 @@ Currently the default font families for the Intershop Progressive Web App [Robot ## 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 - - ``` -- use the icon name with following syntax - ```html - - ``` +To integrate an icon: + +1. Open the appropriate page icon details, e.g. https://fontawesome.com/icons/print?s=solid&f=classic +2. Copy only the name of the icon without the "fa-" prefix, in this case `print` + +```html + +``` + +3. Use the icon name with following syntax + +```html + +``` 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(){}`. diff --git a/docs/guides/customizations.md b/docs/guides/customizations.md index 11be6b1b89..a6a8cb8eee 100644 --- a/docs/guides/customizations.md +++ b/docs/guides/customizations.md @@ -7,9 +7,9 @@ kb_sync_latest_only # Customizations -When customizing the PWA, always keep in mind that you probably want to upgrade from time to time and will have to merge incoming changes into your codebase. -We therefore suggest that you do not edit existing files all too much and keep them as intact as possible. -In this document we provide a couple of rules that you should follow. +When customizing the PWA, always keep in mind that you may want to upgrade from time to time and will have to merge incoming changes into your codebase. +We, therefore, suggest not to edit existing files to a large extent and to keep them as intact as possible. +In this document we provide a couple of rules to follow. Generally speaking: > Keep modifications on existing files as minimal as possible! @@ -18,23 +18,23 @@ It can be tempting to always modify existing templates, component and style file However, when merging incoming upgrades the number of merge conflicts can possibly be large. So if you want to upgrade to new PWA versions later, stick to the following recommendations. -## Setup an Intershop PWA-based Project +## Set up an Intershop PWA-based Project When initially setting up an Intershop PWA-based project it is not advisable to clone the complete GitHub repository of the Intershop PWA. -All that is initially needed is the `master` branch that includes the released versions of the PWA. +All that is needed initially is the `master` branch that includes the released versions of the PWA. This can be achieved with the following Git command. ``` git clone --single-branch --branch master --origin intershop https://github.com/intershop/intershop-pwa.git project-pwa ``` -This command clones only the `master` branch from the GitHub repository of the Intershop PWA with the remote name `intershop` (not `origin` that will be needed later on for the projects own remote Git repository) into a folder `project-pwa` (instead of `intershop-pwa`). +This command clones only the `master` branch from the GitHub repository of the Intershop PWA with the remote name `intershop` (not `origin` that will be needed later on for the project's own remote Git repository) into a folder `project-pwa` (instead of `intershop-pwa`). Based on this initial version of the Intershop PWA (the latest release), any project customizations can be started. ## Start Customization -The PWA uses themes which include theme specific +The PWA uses themes which include theme-specific - features and configurations - overrides for certain file types (HTML, component styles and TypeScript) @@ -76,12 +76,12 @@ That way the modifications on existing code are most often kept to a single line When **heavily customizing** existing components it is better to **copy components** and change all references. If 20 % of the component has to be changed, it is already a good idea to duplicate it. That way incoming changes will not affect your customizations. -Typical hot-spots where copying is a good idea are header-related or product-detail-page related customizations. +Typical hot-spots where copying is a good idea are header-related or product-detail-page-related customizations. #### Theme Specific Overrides The [customized webpack build](./optimizations.md) supports replacing any file with an environment suffix in front of the file extension. -If you for example want to customize the template `product-detail.component.html`, put your customized content in the parallel file `product-detail.component.theme.html` and run a build with `--configuration=theme`. +If you, for example, want to customize the template `product-detail.component.html`, put your customized content in the parallel file `product-detail.component.theme.html` and run a build with `--configuration=theme`. Then this overridden component template will be swapped in. This also works for multiple configurations: `product-detail.component.foo.bar.baz.html` will be active for configurations `foo`, `bar` and `baz`, but not for `foobar`. @@ -102,7 +102,7 @@ As an example, imagine the following files/overrides exist: - In a build for theme `foo`, the file `my.component.foo.html` will be swapped in. - In a build for theme `bar`, the file `my.component.bar.baz.html` will be swapped in. - In a build for theme `foobar`, the file `my.component.all.html` will be swapped in. -- The file `my.component.html` won't be used for any builds. +- The file `my.component.html` will not be used for any builds. ##### Schematic Support @@ -150,13 +150,13 @@ Here you can just accept either modification and update the test snapshots. Changing the styling by applying changes to SCSS files should be done in the custom theme folder `src/styles/themes/`. 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: +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. +- 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. +- 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 theme override file next to the original file in the `src/styles` folder will not lead to the expected results. -The lookup starts with the file `style.scss` in the theme specific folder. +The lookup starts with the file `style.scss` in the theme-specific folder. > **Note:** You should > @@ -166,7 +166,7 @@ The lookup starts with the file `style.scss` in the theme specific folder. When styling is done on component level, all styling is encapsulated to exactly this component (default behavior). On component level, theme-specific overrides for `.scss` files work as expected. -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. +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'; @@ -178,10 +178,10 @@ You can re-use variables from the global styling on component level by importing ### Static Assets -To add static assets (images, favicon, manifest file), create a theme specific folder in `src/assets/themes/` and adjust the theme specific references in the `*.scss` files accordingly. +To add static assets (images, favicon, manifest file), create a theme-specific folder in `src/assets/themes/` and adjust the theme-specific references in the `*.scss` files accordingly. -The `index.html` does not support theme specific overrides, see [Theme Specific Overrides](../guides/customizations.md#theme-specific-overrides). -For this file, any theme specific differences are handled via [theme.service.ts](../../src/app/core/utils/theme/theme.service.ts). +The `index.html` does not support theme-specific overrides, see [Theme Specific Overrides](../guides/customizations.md#theme-specific-overrides). +For this file, any theme-specific differences are handled via [theme.service.ts](../../src/app/core/utils/theme/theme.service.ts). ### Dependencies @@ -196,7 +196,7 @@ In theory the customized PWA project can re-use our Page Objects without much ad Specs should be copied and adapted for the project to use correct demo data. When executing tests, the test itself requires an appropriate demo server to be launched before the run. We currently use patterns in the test name to determine the channel for which the test can be run. -E.g. `login-user.b2b.b2c.e2e-spec.ts` can be run on with the inSPIRED B2C and B2B channels. +For example, `login-user.b2b.b2c.e2e-spec.ts` can be run for the inSPIRED B2C and B2B channels. The same system can be adopted for customization projects. ## Import Changes from New PWA Release (Migration) @@ -224,7 +224,7 @@ git checkout -b migration_to_1.1 ``` Now the Git commits of the new Intershop PWA release will be cherry picked into this migration branch. -For this, one needs to provide the wanted commit range which should be possible by using the Intershop PWA version tags, e.g. `1.0.0` to `1.1.0` (since the end tag is a merge commit it will lead to an error at the end of the cherry pick, to prevent this only the commits up to the second parent should be used with `^2`). +For this, one needs to provide the wanted commit range which should be possible by using the Intershop PWA version tags, e.g., `1.0.0` to `1.1.0` (since the end tag is a merge commit it will lead to an error at the end of the cherry pick, to prevent this only the commits up to the second parent should be used with `^2`). If there are any problems with the tags, using the specific commit SHAs should always work. ``` @@ -234,24 +234,24 @@ git cherry-pick 1.0.0..1.1.0^2 Now each commit of the new Intershop PWA release is applied to the custom project context. Thus, if any merge conflicts arise, this will be within the specific Intershop PWA commit context and should be mergeable with the information and diff provided for this commit in the GitHub repository. -If merge conflicts need to be resolve it is good to disable any pre-commit hooks during the migration. -For this set `HUSKY=0` as environment variable. +If merge conflicts need to be resolved, it is advisable to disable any pre-commit hooks during the migration. +For this purpose, set `HUSKY=0` as environment variable. -After successfully going through the range cherry pick (with `git commit` and `git cherry-pick --continue` after each resolved merge conflict), an `npm install` will probably be required and one needs to check whether the project code still works as expected. +After successfully going through the range cherry pick (with `git commit` and `git cherry-pick --continue` after each resolved merge conflict), an `npm install` will probably be required and you need to check whether the project code still works as expected. Starting the server or `npm run check` are good basic tests for that. ### 2. Rebase Commits of New Release -For the `git rebase --onto` approach one needs to create a new branch based on the release tag of the Intershop PWA one wants to migrate to, naming it, for example, `migration_to_1.1`. +For the `git rebase --onto` approach you need to create a new branch based on the release tag of the Intershop PWA you want to migrate to, naming it, for example, `migration_to_1.1`. ``` git checkout -b migration_to_1.1 1.1.0 ``` Now the branch with the Git commits of the new Intershop PWA release will be rebased onto the current project's main development branch. -For this, one needs to provide the branch name of the target branch to rebase onto. +To do so, you need to provide the branch name of the target branch to rebase onto. In addition, a commit is needed where the current migration branch should be "cut off". -This is usually the current version tag of the Intershop PWA used currently in the custom project, e.g. `1.0.0`. +This is usually the current version tag of the Intershop PWA used currently in the custom project, e.g., `1.0.0`. If there are any problems with the tag, using the specific commit SHAs should always work. ``` @@ -261,10 +261,10 @@ git rebase --onto develop 1.0.0 Now each commit of the new Intershop PWA release is applied to the custom project context. Thus, if any merge conflicts arise, this will be within the specific Intershop PWA commit context and should be mergeable with the information and diff provided for this commit in the GitHub repository. -If merge conflicts need to be resolve it is good to disable any pre-commit hooks during the migration. -For this set `HUSKY=0` as environment variable. +If merge conflicts need to be resolved, it is advisable to disable any pre-commit hooks during the migration. +For this purpose, set `HUSKY=0` as environment variable. -After successfully going through the rebase onto (with `git rebase --continue` after each resolved merge conflict), an `npm install` will probably be required and one needs to check whether the project code still works as expected. +After successfully going through the rebase onto (with `git rebase --continue` after each resolved merge conflict), an `npm install` will probably be required and you need to check whether the project code still works as expected. Starting the server or `npm run check` are good basic tests for that. ### 3. Merge the New Release in its Entirety @@ -273,21 +273,21 @@ This is also a possible way to migrate your custom project to the latest version Just add the Intershop PWA GitHub repository as a second remote in your project and `git merge` the release branch. -> Prior to 0.16.1 the entire git history changed completely. -> Please see [Merging 0.16.1 as 2nd upstream repository: "refusing to merge unrelated histories](https://github.com/intershop/intershop-pwa/issues/62) for suggestions on importing the new history. +> Prior to 0.16.1 the entire Git history changed completely. +> Please see [Merging 0.16.1 as 2nd upstream repository: "refusing to merge unrelated histories"](https://github.com/intershop/intershop-pwa/issues/62) for suggestions on importing the new history. ## Hints - The Intershop PWA project is configured to follow consistent formatting rules. For a better overview of relevant changes and less merge efforts it is advised to adhere to these rules during project development as well. - For this, one needs to configure one's IDE accordingly. + For this, you need to configure your IDE accordingly. The fitting Visual Studio Code configuration is part of the project. - The Intershop PWA project configures and contains a set of linting rules that also aim to ensure a consistent code style and are intended to prevent any coding patterns that are considered problematic. It is advised to follow these rules in customer projects as well. If some rules are actually unwanted in a project, it is best to disable these configurations but to keep all other checks intact and to address any violations. - Keep the unit tests running and write new ones. This will also help ensuring not to break any existing functionality after a migration. -- `npm run check` should run through successfully on local development environments after a feature or bugfix or migration has finished. +- `npm run check` should run through successfully on local development environments after a feature or bug fix or migration has finished. This check can be left to a CI pipeline as well but the task should be configured in a way that fits the requirements of the project. # Further References diff --git a/docs/guides/migrations.md b/docs/guides/migrations.md index d801f8d874..6b4d7fd716 100644 --- a/docs/guides/migrations.md +++ b/docs/guides/migrations.md @@ -9,22 +9,23 @@ kb_sync_latest_only ## 4.0 to 4.1 -The Intershop PWA now uses Node.js 18.16.0 LTS with the corresponding npm version 9.5.1 to resolve an issue with Azure docker deployments (see #1416). +The Intershop PWA now uses Node.js 18.16.0 LTS with the corresponding npm version 9.5.1 to resolve an issue with Azure Docker deployments (see #1416). -As a leftover adaption regarding the switch from deprecated class-based route guards in favor of functional guards the `addGlobalGuard` function was adapted to actually work with functional guards. -If the `addGlobalGuard` function is used for customizations make sure it now works as expected. +As a leftover adaption regarding the switch from deprecated class-based route guards in favor of functional guards the `addGlobalGuard` function was adapted to work with functional guards. +If the `addGlobalGuard` function is used for customizations, make sure it now works as expected. -The input parameter `id` of the component `ish-product-quantity` caused issues with duplicate IDs within the page html, therefore it was renamed to `elementId`. -If the input parameter 'id' of this component has already been used it has to be renamed accordingly. +The input parameter `id` of the component `ish-product-quantity` caused issues with duplicate IDs within the page html. +Therefore, it was renamed to `elementId`. +If the input parameter 'id' of this component has already been used, it has to be renamed accordingly. The `ishIntersectionObserver` returns all 3 `IntersectionStatus` change events `Visible`, `Pending` and now `NotVisible` as well. The custom project code needs to be adapted if it does not filter the events where it is used (e.g `if (event === 'Visible')`). -The two standard themes `b2b` and `b2c` where refactored so the `b2c` theme could be changed into a [configurable theme](./themes.md#configurable-theme) that uses CSS custom properties (CSS variables). +The two standard themes `b2b` and `b2c` where refactored in such a way that the `b2c` theme could be changed into a [configurable theme](./themes.md#configurable-theme) that uses CSS custom properties (CSS variables). Since SCSS color calculations do not work with CSS custom properties (they need real values instead of `var(--corporate-primary)`), SCSS functions like `darken()` and `lighten()` were removed from the standard Intershop PWA SCSS styling. Existing projects that do not want to use a configurable theme do not need to apply these changes to their custom styling. -To use the new [configurable theme](./themes.md#configurable-theme) feature the feature toggle `extraConfiguration` needs to be enabled. +To use the new [configurable theme](./themes.md#configurable-theme) feature, the feature toggle `extraConfiguration` needs to be enabled. ## 3.3 to 4.0 @@ -33,7 +34,7 @@ To migrate to this version, it is advised to delete the locale `package-lock.jso The project was updated to work with Angular 15. This includes the removal of the Browserslist configuration and an updated TypeScript compiler `target` and `lib` to `ES2022` (for browser support requirements that differ from the Angular 15 standard configuration see the [configuring browser compatibility](https://angular.io/guide/build#configuring-browser-compatibility) guide and the [TypeScript configuration](https://angular.io/guide/typescript-configuration) reference). -Adaptions of the Schematics configurations and tests were necessary as well. +Adaptions of the Schematics configurations and tests were also necessary. In addition, all other dependencies were updated as well and resulted in necessary Stylelint and Jest test adaptions. The placeholder for theme-specific assets and styles has been changed from `placeholder` to `theme_placeholder`. @@ -104,7 +105,7 @@ To migrate to this new account navigation item handling, any account navigation The deprecated SSR environment variable `ICM_IDENTITY_PROVIDER` was completely removed. Use the variable `IDENTITY_PROVIDER` instead to select the identity provider to be used if it is not the default `ICM`. -We removed the default `identityProvider` configuration from `environment.model.ts` so only the hardcoded fallback from `configuration.effects.ts` works as fallback. +We removed the default `identityProvider` configuration from `environment.model.ts`, so only the hardcoded fallback from `configuration.effects.ts` works as fallback. The deprecated properties `templateOptions` and `expressionProperties` have been removed from the `FormlyFieldConfiguration` object. Current projects **must** use the new properties for all formly field configurations. @@ -391,7 +392,7 @@ You must **not** edit any file inside that `dist` folder, since this would inclu ## 0.31 to 1.0 -The Angular configuration mechanism of the Intershop PWA was refactored to support running multiple configurations in one docker image (see [Guide - Multiple Themes](./themes.md)). +The Angular configuration mechanism of the Intershop PWA was refactored to support running multiple configurations in one Docker image (see [Guide - Multiple Themes](./themes.md)). This now means that the former `environment.local.ts` which had a standalone configuration can no longer be supported. Instead, theme-specific environments exist for `default` and `blue`, and development settings can be overridden in `environment.development.ts`, which are imported into the theme-specific configurations (see [Guide - Development](./development.md#development-server)). `npm install` will create an initial version of the `environment.development.ts` that can be filled with the needed information from `environment.local.ts`. diff --git a/docs/guides/multi-site-configurations.md b/docs/guides/multi-site-configurations.md index b25936b275..f10774d8c4 100644 --- a/docs/guides/multi-site-configurations.md +++ b/docs/guides/multi-site-configurations.md @@ -41,20 +41,20 @@ The `channel` property is also mandatory. All other properties are optional: -- **application**: The ICM application -- **identityProvider**: The active identity provider for this site -- **features**: Comma-separated list of activated features -- **addFeatures**: Comma-separated list of additional features extending defaults -- **lang**: The default language as defined in the Angular CLI environment -- **currency**: The default currency for this channel -- **theme**: The theme used for the channel (see [Guide - Themes](./themes.md)) +- **application**: the ICM application +- **identityProvider**: the active identity provider for this site +- **features**: comma-separated list of activated features +- **addFeatures**: comma-separated list of additional features extending defaults +- **lang**: the default language as defined in the Angular CLI environment +- **currency**: the default currency for this channel +- **theme**: the theme used for the channel (see [Guide - Themes](./themes.md)) - **protected**: Selectively disable basic auth for a given domain and/or baseHref. Only applies in combination with globally activated nginx basic authentication. Dynamically directing the PWA to different ICM installations can be done by using: -- **icmHost**: The domain in which the ICM instance runs (without protocol and port) -- **icmPort**: Optional, required if the port differs from 443 -- **icmScheme**: Optional, required if the protocol differs from 'https' +- **icmHost**: the domain in which the ICM instance runs (without protocol and port) +- **icmPort**: optional, required if the port differs from 443 +- **icmScheme**: optional, required if the protocol differs from 'https' Multiple channels can also be configured via context paths that re-configure the PWA upstream to use a different `baseHref` for each channel. @@ -93,7 +93,7 @@ Such a configuration is shown in the following configuration that sets different ## Examples -### One domain, One Channel, Multiple Locales +### One Domain, One Channel, Multiple Locales This setup is used by our demo application. It uses a single channel and a static URL, while locales are changed via a context path (`baseHref`) parameter. @@ -116,7 +116,8 @@ This results in URLs like this: lang: fr_FR ``` -It is possible to extend this configuration to use different channels per context path - to do this, replace the `default` value with your desired channel. +It is possible to extend this configuration to use different channels per context path. +To do this, replace the `default` value with your desired channel. ### Multiple Domains, Multiple Channels, Multiple Locales @@ -145,10 +146,10 @@ This results in URLs like this: channel: inspired-inTRONICS-FR ``` -### Multiple Subdomains, Multiple channels, Multiple Locales +### Multiple Subdomains, Multiple Channels, Multiple Locales It is also possible to configure different subdomains by changing the regular expression that matches the domain. -This works also in conjunction with context paths. +This also works in conjunction with context paths. This results in URLs like this: `de.pwademo.com`, `fr.pwademo.com`, `ca.pwademo.com/en` @@ -200,7 +201,7 @@ To see what is possible through multi-site handling, have a look at this extende features: quoting ``` -### Extended Example with two domains, one with basic auth (except /fr), the other without +### Extended Example with Two Domains, One with Basic Auth (Except /fr), the Other Without ```yaml de.+\.com: @@ -217,17 +218,17 @@ ca.+\.com: lang: en_US ``` -## Integrate your multi-site configuration with the language switch +## Integrate Your Multi-Site Configuration with the Language Switch To construct new multi-site URLs when switching between languages, the PWA uses the `multi-site.service.ts`. -The `getLangUpdatedUrl` is called with the desired locale string, current url and current baseHref. -From this it constructs a new URL, conforming to our multi-site setup (see [One domain, one channel, multiple locales](#one-domain-one-channel-multiple-locales)). +The `getLangUpdatedUrl` is called with the desired locale string, current url, and current baseHref. +From this it constructs a new URL, conforming to our multi-site setup (see [One Domain, One Channel, Multiple Locales](#one-domain-one-channel-multiple-locales)). -To control the transformation of urls, the `multiSiteLocaleMap` environment variable is used. +To control the transformation of URLs, the `multiSiteLocaleMap` environment variable is used. Depending on your needs, `multiSiteLocaleMap` can be set in either the `environment.ts` or as an environment variable (`MULTI_SITE_LOCALE_MAP`). See [`docker-compose.yml`](../../docker-compose.yml) for a commented out example or [`environment.model.ts`](../../src/environments/environment.model.ts) for the default value. -In case you want to disable this functionality, simply override the default environment variable `multiSiteLocaleMap` with `undefined` or `MULTI_SITE_LOCALE_MAP` with `false`. +In case you want to disable this functionality, override the default environment variable `multiSiteLocaleMap` with `undefined` or `MULTI_SITE_LOCALE_MAP` with `false`. In case you want to extend this functionality to work with more locales, extend the default environment variable `multiSiteLocaleMap` with your additional locales. diff --git a/docs/guides/ssr-startup.md b/docs/guides/ssr-startup.md index 9ad5f7cee2..52c97d1ca7 100644 --- a/docs/guides/ssr-startup.md +++ b/docs/guides/ssr-startup.md @@ -66,8 +66,8 @@ Make sure to use them as written in the table below. | | GMA_KEY | string | API key for Google Maps | | | SENTRY_DSN | string | Sentry DSN URL for using Sentry Error Monitor | | | PROMETHEUS | switch | Exposes Prometheus metrics | -| | IDENTITY_PROVIDER | string | ID of the default Identity Provider if other than `ICM` | -| | IDENTITY_PROVIDERS | JSON | Configuration of additional Identity Providers besides the default `ICM` | +| | IDENTITY_PROVIDER | string | ID of the default identity provider if other than `ICM` | +| | IDENTITY_PROVIDERS | JSON | Configuration of additional identity providers besides the default `ICM` | ## Development @@ -84,7 +84,7 @@ If the SSR development environment needs to run with `https`, this can be achiev npm run start:ssr-dev -- --ssl ``` -To provide specific certificates that can be valid in your local development environment this is an example command how to achieve this. +The following is an example command for how to provide specific certificates that can be valid in your local development environment: ``` ng run intershop-pwa:serve-ssr --ssl --ssl-cert ~/work/wildcard-certificates/wildcard_localdev.de/cert.pem --ssl-key ~/work/wildcard-certificates/wildcard_localdev.de/privkey.pem --host host.localdev.de diff --git a/docs/guides/themes.md b/docs/guides/themes.md index 6ed941a2b3..b93f67c754 100644 --- a/docs/guides/themes.md +++ b/docs/guides/themes.md @@ -9,12 +9,12 @@ kb_sync_latest_only ## Multiple Themes -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. +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 and the B2C application. This mechanism uses Angular configurations to replace files for each configuration. The styles for B2B are defined in `src/styles/themes/b2b/style.scss`, for B2C in `src/styles/themes/b2c/style.scss`. -## Developing the PWA with several themes +## Developing the PWA with Several Themes Before using multiple themes, use schematics to set your default theme: [Customizations - Start Customization](./customizations.md#start-customization). @@ -24,26 +24,26 @@ Now add another theme **without** using `--default`: node schematics/customization/add ``` -This will add the theme to the according files and create styling specific folders and files, see [Customizations - Start Customization](./customizations.md#start-customization). +This will add the theme to the according files and create styling-specific folders and files, see [Customizations - Start Customization](./customizations.md#start-customization). ## Configurable Theme -> **Note** -> To use this feature the feature toggle `extraConfiguration` needs to be enabled. +> **Note:** +> To use this feature, the feature toggle `extraConfiguration` needs to be enabled. -> **Warning** -> Multiple themes (e.g. for different channels or brands) increase the build and deployment time of the PWA SSR container. -> That is okay for a limited number of themes (2-3) but will become problematic the more the number grows. -> A solution to this problem could be to use only one theme that can be configured at runtime for the different channels/brands. +> **Warning:** +> Multiple themes (e.g., for different channels or brands) increase the build and deployment time of the PWA SSR container. +> This is okay for a limited number of themes (2-3) but will become problematic the higher the number gets. +> A solution could be to use only one theme that can be configured for the different channels/brands at runtime. -With the Intershop PWA 4.1 the two standard themes `b2b` and `b2c` where refactored so the `b2c` theme could be changed into a configurable theme. +With the Intershop PWA 4.1 the two standard themes `b2b` and `b2c` where refactored so that the `b2c` theme could be changed into a configurable theme. Configurable in this context means adaptable at runtime [using CSS custom properties (CSS variables)](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties). -This way only one configurable theme is needed at build time that can then be adapted through an ICM backoffice CMS _Configuration_ component on channel or application level. -This is different to compiling different themes at build time e.g. with SCSS variables and using them for different channels through the [Multi Site Configuration](./multi-site-configurations.md). +This way only one configurable theme is needed at build time that can then be adapted through an ICM back office CMS _Configuration_ component on channel or application level. +This differs from compiling different themes at build time, e.g., with SCSS variables and using them for different channels through the [Multi Site Configuration](./multi-site-configurations.md). The difference between the default `b2b` theme and the configurable `b2c` theme lies in the way the SCSS variables are initialized. The underlying `.scss` files are the same for the standard Intershop PWA. -While the `b2b` theme uses a [`variables.scss`](../../src/styles/themes/b2b/variables.scss) that directly assigns property values to the SCSS variables the `b2c` theme assigns CSS custom properties to the SCSS variables (see [`variables.scss`](../../src/styles/themes/b2c/variables.scss)). +While the `b2b` theme uses a [`variables.scss`](../../src/styles/themes/b2b/variables.scss) that directly assigns property values to the SCSS variables, the `b2c` theme assigns CSS custom properties to the SCSS variables (see [`variables.scss`](../../src/styles/themes/b2c/variables.scss)). `b2b - variables.scss` @@ -79,7 +79,7 @@ $CORPORATE-SHADOW: var(--corporate-shadow); $text-color-corporate: var(--text-color-corporate); ``` -These CSS custom properties are then assigned actual values in the [`properties.scss`](../../src/styles/themes/b2c/properties.scss). +In the [`properties.scss`](../../src/styles/themes/b2c/properties.scss) then actual values are assigned to these CSS custom properties. `b2c - properties.scss` @@ -100,74 +100,74 @@ These CSS custom properties are then assigned actual values in the [`properties. } ``` -And with the introduction of such CSS custom properties the values of these properties can be overridden at runtime, in our case through defining them as inline styles at the `html` tag. +With the introduction of such CSS custom properties the values of these properties can be overridden at runtime, in our case through defining them as inline styles at the `html` tag. ``` ``` -> **Note** +> **Note:** > SCSS color calculations do not work with CSS custom properties, they need real values. -> Therefore SCSS functions like `darken()` and `lighten()` do not work with values like `var(--corporate-primary)`. +> Therefore, SCSS functions like `darken()` and `lighten()` do not work with values like `var(--corporate-primary)`. > The standard Intershop PWA SCSS styling was adapted to no longer use such functions. -> Unfortunately the underlying Bootstrap styling still uses color calculations based on the SCSS variables `$primary` and `$secondary`. +> The underlying Bootstrap styling still uses color calculations based on the SCSS variables `$primary` and `$secondary`. > For that reason these variables have to be set with actual values so the default Bootstrap stylings can be generated. -> If necessary such Bootstrap generated styles with non fitting colors then need to be overridden in project styles (see [`button.scss`](../../src/styles/global/buttons.scss)). +> If necessary, such Bootstrap generated styles with non-fitting colors then need to be overridden in project styles (see [`button.scss`](../../src/styles/global/buttons.scss)). ### ICM Requirements -To configure the configurable `b2c` theme within the ICM backend a specific _Configuration_ CMS include (`include.configuration.pagelet2-Include`) with an assigned _Configuration_ CMS component (`component.configuration.pagelet2-Component`) is needed. +To configure the configurable `b2c` theme within the ICM back office, a specific _Configuration_ CMS include (`include.configuration.pagelet2-Include`) with an assigned _Configuration_ CMS component (`component.configuration.pagelet2-Component`) is needed. The sources are available with ICM 7.10.40.3 (in the `app_sf_pwa_cm` cartridge) but can be integrated in any earlier ICM version as well. -With the _Configuration_ component in place the theme configuration can be changed via CMS on organization, channel or application level. +With the _Configuration_ component in place, the theme configuration can be changed via CMS on organization, channel, or application level. ### Configuration Parameters The _Configuration_ component provides several configuration parameters for the PWA. Regarding CSS custom properties for a configurable theme it provides options to change the _Logo_, _Logo (mobile)_ and _CSS Properties_ in general. -Besides that additional _CSS Fonts_ can be integrated that can then be referenced in the _CSS Properties_. +Besides that, additional _CSS Fonts_ can be integrated that can then be referenced in the _CSS Properties_. -Independent from the used theme being configurable via CSS custom properties the _Configuration_ Component can be used to change the _Favicon_ or an additional _CSS File_ can be referenced or additional _CSS Styling_ can be added. +Independent of the used theme being configurable via CSS custom properties, the _Configuration_ Component can be used to change the _Favicon_, or an additional _CSS File_ can be referenced, or additional _CSS Styling_ can be added. -Also the used feature set can be changed with the _Features_ and _Additional Features_ parameters and additional custom _Configuration JSON_ can be provided for any specific customization needs. +Also the used feature set can be changed with the _Features_ and _Additional Features_ parameters, and additional custom _Configuration JSON_ can be provided for any specific customization needs. -| Parameters | Values | Description | -| ------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Logo | image reference | Brand Logo, can be a reference to an ICM managed image (uploaded and selected), an absolute URL (`https://`) or with the prefix `file://` pointing to an image in the PWA assets folder | -| Logo (mobile) | image reference | Brand Logo on mobile devices (see "Logo" description) | -| Favicon | image reference | Storefront Favicon (see "Logo" description) | -| CSS Properties | key-value pairs | CSS custom properties as multiline key (name without `--`) value pairs separated by a `:`, configurable properties can be found in `properties.scss`, example: `corporate-primary:#688dc3` | -| CSS Fonts | font URL | CSS Font references (multiline) (e.g. `https://fonts.googleapis.com/css2?family=Open+Sans`) | -| CSS File | URL | CSS style file reference, either ICM managed (uploaded and selected, could even be an unzipped `branding.zip`), an absolute URL (`https://`) or with the prefix `file://` pointing to a file in the PWA assets folder | -| CSS Styling | URL | CSS style definitions, added via a `style` tag to the HTML `head` | -| Features | comma separated list | Enabled PWA features, a comma separated features list, if empty, all default features of the theme will be enabled | -| Additional Features | comma separated list | Additional PWA features, a comma separated list of features added to the default feature set of the used theme | -| Configuration JSON | JSON | Additional Configuration data in JSON notation, will be available in the PWA state, accessible via `appFacade.extraSetting$(path)` | +| Parameters | Values | Description | +| ------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Logo | image reference | Brand logo, can be a reference to an ICM managed image (uploaded and selected), an absolute URL (`https://`), or with the prefix `file://` pointing to an image in the PWA assets folder | +| Logo (mobile) | image reference | Brand logo on mobile devices (see "Logo" description) | +| Favicon | image reference | Storefront Favicon (see "Logo" description) | +| CSS Properties | key-value pairs | CSS custom properties as multiline key (name without `--`) value pairs separated by a `:`, configurable properties can be found in `properties.scss`, example: `corporate-primary:#688dc3` | +| CSS Fonts | font URL | CSS font references (multiline) (e.g.; `https://fonts.googleapis.com/css2?family=Open+Sans`) | +| CSS File | URL | CSS style file reference, either ICM managed (uploaded and selected, could even be an unzipped `branding.zip`), an absolute URL (`https://`), or with the prefix `file://` pointing to a file in the PWA assets folder | +| CSS Styling | URL | CSS style definitions, added via a `style` tag to the HTML `head` | +| Features | comma separated list | Enabled PWA features, a comma separated features list, if empty, all default features of the theme will be enabled | +| Additional Features | comma separated list | Additional PWA features, a comma separated list of features added to the default feature set of the used theme | +| Configuration JSON | JSON | Additional Configuration data in JSON notation, will be available in the PWA state, accessible via `appFacade.extraSetting$(path)` | ### Configuration JSON The _Configuration_ CMS component provides a generic _Configuration JSON_ parameter that can be used to add any structured data in JSON format for the specific needs of the PWA customization in projects without the need to change/extend the CMS component model. -This could be used for example to provide additional tracking configuration information. -The data is available as JSON in the PWA state and can be easily accessed via a facade method. +This could be used, for example, to provide additional tracking configuration information. +The data is available as JSON in the PWA state and can easily be accessed via a facade method. ``` this.appFacade.extraSetting$('foo.bar') ``` -If additional document manipulation needs to be done for the customization the `setThemeConfiguration` method of the `configuration.service.ts` is the current reference. -Please be aware of the [DOM manipulations advices](./angular-component-development.md#dom-manipulations). +If additional document manipulation needs to be done for the customization, the `setThemeConfiguration` method of the `configuration.service.ts` is the current reference. +Please consider the [DOM manipulations advices](./angular-component-development.md#dom-manipulations). -If the _Configuration JSON_ does not suite the requirements for customizations good enough it is always possible to extend the Pagelet model of the _Configuration_ component in the ICM project sources. +If the _Configuration JSON_ does not suit the requirements for customizations well enough, it is always possible to extend the Pagelet model of the _Configuration_ component in the ICM project sources. ### Developing with the Configurable Theme > **Note** -> To use this feature the feature toggle `extraConfiguration` needs to be enabled. +> To use this feature, the feature toggle `extraConfiguration` needs to be enabled. For testing the configurable `b2c` theme, even without an ICM that provides the needed CMS include and pagelet, we provide mock data that can be used instead. -Add this line to your `environment.development.ts`. +Add this line to your `environment.development.ts`: ```javascript apiMockPaths: ['^cms/includes/include.configuration.pagelet2-Include'], @@ -175,15 +175,15 @@ apiMockPaths: ['^cms/includes/include.configuration.pagelet2-Include'], Also the `icmChannel` and the wanted `features` set should be set in the `environment.development.ts` if the ones from `environment.b2c.ts` are not what you want. -To start the PWA with the `b2c` theme run +To start the PWA with the `b2c` theme, run ```bash ng s -c=b2c,development ``` -To experiment with the CMS _Configuration_ component parameters you can edit the [`src\assets\mock-data\cms\includes\include.configuration.pagelet2-Include\get.json`](../../src/assets/mock-data/cms/includes/include.configuration.pagelet2-Include/get.json). +To experiment with the CMS _Configuration_ component parameters, you can edit the [`src\assets\mock-data\cms\includes\include.configuration.pagelet2-Include\get.json`](../../src/assets/mock-data/cms/includes/include.configuration.pagelet2-Include/get.json). -To develop a custom configurable theme one needs to copy the `b2c` theme as base of the custom theme instead of using the default `b2b` theme. +To develop a custom configurable theme, you need to copy the `b2c` theme as base of the custom theme instead of using the default `b2b` theme. # Further References