SAP Spartacus Multi-Site Configuration

official link

Each site defined in the CMS has its own context, which includes the basic site ID, language attributes, and currency attributes. The context also defines how these attributes are persisted in the URL.

Static Multi-Site Configuration

You can configure your application by defining context properties such as base site, language, and currency. When you append the values of these attributes to the storefront URL, the storefront will be configured based on these values.

For example, when accessing https://localhost:4200/electronics-spa/en/USD/, the application loads the electronics-spa base site, sets the site language to English (en), and sets the currency to (USD).

The context attribute also sets default values for the language and currency drop-down lists, and you can use them to dynamically change the context of the storefront.

Site attributes: theme, channel and language

content catalog：

Products displayed by default:

The configuration is now placed in C:\Code\SPA\spartacus\projects\storefrontapp\src\app\spartacus\spartacus-b2c-configuration.module.ts:

Context Properties

The context properties are in app.module.ts.

The baseSite, language, and currency attributes are arrays with the first element in the array as the default value.

The urlParameters attribute takes the values of other context attributes to create the context structure attached to the storefront URL.

For example, if your storefront URL is https://localhost:4200, it will become https://localhost:4200/electronics-spa/en/USD/ with the following context configuration:

context: {
    baseSite: [
      'electronics-spa', //Selected by default because it is the first element in the list
      'electronics',
    ],
    language: [
      'en'
    ],
    currency: [
      'USD'
    ],
    urlParameters: ['baseSite', 'language', 'currency']
  },
 ...

Enabling Context in the Storefront URL

By default, the context does not appear in the Spartacus storefront URL.

You may want to display the context in the storefront URL as a way to optimize SEO, or to maintain the compatibility of the URL with the previous storefront. For example, you might want a search robot to categorize different versions of storefronts based on the language and currency in the URL. Or, you might be migrating to Spartacus from another storefront that includes context in the storefront URL, and you want to maintain the page ranking you previously established.

To include the context in the URL, add the urlParameters attribute to the context attribute in app.modules.ts. Below is an example:

context: {
    baseSite: ['electronics-spa'],
    urlParameters: ['baseSite', 'language', 'currency']
  },

Automatic Multi-Site Configuration

This feature was introduced in version 1.3 of the Spartacus library.

Each site defined in the CMS has its own context, which includes the basic site ID, language attributes, and currency attributes. The context also defines how these attributes are persisted in the URL. You can allow Spartacus to automatically determine the context based on the site URL pattern defined in the CMS. You can enable this automatic context configuration by simply not defining the context.baseSite property in app.module.ts.

Before the application is initialized, Spartacus obtains the base station list from the backend, compares the current URL with the URL pattern of the site defined in the CMS, and then identifies the current base station and its language, currency, and URL encoding attributes.

Mitigating the Initial Back End Call

The initial call to the back end of the basic site may be slow, which can affect the user experience. To solve this problem, you can choose to use server-side rendering (SSR) or progressive web application (PWA) technology to cache the context.

Caching the Site Context with Server-Side Rendering

The site can be identified during server-side rendering, and the context can be transferred to the browser using the Angular TransferState mechanism. In order to avoid calling the basic site on the server side every time a page is requested, a reverse proxy can be used to cache the page.

To allow the site to be recognized on the server side, you need to provide Spartacus with the current request URL. You can do this by using ngExpressEngine's Spartacus decorator, which provides the SERVER_REQUEST_URL injection token behind the scenes. You can configure it in main.server.ts as follows:

import { ngExpressEngine as engine } from '@nguniversal/express-engine';
import { NgExpressEngineDecorator } from '@spartacus/core';

export const ngExpressEngine = NgExpressEngineDecorator.get(engine);

Caching the Back End Response with Base Sites in PWA

When using PWA, the Angular Service Worker can cache and provide the backend response of the basic site by adding configuration to the dataGroups array in the Service Worker configuration. The following is an example from ngsw-config.json:

{
  // ...
  "dataGroups": [
    // ...
    {
      "name": "basesites",
      "urls": [
        "*/rest/v2/basesites?fields=baseSites\\(uid,defaultLanguage\\(isocode\\),urlEncodingAttributes,urlPatterns,stores\\(currencies\\(isocode\\),defaultCurrency\\(isocode\\),languages\\(isocode\\),defaultLanguage\\(isocode\\)\\)*"
      ],
      "cacheConfig": {
        "maxSize": 1,
        "maxAge": "1d", // Set to 1 day. Customize this value according to your needs.
        "strategy": "performance"
      }
    }
  ]
}

Base Sites and Storefronts

When the base site is encoded in the URL parameter, Spartacus refers to the baseSite parameter, and CMS refers to this parameter as storefront. You should continue to use the storefront parameter name in the CMS because Spartacus implicitly maps the storefront to baseSite. Other parameters, such as language and currency, are not affected.

As shown in the figure below: the parameter "storefront" is used in backoffice CMS:

And Spartacus uses baseSite:

Writing URL Patterns in Java

Due to historical reasons, the regular expressions with URL patterns defined in the CMS are written in Java. However, these regular expressions are calculated using JavaScript on the front end. You should continue to use Java regex in the CMS, they will be implicitly converted to JavaScript in Spartacus. For example, to be case-insensitive, modifiers such as (?i) are mapped to /i.

Note: Although the existing mapping between Java regex and JavaScript should be sufficient for the most common situations, not all Java regex features are available in JavaScript, so verifying that your URL pattern does not use Java regex features is not available in JavaScript. Important JavaScript. Otherwise, any basic site with an incorrect URL pattern will not be recognized by Spartacus.

Disabling a Base Site

Regardless of the options defined in the CMS, such as active, activeFrom, or activeTo, the backend endpoint returns a list of all basic sites, without any information about whether the site is active. To disable a basic site, you must delete the URL pattern of the basic site.

As an alternative low-level solution, you can set restrictions on back-end database calls to filter only active sites.

More original articles by Jerry, all in: "Wang Zixi":