Skip to content

Commit

Permalink
docs: add Configurable Theme documentation (#1427)
Browse files Browse the repository at this point in the history 
* provide example CMS configuration mock data
* renamed 'Multiple Themes' guide to 'Themes' guide
* feature toggle documentation + migration note
  • Loading branch information
@shauke
shauke committed May 17, 2023
1 parent 9df825f commit 5fab401
Show file tree
Hide file tree
Showing 11 changed files with 303 additions and 66 deletions.
4 changes: 2 additions & 2 deletions docs/README.md
View file
Expand Up @@ -52,9 +52,9 @@ kb_sync_latest_only

- [Concept - Progressive Web App](./concepts/progressive-web-app.md)
- [Guide - Customizations](./guides/customizations.md)
- [Guide - Multiple Themes](./guides/multiple-themes.md)
- [Guide - Cookie Consent](./guides/cookie-consent.md)
- [Guide - Themes](./guides/themes.md)
- [Guide - Migration](./guides/migrations.md)
- [Guide - Cookie Consent](./guides/cookie-consent.md)
- [Concept - URL Rewriting](./concepts/url-rewriting.md)
- [Guide - Mocking REST API Calls](./guides/mocking-rest-calls.md)

Expand Down
49 changes: 25 additions & 24 deletions docs/concepts/configuration.md
View file
Expand Up @@ -151,30 +151,31 @@ Of course, the ICM server must supply appropriate REST resources to leverage fun

### Available Feature Toggles

| 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 |
| 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 |
| **B2C Features** | |
| 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`) |
| tacton | Tacton product configuration integration (additional configuration via `tacton` and `dataRetention` configuration options) |
| tracking | Google Tag Manager tracking (additional configuration via `gtmToken`) |
| 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 |
| **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 |
| **B2C Features** | |
| 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`) |
| tacton | Tacton product configuration integration (additional configuration via `tacton` and `dataRetention` configuration options) |
| tracking | Google Tag Manager tracking (additional configuration via `gtmToken`) |

### Configuring Features

Expand Down
2 changes: 1 addition & 1 deletion docs/concepts/pwa-building-blocks.md
View file
Expand Up @@ -22,7 +22,7 @@ For an architectural overview of how SSR works in the Intershop PWA, see [Deploy
Pre-rendering pages enables a number of features:

- **SEO compatibility**: Many web crawlers have no or only a limited capability to interpret JavaScript code. To make single-page applications like the Intershop PWA accessible to search engines, SSR is necessary. Pre-rendered pages can easily be crawled and indexed. For more information, see [Search Engine Optimization](search-engine-optimization.md).
- **Dynamic configurations**: Using SSR allows for safe, dynamic configuration of the Intershop PWA through various URL parameters (see [Configuration](configuration.md)). For example, server-side parameter configuration enables [multi-site](multi-site-handling.md) and [multi-theme](../guides/multiple-themes.md) handling.
- **Dynamic configurations**: Using SSR allows for safe, dynamic configuration of the Intershop PWA through various URL parameters (see [Configuration](configuration.md)). For example, server-side parameter configuration enables [multi-site](multi-site-handling.md) and [multi-theme](../guides/themes.md) handling.
- **Hybrid approach**: Via the _express.js_ server, URLs can be remapped to allow dynamic integration of specific _Responsive Starter Store_ pages. See [Hybrid Approach](hybrid-approach.md) for more information.

For an overview of the ever-growing list of third party integrations relating to SSR and deployment in general, see [Third-party Integrations](../README.md#third-party-integrations).
Expand Down
4 changes: 2 additions & 2 deletions docs/concepts/styling-behavior.md
View file
Expand Up @@ -17,7 +17,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 - Multiple Themes](../guides/multiple-themes.md)).
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.

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.
Expand Down Expand Up @@ -58,4 +58,4 @@ Please read [the additional documentation](../guides/optimizations.md#purgecss)

## References

[Guide - Multiple Themes](../guides/multiple-themes.md)
[Guide - Themes](../guides/themes.md)
4 changes: 2 additions & 2 deletions docs/guides/customizations.md
View file
Expand Up @@ -5,7 +5,7 @@ kb_everyone
kb_sync_latest_only
-->

# Customization Guide
# 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.
Expand Down Expand Up @@ -48,7 +48,7 @@ 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 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 - Themes](./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>`
Expand Down
10 changes: 8 additions & 2 deletions docs/guides/migrations.md
View file
Expand Up @@ -17,6 +17,12 @@ If the `addGlobalGuard` function is used for customizations make sure it now wor
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 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).
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.

## 3.3 to 4.0

The Intershop PWA now uses Node.js 18.15.0 LTS with the corresponding npm version 9.5.0 and the `"lockfileVersion": 3,`.
Expand Down Expand Up @@ -129,7 +135,7 @@ If you want to inject a token, use the methods `injectSingle` and `injectMultipl
There is a new linting rule `useTypeSafeInjectionTokenRule` that enforces the usage of these methods.
For more information, see the [Configuration Concept](../concepts/configuration.md#angular-cli-environments).

We introduced the product notifications feature as a new extension which is toggled with the feature toggle 'productNotifications' in the `environment.model.ts`.
We introduced the product notifications feature as a new extension which can be enabled with the feature toggle `productNotifications`.

## 3.2 to 3.3

Expand Down Expand Up @@ -382,7 +388,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](./multiple-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`.
Expand Down
2 changes: 1 addition & 1 deletion docs/guides/multi-site-configurations.md
View file
Expand Up @@ -47,7 +47,7 @@ All other properties are optional:
- **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 - Multiple Themes](./multiple-themes.md))
- **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:
Expand Down
29 changes: 0 additions & 29 deletions docs/guides/multiple-themes.md
View file

This file was deleted.

6 changes: 3 additions & 3 deletions docs/guides/ssr-startup.md
View file
Expand Up @@ -12,7 +12,7 @@ kb_sync_latest_only
To **simply** build the Intershop PWA in server-side rendering mode, you can use the _package.json_ script `npm run build`, which builds the Intershop PWA with the `production` configuration of the `angular.json` with the default theme.
Afterwards you can start the application with `npm run serve` (or do both by using `npm run start`).

To build a specific theme (see [Guide - Multiple Themes][multiple-themes]), you can build (and run) via `npm` using the `--configuration=` argument.
To build a specific theme (see [Guide - Themes][themes]), you can build (and run) via `npm` using the `--configuration=` argument.
All `configuration` options must be in the format `--configuration=<theme>,(production|development)`.

## Building Multiple Themes
Expand Down Expand Up @@ -115,7 +115,7 @@ This feature can also be used to benchmark the SSR render performance locally by
- [Concept - Deploy URL][concept-deploy-url]
- [Concept - Hybrid Approach][concept-hybrid]
- [Concept - Logging](../concepts/logging.md)
- [Guide - Multiple Themes][multiple-themes]
- [Guide - Themes][themes]
- [Guide - Client-Side Error Monitoring with Sentry](./sentry-error-monitoring.md)
- [Guide - Google Tag Manager](./google-tag-manager.md)
- [Guide - Monitoring with Prometheus](./prometheus-monitoring.md)
Expand All @@ -126,5 +126,5 @@ This feature can also be used to benchmark the SSR render performance locally by

[concept-hybrid]: ../concepts/hybrid-approach.md
[concept-deploy-url]: ../concepts/deploy-url.md
[multiple-themes]: ./multiple-themes.md
[themes]: ./themes.md
[pm2]: https://pm2.keymetrics.io

0 comments on commit 5fab401

Please sign in to comment.