FirstSpirit Connect (Headless): For SAP Commerce Cloud

1. Einleitung

Die Erwartungen von Kundinnen und Kunden an moderne E-Commerce-Shopsysteme werden immer vielfältiger: Neben der reinen Darstellung von Produktkatalogen müssen sie einzigartige und personalisierte Shopping-Erlebnisse vermitteln. Kundinnen und Kunden wollen dabei über alle von ihnen genutzten Kanäle und Endgeräte angesprochen werden. Die Anzahl eingesetzter Touchpoints ist daher beliebig groß.

Die FirstSpirit Connect (Headless): For SAP Commerce Cloud (Headless) for SAP Commerce Cloud-Integration verknüpft die Digital Experience Platform FirstSpirit mit dem E-Commerce-Shopsystem SAP Commerce Cloud in Verbindung mit der Spartacus Storefront. Sie schafft dadurch ein leistungsstarkes Gesamtsystem, das die funktionalen Vorteile dieser Systeme kombiniert und die Bereitstellung moderner und personalisierter Inhalte ermöglicht.

Redakteurinnen und Redakteure erhalten vollständigen Zugriff auf den Produktkatalog der SAP Commerce Cloud und können diesen durch redaktionelle Inhalte, wie beispielsweise Shoppable-Videos, ergänzen. Die Pflege der Inhalte erfolgt dabei mithilfe einer intuitiv zu bedienenden WYSIWYG-Oberfläche, die FirstSpirit bereitstellt. Darüber hinaus erhalten sie die Möglichkeit, neue Inhalte zu erstellen. Die Inhalte können auf Seiten unterschiedlichsten Typs eingebunden werden - sowohl auf der Homepage als auch auf Landingpages sowie Produkt- und Kategorieseiten. Kenntnisse über das E-Commerce-Shopsystem sind dafür nicht erforderlich. Die WYSIWYG-Oberfläche stellt alle benötigen Funktionalitäten zur Verfügung.

Die Spartacus Storefront übernimmt weiterhin die Auslieferung der Inhalte. Diese bezieht sie jedoch nicht mehr ausschließlich aus der SAP Commerce Cloud, sondern zusätzlich aus dem FirstSpirit CaaS (Content as a Service). Der CaaS entspricht einem zentralen Content Repository und persistiert die in FirstSpirit gepflegten Inhalte.
Das Gesamtsystem aus FirstSpirit, Spartacus und der SAP Commerce Cloud besitzt damit eine Architektur, in der das redaktionelle Backend FirstSpirits klar von der Spartacus Storefront getrennt ist.

Wird im restlichen Dokument die Formulierung "Commerce Cloud" verwendet, ist damit immer ausschließlich die SAP Commerce Cloud gemeint.
Dies gilt auch für die Kurzform "FirstSpirit Connect (Headless): For SAP Commerce Cloud", mit der innerhalb dieser Dokumentation grundsätzlich die FirstSpirit Connect (Headless): For SAP Commerce Cloud (Headless) for SAP Commerce Cloud-Integration gemeint ist.

Des Weiteren ist die gesamte Dokumentation auf die Anbindung der Spartacus Storefront sowie des B2C Demo Shops ausgerichtet. Die Erwähnung der Storefront bezieht sich somit ausschließlich auf die Spartacus Storefront.

Ein Bestandteil der Auslieferung des FirstSpirit Connect (Headless): For SAP Commerce Cloud (Headless) for SAP Commerce Cloud-Moduls ist das Referenzprojekt FirstSpirit Connect Reference Project. Die vorliegende Dokumentation orientiert sich durchgängig an diesem Referenzprojekt und erläutert die mit dem Modul bereitgestellten Funktionalitäten anhand gängiger Anwendungsfälle.

1.1. Funktionsumfang

FirstSpirit Connect (Headless): For SAP Commerce Cloud stellt die folgenden Möglichkeiten zur Verfügung:

Zugriff auf Produkt- und Kategorieinformationen
Erzeugung neuer redaktioneller Inhalte
gleichzeitige Darstellung von Shopelementen und redaktionellen Inhalten in der FirstSpirit-Vorschau
Ausspielung von Inhalten an beliebige Touchpoints

Die dafür notwendigen Funktionalitäten werden mit der Installation und Konfiguration des Moduls innerhalb des WYSIWYG-Clients bereitgestellt.

Die Pflege der Inhalte findet über die gewohnten FirstSpirit-Mittel statt. Mit FirstSpirit vertraute Personen benötigen daher keine darüber hinausgehenden Kenntnisse - insbesondere keine über das E-Commerce-Shopsystem. Die Inhalte werden der Storefront mithilfe des CaaS verfügbar gemacht und in Kombination mit den Inhalten aus der Commerce Cloud von der Storefront ausgeliefert.

Innerhalb des neu geschaffenen Gesamtsystems ergibt sich somit keinerlei Unterschied für die Auslieferung redaktioneller Inhalte. Sie erfolgt weiterhin durch die Storefront. Auch eine Wartung FirstSpirits beeinflusst weder die Storefront noch die Commerce Cloud.

Abbildung 1. Datenfluss

1.2. Architektur

Die SAP-Shop-Architektur setzt sich standardmäßig aus der Commerce Cloud und der Spartacus Storefront zusammen. Während die Commerce Cloud in diesem System sämtliche Shopfunktionalitäten bereitstellt und alle Shopinhalte persistiert, dient die Spartacus Storefront der Auslieferung dieser Inhalte.

Mit der FirstSpirit Connect (Headless): For SAP Commerce Cloud (Headless) for SAP Commerce Cloud-Lösung integrieren sich FirstSpirit und der CaaS in diese Architektur und erweitern die Shopfunktionalitäten der Commerce Cloud. Die Integration schafft dadurch ein Gesamtsystem, das die funktionalen Stärken der einzelnen Systeme kombiniert. Innerhalb dieses Gesamtsystems repräsentieren FirstSpirit und die Commerce Cloud das Backend, während der CaaS die Middleware und die Storefront das Frontend bilden.

Die folgende Grafik zeigt die Highlevel-Architektur dieses Gesamtsystems:

Abbildung 2. Highlevel-Architektur

Innerhalb des neu geschaffenen Gesamtsystems übernimmt die Storefront weiterhin die Auslieferung der Inhalte, die sie standardmäßig aus der Commerce Cloud bezieht. Zusätzlich fragt sie jedoch die Inhalte der jeweiligen CaaS-Instanz ab und verknüpft sie mit denen der Commerce Cloud. Zu diesem Zweck wird sie durch die fs-spartacus-bridge-Bibliothek erweitert.

Im Gegensatz zur Auslieferung der Inhalte verlagert sich deren Erstellung und Pflege von der Commerce Cloud nach FirstSpirit. FirstSpirit stellt dafür mit dem ContentCreator einen intuitiv zu bedienenden WYSIWYG-Client zur Verfügung. In diesen ist der sogenannte Omnichannel Manager (OCM) eingebunden, der die Darstellung externer Inhalte im ContentCreator erlaubt (vgl. Abbildung Lowlevel-Architektur).

Durch die Einbettung der Storefront in den Omnichannel Manager wird eine kombinierte Vorschau der Inhalte bereitgestellt, die in diesem Fall aus dem Preview CaaS und der Commerce Cloud stammen. Die Redakteurinnen und Redakteure erhalten auf diesem Weg die Möglichkeit, bereits existierende Shopseiten im ContentCreator zu bearbeiten. Dafür stehen ihnen eine Vielzahl unterschiedlicher Komponenten, wie z.B. Shoppable-Videos, zur Verfügung.

Die Bereitstellung der Produkt- und Kategorieinformationen erfolgt über einen Report im ContentCreator. Dieser greift dafür über die CMS WebServices-Schnittstelle der Commerce Cloud auf den Product Catalog zu und ermittelt so die notwendigen Daten.

Die Übertragung der erstellten bzw. veränderten Inhalte in den Online CaaS erfolgt mit jeder Freigabe. Der CaaS persistiert die Inhalte im JSON-Format in Form von Inhaltsfragmenten und macht sie für die Storefront verfügbar, die sie zusammen mit den Commerce Cloud-Inhalten in den Shop integriert. Für die Darstellung der aus dem Referenzprojekt stammenden Inhalte muss die Storefront neben der Bridge die fs-spartacus-view-components-Bibliothek einbinden.

Das Gesamtsystem aus FirstSpirit, Spartacus und der Commerce Cloud besitzt damit eine Architektur, in der das redaktionelle Backend FirstSpirits klar von der Storefront getrennt ist. Eine Wartung FirstSpirits beeinflusst weder die Storefront noch die Commerce Cloud.

Abbildung 3. Lowlevel-Architektur

1.3. Konzept

Die FirstSpirit Connect (Headless): For SAP Commerce Cloud-Integration bietet die Möglichkeit, redaktionelle Inhalte für die Storefront FirstSpirit-seitig zu pflegen und diese anschließend in den CaaS zu übertragen. Aus diesem werden sie von der Spartacus Storefront abgefragt und zusammen mit den Produktinformationen aus der Commerce Cloud ausgeliefert. Dafür muss die Verarbeitung von Inhalten in beiden Systemen aufeinander abgestimmt und zueinander kompatibel sein. Die nachfolgenden Unterkapitel beschreiben das zugrunde liegende Konzept, mit dem diese Kompatibilität erreicht wird.

1.3.1. Seiten

Ähnlich wie in FirstSpirit basieren Seiten in der Commerce Cloud auf einer Struktur unterschiedlicher Komponenten. Um redaktionelle Inhalte zwischen den beiden Systemen austauschen zu können, müssen diese Komponenten aufeinander abgestimmt sein.

Innerhalb des in der Auslieferung enthaltenen Referenzprojekts FirstSpirit Connect Reference Project werden die Slots durch die Inhaltsbereiche einer Seitenvorlage repräsentiert. Ihnen können Absätze hinzugefügt werden, die jeweils einer Komponente entsprechen (vgl. Abbildung Page Rendering).

Mit FirstSpirit lassen sich somit Komponenten generieren, die über Slots in einer Seite dargestellt werden.

Abbildung 4. Page Rendering

1.3.2. Seitentypen

Wie im vorhergehenden Kapitel beschrieben, erfolgt die Pflege redaktioneller Inhalte sowohl in FirstSpirit als auch in der Commerce Cloud auf Basis einer Seite. Die Integration unterscheidet dabei zwischen Shop Driven Pages und den FirstSpirit Driven Pages.

Shop Driven Pages: Im Gegensatz zu den FirstSpirit Driven Pages besitzen die Shop Driven Pages sowohl eine Seite in FirstSpirit als auch in der Commerce Cloud. Sie entsprechen beispielsweise der Homepage oder den Produkt- und Kategorieseiten. Die FirstSpirit-seitig gepflegten Inhalte überschreiben oder ergänzen die bestehenden Inhalte in den vordefinierten Slots dieser Seiten.
FirstSpirit Driven Pages: FirstSpirit Driven Pages existieren ausschließlich in FirstSpirit und besitzen keine zugehörige Seite in der Commerce Cloud. Sie dienen der Erzeugung von Inhalts- oder Kampagnenseiten, die nicht zwingend im Standardumfang des Shops enthalten sind. FirstSpirit Driven Pages können entweder das Layout einer Shop Driven Page oder ein eigenes Layout verwenden, das in der Storefront definiert ist.

Die Speicherung der Inhalte ist für beide Seitentypen identisch: Sie werden an den CaaS übertragen und in diesem persistiert. Bei der Abfrage einer Seite prüft die Storefront, ob zu einer gegebenen ID sowohl im CaaS als auch in der Commerce Cloud eine Seite existiert. Ist dies der Fall, handelt es sich um eine Shop Driven Page. Enthält andernfalls nur der CaaS eine Seite für die entsprechende ID, handelt es sich um eine FirstSpirit Driven Page. Liefert keines der beiden Systeme eine Seite zurück, zeigt die Storefront eine Fehlerseite an.

1.3.3. Vorschau

Die mit dem FirstSpirit Connect (Headless): For SAP Commerce Cloud-Modul realisierte Integration sieht FirstSpirit-seitig lediglich die Erzeugung und Pflege der redaktionellen Inhalte sowie ihre Publizierung in Form von JSON-Dokumenten vor. Die Storefront bestimmt jedoch weiterhin das Rahmenwerk einer Seite, deren Slots die generierten Komponenten einbinden.

Um eine Seite in der Vorschau darzustellen, ermittelt FirstSpirit ihre aktuelle Ansicht in der Spartacus Storefront. Diese fragt ihrerseits die redaktionellen Inhalte aus dem Preview CaaS ab und ersetzt die entsprechenden Komponenten. FirstSpirit stellt anschließend das Resultat mithilfe des Omnichannel Managers im ContentCreator dar.

2. Commerce Cloud - Installation und Konfiguration

FirstSpirit dient der Erstellung und Pflege redaktioneller Daten, die in den CaaS übertragen und von diesem persistiert werden. Um die Daten in den Shop zu integrieren, benötigt die Storefront eine Zugriffsmöglichkeit auf den CaaS. Diese wird durch verschiedene Bibliotheken bereitgestellt, die eine Spartacus-seitige Einbindung und Konfiguration erfordern.

Die nachfolgenden Kapitel beschreiben alle notwendigen Schritte für die Installation und die Konfiguration der Bibliotheken sowie für die erforderlichen Commerce Cloud-seitigen Anpassungen.

Die FirstSpirit Connect (Headless): For SAP Commerce Cloud-Integration setzt die Verwendung der Commerce Cloud (in der Version 19.05 oder höher) und der Spartacus Storefront in der Version 4.x voraus.

2.1. OAuth-Konfiguration

Das FirstSpirit Connect (Headless): For SAP Commerce Cloud-Modul benötigt für die Abfrage der Informationen aus der Commerce Cloud eine OAuth-Authentifizierung. Daher ist die Konfiguration eines OAuth-Clients innerhalb der Commerce Cloud erforderlich.

Für das Anlegen eines solchen OAuth-Clients stehen zwei Möglichkeiten zur Verfügung:

manuell im Backoffice unter System OAuth OAuth Clients
automatisch per Import des nachfolgenden ImpExes
(in der Hybris Admin Console unter Console ImpEx Import)

ImpEx

INSERT_UPDATE OAuthClientDetails;clientId[unique=true] ;resourceIds;scope ;authorizedGrantTypes ;authorities ;clientSecret;registeredRedirectUri
;firstspirit ;hybris ;extended,previewwebservices;authorization_code,refresh_token,password,client_credentials;ROLE_TRUSTED_CLIENT ;secret; ;

2.2. Einbindung und Konfiguration der Bibliotheken

In dem durch die FirstSpirit Connect (Headless): For SAP Commerce Cloud-Integration realisierten System übernimmt die Storefront die Auslieferung der Inhalte. Diese bezieht sie sowohl aus der Commerce Cloud als auch aus der jeweiligen CaaS-Instanz und verknüpft sie miteinander. Zu diesem Zweck muss sie durch die fs-spartacus-bridge-Bibliothek erweitert werden. Für die Darstellung und Bearbeitung der aus dem Referenzprojekt stammenden Inhalte ist darüber hinaus die Einbindung der Bibliotheken fs-spartacus-view-components und fs-tpp-api erforderlich. Des Weiteren wird die fs-spartacus-common-Bibliothek benötigt. Sie enthält Klassen, die sowohl die Bridge als auch die Angular UI-Komponenten nutzen.

Die Bereitstellung der Bibliotheken erfolgt in Form von npm-Paketen, die sich über die folgenden Befehle installieren lassen. Für die fs-tpp-api-Bibliothek ist kein Befehl angegeben, da ihre Installation automatisch erfolgt.

Installationsbefehle

npm install fs-spartacus-bridge
npm install fs-spartacus-view-components
npm install fs-spartacus-common

Für die Darstellung der Editierfunktionalitäten im ContentCreator wird zusätzliches CSS benötigt. Dieses ist in der Bridge enthalten und muss im Anschluss an die Installation in die styles.scss-Datei der Storefront importiert werden.

Einbindung der CSS-Datei

@import '~fs-spartacus-bridge/styles/index';

Des Weiteren sind im letzten Schritt der Installation die Angular UI-Komponenten und die Bridge im imports-Array des @NgModules im Hauptmodul der Spartacus-Applikation (app.module.ts) einzubinden. Im Gegensatz zu den UI-Komponenten setzt die Bridge dabei pro BaseSite unterschiedliche Informationen voraus. Neben einer optionalen Fallback-Sprache und verschiedenen CaaS-Angaben erwartet sie eine Definition der Shop und FirstSpirit Driven Pages, deren Bearbeitung im ContentCreator möglich sein soll.

Die Festlegung einer Fallback-Sprache bietet die Möglichkeit, auf Inhalte in einer anderen Sprache zurückzugreifen, wenn für die angezeigte Sprache keine Inhalte existieren. So sind Inhalte schnell und einfach präsentiertbar, ohne vollständig übersetzt zu sein. Die Nutzung dieser Funktion erfordert die Angabe einer Fallback-Sprache im CaaS locale-Format (zum Beispiel en_GB).

Um die in der Bridge-Konfiguration festgelegte Fallback-Sprache nutzen zu können, muss die verwendete FirstSpirit-Absatzvorlage die Eingabekomponente st_languageFallbackEnabled und die ihr zugehörige Regel beinhalten. Andernfalls ist die Aktivierung der Fallback-Sprache nicht möglich.

Zu den CaaS-Angaben zählen unter anderem die Tenant ID und die Project ID: Die Tenant ID ist eine von der Crownpeak Technology GmbH festgelegte eindeutige Kennung, die im Konfigurationsdialog des CaaS-Services definiert ist. Die Project ID entspricht der UUID des verwendeten FirstSpirit-Projekts. Sie ist ein Bestandteil der CaaS-URL und folgt in dieser auf die Tenant ID. Die CaaS-URL ist ihrerseits im Konfigurationsdialog der CaaS-Projekt-Komponente sichtbar. Weitere Informationen zum Schema der CaaS-URL sind in der CaaS Connect Moduldokumentation enthalten.

Die für die Konfiguration notwendigen CaaS-Informationen stellt die Crownpeak Technology GmbH mit der Integration zur Verfügung. Bei Fragen bietet der Technical Support qualifizierte Unterstützung an.

Für die definierten Pages sind zusätzlich die bearbeitbaren Slots sowie optional eine Merge-Strategie zu konfigurieren. Mit der Merge-Strategie lässt sich festlegen, wie die Inhalte, die sowohl Commerce Cloud- als auch FirstSpirit-seitig für einen Slot gepflegt sind, miteinander verknüpft werden. Standardmäßig ersetzen die FirstSpirit-Inhalte die in einem Slot enthaltenen Commerce Cloud-Inhalte.

Der folgende Code-Block zeigt die für das Referenzprojekt notwendige Konfiguration. Sie definiert verschiedene Shop und FirstSpirit Driven Pages, für deren Bearbeitung die Konfiguration zwingend erforderlich ist.

Erweiterung des import-Arrays

import { APPEND, FsSpartacusBridgeModule } from 'fs-spartacus-bridge';
import { FsSpartacusViewComponentsModule } from 'fs-spartacus-view-components';
import { FirstSpiritManagedPage, fromSlotList } from 'fs-spartacus-common';
import { NgModule } from '@angular/core';

@NgModule({
   imports: [
      FsSpartacusViewComponentsModule,
      FsSpartacusBridgeModule.withConfig({
         bridge: {
            [BaseSite uid]: {
               fallbackLanguage: 'en_GB',
               caas: {
                  baseUrl: 'CAAS BASE URL',
                  project: 'PROJECT ID',
                  apiKey: 'CAAS API KEY',
                  apiKeyPreview: 'PREVIEW CAAS API KEY',
                  tenantId: 'TENANT ID'
               },
               firstSpiritManagedPages: [
                  FirstSpiritManagedPage.enhanceSapPages('CartPageTemplate',
                     fromSlotList('BottomHeaderSlot', 'PreFooterSlot')),
                  FirstSpiritManagedPage.enhanceSapPages('ProductDetailsPageTemplate',
                     fromSlotList('BottomHeaderSlot', 'PreFooterSlot')),
                  FirstSpiritManagedPage.enhanceSapPages('CategoryPageTemplate',
                     fromSlotList('BottomHeaderSlot', 'PreFooterSlot')),
                  FirstSpiritManagedPage.enhanceSapPages('ProductListPageTemplate',
                     fromSlotList('BottomHeaderSlot', 'PreFooterSlot'))
                  FirstSpiritManagedPage.enhanceSapPages('ProductListPageTemplate',
                     fromSlotList('BottomHeaderSlot', 'PreFooterSlot')),
                  FirstSpiritManagedPage.integrateFsDrivenPagesIntoSapSkeleton(
                     'DummyCampaignPageWithHeader',
                     PageType.CONTENT_PAGE,
                     'campaign_page_with_header',
                     fromSlotList(
                        'BottomHeaderSlot',
                        'Section1', 'Section2C', 'Section3',
                        'PreFooterSlot'
                     )
                  ),
                  FirstSpiritManagedPage.integrateFsDrivenPages(
                     'campaign_page_without_header',
                     fromSlotList(
                        'BottomHeaderSlot',
                        'NarrowContentSection', 'WideContentSection', 'BottomNarrowSection',
                        'PreFooterSlot'
                     )
                  )
               ]
            }
         }
      })
   ]
})
export class AppModule { }

2.2.1. Anbindung unterschiedlicher BaseSites

Für die Umsetzung unterschiedlicher Länder- oder Shopseiten bietet Spartacus die sogenannte Multi-Site Configuration an. Sie dient der Anbindung unterschiedlicher BaseSites, die jeweils einer solchen Seite entsprechen.

Die FirstSpirit Connect (Headless): For SAP Commerce Cloud (Headless) for SAP Commerce Cloud-Integration erlaubt die Anbindung beliebig vieler BaseSites. Dafür sind der Bridge-Konfiguration lediglich die unterschiedlichen BaseSite-UIDs hinzuzufügen. Die Bridge erwartet darüber hinaus pro BaseSite eine optionale Fallback-Sprache, verschiedene CaaS-Informationen und die Definition der Shop und FirstSpirit Driven Pages, deren Bearbeitung im ContentCreator möglich sein soll.

Das folgende Code-Beispiel zeigt eine solche Konfiguration in gekürzter Form:

Konfiguration unterschiedlicher BaseSites

import { APPEND, FsSpartacusBridgeModule } from 'fs-spartacus-bridge';
import { FsSpartacusViewComponentsModule } from 'fs-spartacus-view-components';
import { FirstSpiritManagedPage, fromSlotList } from 'fs-spartacus-common';
import { NgModule } from '@angular/core';

@NgModule({
   imports: [
      FsSpartacusViewComponentsModule,
      FsSpartacusBridgeModule.withConfig({
         bridge: {
            [BaseSite uid]: {
               fallbackLanguage: 'en_GB',
               caas: {
                  baseUrl: 'CAAS BASE URL',
                  project: 'PROJECT ID',
                  apiKey: 'CAAS API KEY',
                  apiKeyPreview: 'PREVIEW CAAS API KEY',
                  tenantId: 'TENANT ID'
               },
               firstSpiritManagedPages: [
                  FirstSpiritManagedPage.enhanceSapPages('CartPageTemplate',
                     fromSlotList('BottomHeaderSlot', 'PreFooterSlot')),
                  ...
               ]
            },
            [BaseSite uid]: {
               fallbackLanguage: 'en_US',
               caas: {
                  ...
               },
               firstSpiritManagedPages: [
                  ...
               ]
            },
                        [BaseSite uid]: {
               fallbackLanguage: 'de_DE',
               caas: {
                  ...
               },
               firstSpiritManagedPages: [
                  ...
               ]
            }
         }
      })
   ]
})
export class AppModule { }

2.2.2. Definition der Shop und FirstSpirit Driven Pages

Für die Pflege redaktioneller Inhalte unterscheidet die Integration zwischen Shop und FirstSpirit Driven Pages. Sie variieren dadurch, dass die Shop Driven Pages sowohl in FirstSpirit als auch in der Commerce Cloud eine Seite besitzen. Im Gegensatz dazu existieren die FirstSpirit Driven Pages ausschließlich in FirstSpirit.

Um die Bearbeitung der Seiten im ContentCreator zu ermöglichen, sind sie in der Bridge zu konfigurieren. Die Konfiguration unterscheidet sich dabei in Abhängigkeit des Seitentyps.

Shop Driven Pages

Im Fall der Shop Driven Pages sind in der Konfiguration der Name des Commerce Cloud Templates und die bearbeitbaren Slots sowie optional eine Merge-Strategie anzugeben. Das Mapping zwischen dem definierten Commerce Cloud Template und der FirstSpirit-Vorlage erfolgt in den Projekteinstellungen.

Beispielkonfiguration - Shop Driven Page

firstSpiritManagedPages: [
   FirstSpiritManagedPage.enhanceSapPages('StoreFinderPageTemplate', [
      { name: 'BottomHeaderSlot' },
      { name: 'MiddleContent', mergeStrategy: APPEND }
   ])
]

FirstSpirit Driven Pages

FirstSpirit Driven Pages existieren ausschließlich in FirstSpirit und besitzen keine zugehörige Seite in der Commerce Cloud. Sie können entweder das Layout einer Shop Driven Page oder ein eigenes Layout verwenden, das in der Storefront definiert ist. Diese Unterscheidung ist auch in der Konfiguration zu berücksichtigen: Im ersten Fall sind die UID der zu verwendenden Commerce Cloud-Seite, deren PageType sowie die FirstSpirit-Vorlage und die bearbeitbaren Slots anzugeben. Im zweiten Fall ist lediglich die Angabe der FirstSpirit-Vorlage und der Slots erforderlich. In beiden Fällen erfolgt das Styling der FirstSpirit Driven Pages in Angular beispielsweise in der styles.scss-Datei der Storefront.

Beispielkonfiguration - FirstSpirit Driven Pages

firstSpiritManagedPages: [

   // Fall 1: Die FirstSpirit Driven Page verwendet das Layout einer Shop Driven Page.
   FirstSpiritManagedPage.integrateFsDrivenPagesIntoSapSkeleton(
      'DummyCampaignPageWithHeader',
      PageType.CONTENT_PAGE,
      'campaign_page_with_header',
      fromSlotList('BottomHeaderSlot', 'Section1', 'Section2C', 'Section3', 'PreFooterSlot')),

   // Fall 2: Die FirstSpirit Driven Page verwendet ein in der Storefront definiertes Layout.
   FirstSpiritManagedPage.integrateFsDrivenPages(
      'campaign_page_without_header',
      fromSlotList('BottomHeaderSlot', 'NarrowContentSection', 'WideContentSection',
         'BottomNarrowSection', 'PreFooterSlot')
   )
]

Die im ersten Fall anzugebene Commerce Cloud-Seite muss einer Dummy-Seite entsprechen, die bis auf das gewünschte Layout leer ist. Das heißt, dass sie das Layout definiert und beispielsweise einen allgemeinen Header und Footer besitzt, ansonsten jedoch keine Inhalte enthält. Eine solche Seite ist für jedes Layout erforderlich, dass von FirstSpirit Driven Pages verwendbar sein soll. Der SAP Blog beschreibt die Erzeugung neuer Seiten in Spartacus.

Im zweiten Fall ist der FirstSpirit Driven Page keine Commerce Cloud-Seite und somit auch kein Layout einer solchen Seite zugeordnet. Die Storefront weiß daher nicht, welche Slots existieren und in welcher Reihenfolge diese auszugeben sind. Um ihr diese Informationen mitzuteilen, ist die layoutConfig-Konfiguration folgendermaßen zu erweitern. Der dargestellte Code-Ausschnitt entspricht der Konfiguration für das Referenzprojekt.

Spartacus-seitig existieren verschiedene allgemeine Slots, deren Ausgabe ohne zusätzliche Konfiguration erfolgt. Ihre Angabe ist daher lediglich in der Konfiguration der Bridge, jedoch nicht in der layoutConfig-Konfiguration erforderlich. Ein Beispiel für diese Art von Slots ist der BottomHeaderSlot aus dem vorhergehenden Code-Ausschnitt.

Erweiterung der layoutConfig-Konfiguration

import {layoutConfig, LayoutConfig} from '@spartacus/storefront';

const config: LayoutConfig = JSON.parse(JSON.stringify(layoutConfig));
config.layoutSlots.footer['slots'].unshift('PreFooterSlot');

config.layoutSlots.campaign_page_without_header = {
  slots: ['NarrowContentSection', 'WideContentSection', 'BottomNarrowSection']
 };

export const customLayoutConfig = config;

FirstSpirit-seitige Anforderungen

Sowohl die Shop als auch die FirstSpirit Driven Pages benötigen entsprechende Seitenvorlagen im FirstSpirit-Projekt, in denen die Eingabekomponenten pt_seoUrl und pt_cc_identifier konfiguriert sein müssen. Die Eingabekomponente pt_seoUrl ermöglicht die Definition einer SEO-Url und muss daher bearbeitbar sein. Im Gegensatz dazu handelt es sich bei der Eingabekomponente pt_cc_identifier um eine versteckte Komponente. Sie wird automatisch befüllt und stellt die Erreichbarkeit der Seite im ContentCreator sicher.

Darüber hinaus ist sicherzustellen, dass die Inhaltsbereiche der FirstSpirit-Vorlagen mit den konfigurierten Slots übereinstimmen: Für jeden definierten Slot muss die Seitenvorlage einen Inhaltsbereich mit demselben Namen besitzen. Andernfalls werden die redaktionellen Inhalte von der Storefront ignoriert und nicht im Live-Stand ausgegeben.

Das Mapping zwischen den konfigurierten Slots und den Inhaltsbereichen der FirstSpirit-Seitenvorlagen unterscheidet nicht zwischen Groß- und Kleinschreibung. Die Namen Section1 und section1 gelten daher als identisch und werden einander erfolgreich zugeordnet.

2.2.3. Merge-Strategien

Mit der FirstSpirit Connect (Headless): For SAP Commerce Cloud-Integration bezieht die Storefront sowohl Inhalte aus der Commerce Cloud als auch aus der jeweiligen CaaS-Instanz und verknüpft sie vor der Auslieferung miteinander. Dafür muss sie durch die fs-spartacus-bridge-Bibliothek erweitert werden, die entsprechend der Beschreibung im vorhergehenden Kapitel einzubinden und zu konfigurieren ist. Während der Konfiguration lässt sich optional eine Merge-Strategie definieren. Diese legt fest, wie die Inhalte, die sowohl Commerce Cloud- als auch FirstSpirit-seitig für einen Slot gepflegt sind, miteinander verknüpft werden.

Die folgenden Optionen stehen zur Auswahl:

REPLACE: Die Merge-Strategie REPLACE entspricht der Standardeinstellung der Bridge und muss daher nicht explizit angegeben werden. Sie bewirkt, dass die in FirstSpirit gepflegten Inhalte die in einem Slot enthaltenen Commerce Cloud-Inhalte überschreiben. Auf der entsprechenden Seite sind damit nur noch die FirstSpirit-Inhalte sichtbar.
APPEND: Soll eine Seite sowohl die Commerce Cloud- als auch die FirstSpirit-Inhalte für einen Slot anzeigen, kann zwischen den Merge-Strategien APPEND und PREPEND gewählt werden. Mit der Merge-Strategie APPEND zeigt die entsprechende Seite die in FirstSpirit gepflegten Inhalte unterhalb der für einen Slot bestehenden Commerce Cloud-Inhalte an.
PREPEND: Die Merge-Strategie PREPEND ist äquivalent zur zuvor genannten Option APPEND. Allerdings zeigt die Seite die FirstSpirit-Inhalte für einen Slot in diesem Fall oberhalb der aus der Commerce Cloud stammenden Inhalte an.

2.3. Erzeugung einer Dummy-Seite

Die FirstSpirit Connect (Headless): For SAP Commerce Cloud-Integration unterscheidet bei der Pflege redaktioneller Inhalte zwischen Shop und FirstSpirit Driven Pages. FirstSpirit Driven Pages können entweder ein eigenes, in der Storefront definiertes Layout verwenden oder das einer Shop Driven Page übernehmen.

In zweiten Fall muss Commerce Cloud-seitig eine Dummy-Seite existieren, die bis auf das gewünschte Layout leer ist. Das heißt, dass sie, abgesehen von beispielsweise einem allgemeinen Header und Footer, keine Inhalte besitzen.

Eine Dummy-Seite lässt sich mithilfe eines ImpEx-Skripts erzeugen. Das im folgenden Code-Block dargestellte Skript generiert die Dummy-Seite für die im Referenzprojekt enthaltenen FirstSpirit Driven Pages. Sie basiert auf dem LandingPage2Template-Template und enthält lediglich einen Header und einen Footer. Die Existenz der Dummy-Seite ist zwingend erforderlich für die Verwendung der FirstSpirit Driven Pages.

Weitere Informationen zur Erzeugung neuer Seiten in Spartacus sind im SAP Blog enthalten.

ImpEx-Skript

$contentCatalog=electronics-spaContentCatalog
$contentCVOnline=catalogVersion(CatalogVersion.catalog(Catalog.id[default=$contentCatalog]),\
CatalogVersion.version[default=Online])[default=$contentCatalog:Online]

$siteResource=jar:de.hybris.platform.spartacussampledataaddon.constants.\
   SpartacussampledataaddonConstants&/spartacussampledataaddon/import/\
   contentCatalogs/electronicsContentCatalog

# create dummy page in online catalog
INSERT_UPDATE ContentPage;$contentCVOnline[unique=true];uid[unique=true];name;\
   masterTemplate(uid,$contentCVOnline);label;defaultPage[default='true'];\
   approvalStatus(code)[default='approved'];homepage[default='false']
;;DummyCampaignPageWithHeader;Dummy Campaign Page With Header;LandingPage2Template;/dummycampaignpagewithheader

# create empty slots for page
INSERT_UPDATE ContentSlot;$contentCVOnline[unique=true];uid[unique=true];name;active
;;Section1-DummyCampaignPageWithHeader;Section1 Slot for DummyCampaignPageWithHeader;true
;;Section2A-DummyCampaignPageWithHeader;Section2A Slot for DummyCampaignPageWithHeader;true
;;Section2B-DummyCampaignPageWithHeader;Section2B Slot for DummyCampaignPageWithHeader;true
;;Section2C-DummyCampaignPageWithHeader;Section2C Slot for DummyCampaignPageWithHeader;true
;;Section3-DummyCampaignPageWithHeader;Section3 Slot for DummyCampaignPageWithHeader;true
;;Section4-DummyCampaignPageWithHeader;Section4 Slot for DummyCampaignPageWithHeader;true
;;Section5-DummyCampaignPageWithHeader;Section5 Slot for DummyCampaignPageWithHeader;true
;;BottomHeaderSlot-DummyCampaignPageWithHeader;Bottom Header Slot for DummyCampaignPageWithHeader;true

# configure content slots for page
INSERT_UPDATE ContentSlotForPage;$contentCVOnline[unique=true];uid[unique=true];\
   position[unique=true];page(uid,$contentCVOnline)[unique=true];contentSlot(uid,$contentCVOnline)[unique=true]
;;Section1-DummyCampaignPageWithHeader;Section1;DummyCampaignPageWithHeader;Section1-DummyCampaignPageWithHeader
;;Section2A-DummyCampaignPageWithHeader;Section2A;DummyCampaignPageWithHeader;Section2A-DummyCampaignPageWithHeader
;;Section2B-DummyCampaignPageWithHeader;Section2B;DummyCampaignPageWithHeader;Section2B-DummyCampaignPageWithHeader
;;Section2C-DummyCampaignPageWithHeader;Section2C;DummyCampaignPageWithHeader;Section2C-DummyCampaignPageWithHeader
;;Section3-DummyCampaignPageWithHeader;Section3;DummyCampaignPageWithHeader;Section3-DummyCampaignPageWithHeader
;;Section4-DummyCampaignPageWithHeader;Section4;DummyCampaignPageWithHeader;Section4-DummyCampaignPageWithHeader
;;Section5-DummyCampaignPageWithHeader;Section5;DummyCampaignPageWithHeader;Section5-DummyCampaignPageWithHeader
;;BottomHeaderSlot-DummyCampaignPageWithHeader;BottomHeaderSlot;DummyCampaignPageWithHeader;BottomHeaderSlot-DummyCampaignPageWithHeader

# language settings
$language=en
INSERT_UPDATE ContentPage;$contentCVOnline[unique=true];uid[unique=true];title[lang=$language]
;;DummyCampaignPageWithHeader;Dummy Campaign Page With Header

3. FirstSpirit - Installation und Konfiguration

Für die Verwendung der Funktionalitäten des FirstSpirit Connect (Headless): For SAP Commerce Cloud-Moduls ist FirstSpirit-seitig die Installation und Konfiguration unterschiedlicher Komponenten erforderlich. Die folgenden Unterkapitel erläutern die dafür notwendigen Schritte.

Zur Nutzung des FirstSpirit Connect (Headless): For SAP Commerce Cloud-Moduls muss außerdem das CaaS Connect-Modul konfiguriert werden. Die dafür notwendigen Schritte sind in der CaaS Connect-Dokumentation beschrieben.

Neben den Standardgruppen Everyone, Administrators und Developers existieren im Referenzprojekt drei weitere externe Gruppen: Editors, ChiefEditors und ProjectAdmins. Diese Gruppen besitzen verschiedene Rechte, die entsprechend ihrer Aufgaben gewählt und für die verschiedenen Verwaltungen definiert wurden. Personen außerhalb dieser Gruppen sind standardmäßig nicht berechtigt das Referenzprojekt zu verwenden.

Besteht darüber hinaus der Bedarf nach weiteren Accounts oder Gruppen, so ist ihre Erzeugung beim Technical Support anzufordern. Für neue Accounts ist dafür eine Angabe der folgenden Informationen erforderlich:

Vor- und Nachname
E-Mail-Adresse
zuzuordnende Gruppen

3.1. Konfiguration der Projekt-Komponente

Für den Einsatz des FirstSpirit Connect (Headless): For SAP Commerce Cloud-Moduls sind einige projektspezifische Informationen erforderlich. Sie sind über die Projekt-Komponente anzugeben, die dem bereitgestellten Referenzprojekt bereits hinzugefügt ist.

Zur Nutzung des FirstSpirit Connect (Headless): For SAP Commerce Cloud-Moduls ist außerdem eine Konfiguration des CaaS Connect-Moduls erforderlich. Die dafür notwendigen Schritte sind in der CaaS Connect-Dokumentation beschrieben.

Das Referenzprojekt bindet außerdem die Projekt-Komponente der CXT ContentCreator Extension ein. Diese enthält eine vordefinierte Konfiguration, deren Veränderung zu einer Verhaltensänderung des ContentCreators führen kann. Eine Anpassung der Konfiguration ist daher nur nach vorheriger Rücksprache mit dem Technical Support vorzunehmen.

Öffnen Sie für die Konfiguration den ServerManager und wählen Sie den Bereich Projekt-Eigenschaften Projekt-Komponenten.

Abbildung 5. Projekt-Eigenschaften - Projekt-Komponenten

Im Hauptpanel ist eine Liste aller bereits vorhandenen Projekt-Komponenten zu sehen. Selektieren Sie den Eintrag FirstSpirit Connect (Headless): For SAP Commerce Cloud for SAP Commerce Cloud Project Configuration und öffnen Sie den zugehörigen Konfigurationsdialog über Konfigurieren.

Der Dialog gliedert sich in fünf Reiter, von denen derzeit lediglich die Felder der Reiter Allgemein, Produkt DAP und Kategorie DAP zu berücksichtigen sind. Die nachfolgenden Unterkapitel erläutern sie im Detail. Die Reiter Vorschau und Inhalte besitzen derzeit keine Funktionalität.

3.1.1. Allgemein

Der Konfigurationsdialog der Projekt-Komponente enthält als erstes den Reiter Allgemein. Die in ihm zu definierenden Informationen müssen dem FirstSpirit-Server für eine Verbindung zur Commerce Cloud bekannt sein.

Abbildung 6. Projekt-Komponente - Allgemein

URI: Innerhalb des Reiters Allgemein ist zunächst die URI der Commerce Cloud-Instanz einzutragen. Sie ermöglicht dem FirstSpirit-Server den Aufbau einer Verbindung zur Commerce Cloud.
Connection timeout/Connection retries: Mithilfe der beiden Felder Connection timeout und Connection retries lassen sich die Zeitspanne (in Sekunden) sowie die Anzahl der Versuche definieren, die der FirstSpirit-Server für einen Verbindungsaufbau zur Commerce Cloud verwendet.

Der FirstSpirit-Server benötigt für die Abfrage von Informationen aus der Commerce Cloud eine OAuth-Authentifizierung. Die benötigten Authentifizierungsdaten sind in den nachfolgenden Feldern des Reiters Allgemein einzutragen. Die übrigen Reiter ermöglichen eine Überschreibung dieser Angaben und besitzen daher dieselben Felder. Die Überschreibung erfolgt durch die Aktivierung der Checkbox Override general OAuth settings in einem der übrigen Reiter.

Auth Server URI: Für die Verbindung zur Commerce Cloud benötigt der FirstSpirit-Server die Angabe des Standard-Endpunkts für die OAuth-Authentifizierung. Die Eingabe der URI dieses Endpunkts muss relativ zur URI der Commerce Cloud-Instanz erfolgen.
Username/Password: In den Feldern Username und Password sind die Zugangsdaten anzugeben, mit denen die Authentifizierung durchgeführt wird. In der Regel handelt es dabei um die Daten eines technischen Commerce Cloud-Accounts.
OAuth Client ID: Dieses Feld dient der Angabe der für die Authentifizierung genutzten Standard-Client-ID. Sie wird während der Konfiguration des OAuth-Clients erzeugt und definiert die Zugriffsrechte des technischen Accounts.
OAuth Client Secret: Zusätzlich zur Client ID wird an dieser Stelle die Eingabe des ihr zugehörigen Client Secrets erwartet.
OAuth Grant Type: Ergänzend zur Client ID und zum Client Secret setzt die OAuth-Authentifizierung einen Grant Type voraus. Dafür stellt die Combobox die zwei Optionen password und client credentials zur Auswahl.
OAuth Einstellungen testen: Durch einen Klick auf diesen Button lässt sich der Verbindungsaufbau zur Commerce Cloud testen. Wurde in einem der anderen Reiter die Überschreibung der OAuth-Authentifizierung aktiviert, werden die in ihm gespeicherten Einstellungen berücksichtigt.

3.1.2. Produkt DAP

Zusätzlich zum Reiter Allgemein besitzt der Konfigurationsdialog der Projekt-Komponente die Reiter Produkt DAP und Kategorie DAP. Sie dienen der Konfiguration der Reports im ContentCreator, die verschiedene Informationen voraussetzen.

Abbildung 7. Projekt-Komponente - Produkt DAP

Collection

Der Produkte-Report im ContentCreator listet die aus der Commerce Cloud stammenden Produkte auf und ermöglicht Redakteurinnen und Redakteuren die Verwendung dieser Produkte. Die Produkte lassen sich über einen REST-Endpunkt abfragen, der dem ContentCreator bekannt sein muss. Er ist daher in diesem Feld anzugeben.

PDP URL

An dieser Stelle ist die relative URL einer Produktdetailseite anzugeben. Als Platzhalter für den Produktcode ist die Verwendung des Ausdrucks {code} möglich. Der Standardwert entspricht p/{code}.

Header/Extract/Icon/Thumbnail

Suchergebnisse im Produkte-Report zeigen standardmäßig im Kennsatz den Produktnamen, im Ausriss die Katalog-Id und eine Miniaturansicht an. Die Felder Header, Extract, Icon und Thumbnail ermöglichen eine Konfiguration dieser Informationen. Dafür stehen neben einfachen Texteingaben die folgenden Platzhalter zur Verfügung:

${catalogId}
${catalogVersion}
${code}
${description}
${name}
${thumbnailMediaUrl}

Die in den Feldern getätigten Eingaben ersetzen die Standardinformationen in den Suchergebnissen des Produkte-Reports. Textuelle Eingaben werden dabei unverändert übernommen. Bleiben die Felder leer, zeigen die Suchergebnisse die Standardinformationen an.

Override general OAuth settings

Die Felder für die OAuth-Authentifizierung ermöglichen die Überschreibung der Eingaben im Reiter Allgemein. Die Überschreibung erfolgt durch die Aktivierung der Checkbox Override general OAuth settings. Andernfalls werden weiterhin die Eingaben aus dem Reiter Allgemein für die Authentifizierung verwendet.

3.1.3. Kategorie DAP

Der Reiter Kategorie DAP ist äquivalent zum Reiter Produkt DAP und dient der Konfiguration des Kategorie-Reports im ContentCreator.

Abbildung 8. Projekt-Komponente - Kategorie DAP

Katalog: Der Kategorie-Report im ContentCreator enthält die Kategorien aus der Commerce Cloud und stellt sie den Redakteurinnen und Redakteuren zur Verfügung. Dafür ist an dieser Stelle die zugehörige Katalog ID einzutragen.
Katalog Version: Die im ContentCreator bereitgestellten Kategorien stammen aus einem Produktkatalog. Ergänzend zur Katalog ID ist daher außerdem die Version des Produktkatalogs anzugeben, aus dem die Kategorien bezogen werden.
CDP URL: An dieser Stelle ist die relative URL einer Kategoriedetailseite anzugeben. Als Platzhalter für den Kategoriecode ist die Verwendung des Ausdrucks {code} möglich. Der Standardwert entspricht c/{code}.
Override general OAuth settings: Die Felder für die OAuth-Authentifizierung ermöglichen die Überschreibung der Eingaben im Reiter Allgemein. Die Überschreibung erfolgt durch die Aktivierung der Checkbox Override general OAuth settings. Andernfalls werden weiterhin die Eingaben aus dem Reiter Allgemein für die Authentifizierung verwendet.

3.2. Hinzufügen der Web-Komponenten

Für den ContentCreator wird eine Web-Komponente benötigt, die dem bereitgestellten Referenzprojekt bereits hinzugefügt ist. Sie ist standardmäßig global im ServerManager im Bereich Server-Eigenschaften Web-Applikationen installiert. In diesem Fall sind alle für die Web-Komponente erforderlichen Installations- oder Konfigurationsschritte bereits seitens der Crownpeak Technology GmbH durchgeführt.

Alternativ ist jedoch auch eine Installation der Web-Komponente in den Projekt-Eigenschaften möglich. Ausschließlich in diesem Fall muss sie noch auf einem aktiven Webserver installiert werden. Öffnen Sie hierfür den ServerManager und wählen Sie den Bereich Projekt-Eigenschaften Web-Komponenten.

Abbildung 9. Web-Komponenten in den Projekt-Eigenschaften

Innerhalb des Hauptpanels sind verschiedene Registerkarten zu sehen, die jeweils eine Liste der bereits vorhandenen Web-Komponenten enthalten. Diese Liste enthält für den ContentCreator die folgenden Einträge:

BasicWorkflows_ContentCreator_Library (nur bei der Verwendung der BasicWorkflows erforderlich)
CXT ContentCreator Extension: WebApp for ContentCreator
FirstSpirit Connect (Headless): For SAP Commerce Cloud for SAP Commerce Cloud Web App
FirstSpirit ThirdPartyPreview WebApp

Selektieren Sie in der Registerkarte einen Webserver über die Auswahlbox und starten Sie die Installation über den Button Installieren. Nach der erfolgreichen Installation öffnet sich ein Dialog, in welchem die Aktivierung des Webservers zu bestätigen ist.

Detaillierte Informationen zur Konfiguration von Web-Komponenten finden Sie in der FirstSpirit Dokumentation für Administratoren.

3.3. Definition der externen Vorschau-URL

Durch die Verwendung des Omnichannel Managers stellt der ContentCreator externe Inhalte aus der Commerce Cloud dar, auf die der Omnichannel Manager eine Zugriffsmöglichkeit benötigt. In den ContentCreator-Eigenschaften ist daher die Vorschau-URL der Storefront anzugeben. Da die Angabe stets projektspezifisch ist, existiert für sie innerhalb des Referenzprojekts keine Standardkonfiguration.

Öffnen Sie für die Eingabe den Bereich Projekt-Eigenschaften ContentCreator innerhalb des ServerManagers und tragen Sie in dem Feld Externe Vorschau-URL die URL der Storefront ein.

Abbildung 10. Externe Vorschau-URL

3.4. Arbeitsabläufe

Die Freigabe und Löschung von Inhalten durch Redakteurinnen und Redakteure erfolgt innerhalb des bereitgestellten Referenzprojekts FirstSpirit Connect Reference Project über die BasicWorkflows. Diese sind dem Projekt bereits hinzugefügt und können alternativ zu projektspezifischen Arbeitsabläufen eingesetzt werden.

Installation des BasicWorkflows-Moduls

Vor der Verwendung der Arbeitsabläufe muss zunächst das BasicWorkflows-Modul auf dem FirstSpirit-Server installiert und die Web-Komponente aktiviert sein. Die dafür notwendigen Schritte sind analog zur Installation der anderen Module und der Aktivierung der dem FirstSpirit Connect (Headless): For SAP Commerce Cloud-Modul zugehörigen Web-Komponente. Die Web-Komponente der BasicWorkflows wird ebenfalls in der Registerkarte ContentCreator benötigt.

Der Einsatz der BasicWorkflows erfordert darüber hinaus die Auswahl des bereitgestellten BasicWorkflows Status Providers im Bereich Projekt-Eigenschaften ContentCreator innerhalb des ServerManagers. Im Referenzprojekt FirstSpirit Connect Reference Project ist diese Einstellung bereits vorgenommen.

Abbildung 11. Element Status Provider

Vorlagen

Die BasicWorkflows benötigen verschiedene Vorlagen. Diese müssen üblicherweise über das Kontextmenü in das verwendete FirstSpirit-Projekt importiert werden. Im Referenzprojekt sind sie jedoch bereits enthalten und ein Import der Vorlagen ist somit nicht notwendig.

Rechtevergabe

Im letzten Schritt müssen die Arbeitsabläufe in den einzelnen Verwaltungen erlaubt werden, um auf FirstSpirit-Elementen ausgeführt werden zu können. Dafür lässt sich auf den Root-Knoten der Verwaltungen über den Kontextmenüeintrag Extras Rechte ändern die Rechtevergabe öffnen. Dieser Schritt ist im Referenzprojekt ebenfalls bereits durchgeführt und entfällt damit.

Die auf den Root-Knoten der Verwaltungen gesetzten Rechte zur Ausführung des Arbeitsablaufs beziehen sich auf die Gruppe Everyone. Falls dies nicht gewünscht ist, muss eine manuelle Anpassung der Rechte erfolgen.

Nähere Informationen zur Installation, Konfiguration und Funktionalität des Arbeitsablaufs finden Sie in der BasicWorkflows-Dokumentation.

3.5. TranslationStudio

Die Übersetzung redaktioneller Inhalte erfolgt oft in Zusammenarbeit mit externen Übersetzungsagenturen oder mithilfe von Übersetzungsservices. Die Integration unterstützt daher TranslationStudio, welches den Export zu übersetzender Inhalte in ein Zielsystem sowie den anschließenden Import der Übersetzungen in das FirstSpirit-Projekt ermöglicht. Das TranslationStudio-Modul ist standardmäßig im Cloud-Umfeld der Crownpeak Technology GmbH installiert, so dass dessen Funktionalitäten bei Bedarf durch die Durchführung weniger Schritte aktivierbar sind.

Die Verwendung TranslationStudios setzt neben der Modulinstallation zusätzlich die Installation der TranslationStudio-Applikation sowie der Web- und Projekt-Komponente voraus. Darüber hinaus sind verschiedene Aktionen innerhalb des FirstSpirit-Projekts erforderlich. Sowohl die Einrichtung der Applikation als auch alle weiteren durchzuführenden Schritte sind im TranslationStudio Installation Manual beschrieben.

Die Installation der Projekt-Komponente ersetzt im ContentCreator den Button der von FirstSpirit bereitgestellten Übersetzungsfunktion. Der Button besitzt jedoch nur dann eine Funktionalität, wenn auch alle übrigen Konfigurationsschritte erfolgreich abgeschlossen sind.

3.6. Projekteinstellungen

Die Commerce Cloud-seitige Installation umfasst unter anderem die Einbindung der Bibliothek fs-spartacus-bridge. Diese erwartet neben verschiedenen CaaS-Angaben eine Definition der Commerce Cloud-Templates, deren Bearbeitung im ContentCreator ermöglicht werden soll.

Die in der Konfiguration der Bridge angegebenen Shop Driven Pages setzen sowohl FirstSpirit-seitig als auch in der Commerce Cloud eine Seite voraus. Das Mapping zwischen der FirstSpirit-Seitenvorlage und dem Commerce Cloud Template erfolgt über das Formular der Projekteinstellungen.

Die Projekteinstellungen enthalten für jedes Commerce Cloud-Template eine Eingabekomponente, in der die entsprechende Seitenvorlage referenziert ist. Für Inhalts-, Produkt- und Kategorieseiten ist darüber hinaus jeweils ein Inhalteordner ausgewählt. Dieser definiert den Speicherort der Seiten, die auf Basis der Seitenvorlagen erstellt werden. Die Strukturverwaltung enthält Ordner mit denselben Namen, in denen die zugehörigen Seitenreferenzen abgelegt werden.

Die Referenznamen der in den Projekteinstellungen enthaltenen Eingabekomponenten folgen alle dem folgenden Schema:

ps_template_<Name des Commerce Cloud Templates> bzw.
ps_folder_<Commerce Cloud Seitentyp>

Bei einer Erweiterung der Projekteinstellungen ist dieses Schema für die Referenznamen neuer Eingabekomponenten zu übernehmen.

Abbildung 12. Projekteinstellungen - Mapping für Produktseiten

3.7. Hinzufügen der Projektsprachen

Innerhalb des durch die FirstSpirit Connect (Headless): For SAP Commerce Cloud-Integration geschaffenen Gesamtsystems übernimmt die Storefront weiterhin die Auslieferung der Inhalte und bestimmt somit die Sprache, in der diese dargestellt werden. Aus diesem Grund müssen alle in der Storefront verfügbaren Sprachen im FirstSpirit-Projekt konfiguriert sein.

Fehlen in der Storefront verfügbare Sprachen im verwendeten FirstSpirit-Projekt, ist die Erzeugung redaktioneller Inhalte für diese Sprachen nicht möglich. Aufgrund dieser Abweichung können Fehler auftreten.

Damit Sprachen in einem FirstSpirit-Projekt verwendbar sind, müssen auf dem FirstSpirit-Server die entsprechenden Sprach-Vorlagen existieren. Fehlen diese, ist ein Hinzufügen der Projektsprachen nicht möglich. Wenden Sie sich in diesem Fall bitte an den Technical Support.

Öffnen Sie für das Hinzufügen der Projektsprachen den ServerManager und wählen Sie den Bereich Projekt-Eigenschaften Sprachen. Im Hauptpanel ist eine Liste aller bereits im Projekt verfügbaren Sprachen zu sehen. Per Rechtsklick in diesem Hauptpanel öffnet sich ein Kontextmenü, das die Ergänzung, Bearbeitung und Löschung von Projektsprachen ermöglicht. Wählen Sie in der Auswahlliste, die sich per Klick auf den Menüpunkt Neu öffnet, die gewünschte Sprache und bestätigen Sie die Auswahl mit OK. Die Sprache ist anschließend in der Liste im Hauptpanel sichtbar. Wiederholen Sie den Vorgang für alle Sprachen, die im Projekt zur Verfügung stehen sollen.

Detaillierte Informationen zur Konfiguration von Projektsprachen sind in der Online Dokumentation für FirstSpirit enthalten.

3.8. Deployment-Aufträge

Die Veröffentlichung redaktioneller Inhalte sowie die Aktualisierung des Online CaaS erfolgt in Verbindung mit CaaS Connect bei jeder Freigabe. Ein zusätzlicher Deployment-Prozess ist in diesem Fall nicht notwendig.

Dennoch können während des Projektverlaufs Situationen auftreten, die ein Deployment erfordern. Das CaaS Connect-Modul stellt daher zwei Aufträge bereit, die dem Projekt automatisch hinzugefügt werden. Sie benötigen keine projektspezifische Anpassung.

4. Referenzprojekt

Das FirstSpirit Connect (Headless): For SAP Commerce Cloud-Modul stellt unterschiedliche Möglichkeiten bereit, auf Shop-Inhalte aus Spartacus zuzugreifen und diese in FirstSpirit zu verwenden. Dafür werden sowohl innerhalb des FirstSpirit-Projekts als auch Spartacus-seitig verschiedene Komponenten benötigt. Diese und die zwischen ihnen bestehenden Beziehungen werden in den nachfolgenden Unterkapiteln anhand des mitgelieferten Referenzprojekts beschrieben.

4.1. Seiten

Im Gegensatz zur Auslieferung der Inhalte verlagert sich deren Erstellung und Pflege von der Commerce Cloud nach FirstSpirit. FirstSpirit stellt dafür den ContentCreator zur Verfügung. In ihm lassen sich mithilfe des Omnichannel Managers sowohl Shop als auch FirstSpirit Driven Pages darstellen und mit redaktionellen Inhalten anreichern.

Die Erzeugung und Bearbeitung redaktioneller Inhalte erfolgt in FirstSpirit grundsätzlich auf Basis einer Seitenreferenz. Sie und die ihr zugrundeliegende Seite werden im bereitgestellten Referenzprojekt automatisch im Hintergrund erzeugt, sobald im ContentCreator eine neue Seite erzeugt wird. Das Skript page_type_mapping ermittelt dabei die zugehörige FirstSpirit-Seitenvorlage, die im Projekt enthalten sein muss.

Das Referenzprojekt besitzt für Inhalts-, Produkt- und Kategorieseiten, die den Shop Driven Pages entsprechen, die folgenden Seitenvorlagen:

cartpagetemplate
contentpage1
landingpage2
searchresultslistpage
storefinderpage
product_detail_page
category_page

Die Seitenvorlagen für die Shop Driven Pages bilden die jeweiligen Commerce Cloud Page Templates ab und unterscheiden sich lediglich in der Anzahl ihrer Inhaltsbereiche. Jeder dieser Inhaltsbereiche erlaubt die Einbindung unterschiedlicher Absätze, die der Erstellung und Persistierung der redaktionellen Inhalte dienen. Das Mapping zwischen den Commerce Cloud-Templates und den FirstSpirit-Seitenvorlagen für Shop Driven Pages erfolgt wie im Installationskapitel beschrieben in den Projekteinstellungen. Da FirstSpirit Driven Pages keine zugehörige Seite in der Commerce Cloud besitzen, ist für sie kein Mapping erforderlich.

Sowohl für die Shop als auch für die FirstSpirit Driven Pages ist sicherzustellen, dass die Inhaltsbereiche der FirstSpirit-Vorlagen mit den in der Bridge konfigurierten Slots übereinstimmen: Für jeden definierten Slot muss die Seitenvorlage einen Inhaltsbereich mit demselben Namen besitzen. Andernfalls werden die redaktionellen Inhalte von der Storefront ignoriert und nicht im Live-Stand ausgegeben.

Darüber hinaus müssen alle Seitenvorlagen die Eingabekomponenten pt_seoUrl und pt_cc_identifier besitzen. Die sprachabhängige Texteingabekomponente pt_seoUrl ermöglicht die Definition einer SEO-Url und muss daher bearbeitbar sein. Im Gegensatz dazu handelt es sich bei der sprachunabhängigen Texteingabekomponente pt_cc_identifier um eine versteckte Komponente. Sie wird automatisch befüllt und stellt die Erreichbarkeit der Seite im ContentCreator sicher.

Der folgende Code-Ausschnitt zeigt die Definition der beiden Eingabekomponenten:

Eingabekomponenten pt_seoUrl und pt_cc_identifier

<CMS_INPUT_TEXT name="pt_seoUrl" hFill="yes" useLanguages="yes">
  <LANGINFOS>
    <LANGINFO lang="*" label="SEO URL"/>
  </LANGINFOS>
</CMS_INPUT_TEXT>

<CMS_INPUT_TEXT name="pt_cc_identifier" hFill="yes" hidden="yes" useLanguages="no">
  <LANGINFOS>
    <LANGINFO lang="*" label="Commerce Cloud Identifier"/>
  </LANGINFOS>
</CMS_INPUT_TEXT>

4.2. Absätze

Innerhalb des in der Auslieferung enthaltenen Referenzprojekts FirstSpirit Connect Reference Project repräsentieren die Inhaltsbereiche einer FirstSpirit-Seitenvorlage die Slots einer Commerce Cloud-Seite. Ihnen können Absätze hinzugefügt werden, die jeweils einem Content-Modul entsprechen.

Das Referenzprojekt stellt dafür die folgenden Absatzvorlagen zur Verfügung:

Teaser (teaser)
Karussell (carousel)
Multi Slot Container (multi_slot_container)
Standortübersicht (location_overview)

Teaser

Der Teaser entspricht einem einzelnen Bild im Querformat, das standardmäßig im Kopfbereich einer Seite eingebunden ist. Auf diesem Bild sind ein weiteres Bild sowie ein Text platzierbar.

Die Absatzvorlage erlaubt neben der Auswahl des Bilds und der beiden Overlay-Möglichkeiten die Angabe eines Verweises sowie eines Alt-Textes. Für die Verlinkung des Bilds sind dabei alle im Referenzprojekt verfügbaren Verweistypen zulässig.

Karussell

Das Karussell ist äquivalent zum Teaser. Im Gegensatz zu diesem bindet es jedoch mehrere Bilder ein, die je nach Konfiguration kontinuierlich rotieren oder einzeln durchklickbar sind.

Die einzelnen Bilder des Karussells entsprechen jeweils einem Teaser. Für diese besitzt das Karussell daher dieselben Funktionen. Darüber hinaus erlaubt die Absatzvorlage die De-/Aktivierung des automatischen Bilddurchlaufs und die Definition der Anzeigedauer in Sekunden.

Multi Slot Container

Der Multi Slot Container ist eine Layoutkomponente, die neben der Eingabe einer Überschrift die automatische Anordnung von Inhalts-, Kategorie- oder Produktelementen ermöglicht. Die Anordnung der Elemente ist dabei abhängig von ihrer Anzahl: Bis zu einer Anzahl von vier Elementen werden diese nebeneinander dargestellt und entsprechend skaliert. Zusätzliche Elemente werden in Gruppen von ebenfalls bis zu vier Elementen zusammenfasst und in weiteren Zeilen darunter angezeigt.

Die Vorlagen der Elemente sind im Referenzprojekt unter den Referenznamen msc_content_item, msc_category_item und msc_product_item gespeichert. Alle drei ermöglichen die Eingabe einer Überschrift, eines Untertitels und eines Teasertextes sowie die Auswahl eines Bilds, für das ein Alternativtext angebbar ist. Des Weiteren enthält die Darstellung der Elemente jeweils einen Button, dessen Beschriftung frei definierbar ist und der auf die Detailansicht des jeweiligen Elements verweist. Dieser Button ist nur dann sichtbar, wenn der Multi Slot Container lediglich ein einziges Element enthält.

Ergänzend zu den genannten Eingabemöglichkeiten erlaubt das Inhaltselement die Definition eines Verweises. Auch in diesem Fall sind dafür alle im Referenzprojekt verfügbaren Verweistypen zulässig.

Das Kategorieelement besitzt zusätzlich zu den genannten Eingabekomponenten eine Komponente zur Auswahl einer Kategorie. Wird für eine Kategorie kein Bild ausgewählt, zeigt das Kategorieelement ein Default-Bild an.

Im Gegensatz zum Kategorieelement stammen die Informationen für das Produktelement standardmäßig aus der Commerce Cloud. Sie dienen als Fallback und werden durch Eingaben in den genannten Komponenten überschrieben.

Standortübersicht

Diese Absatzvorlage erlaubt die Eingabe einer frei definierbaren Überschrift und die Auswahl beliebig vieler Standorte, die jeweils verschiedene Adressdaten enthalten. Jeder dieser Standorte entspricht einem Datensatz, der in der Datenquelle Standorte gespeichert ist. Die selektierten Datensätze werden als zweizeilige Adressen in Form einer Übersicht unterhalb der angegebenen Überschrift dargestellt.

Jede dieser im Referenzprojekt verfügbaren Absatzvorlagen enthält die Eingabekomponente st_languageFallbackEnabled und die ihr zugehörige Regel. Die Eingabekomponente entspricht einer Checkbox, bei deren Aktivierung die in der Bridge konfigurierte Fallback-Sprache verwendet wird. Die Inhalte des Absatzes werden in diesem Fall durch die Inhalte der Fallback-Sprache ersetzt. Weitere Informationen sind im Kapitel zur Verwendung der Fallback-Sprache enthalten.

Die Nutzung der Fallback-Sprache setzt ihre Definition in der Bridge-Konfiguration voraus.

4.3. Verweise

Die FirstSpirit-seitig gepflegten, redaktionellen Inhalte können die nachfolgenden Verweise enthalten, die sie mit anderen Inhalten verknüpfen. Sie basieren auf Verweisvorlagen, die im Referenzprojekt bereits enthalten sind.

Kategorie- und Produktverweis: Das FirstSpirit Connect (Headless): For SAP Commerce Cloud-Modul stellt im ContentCreator jeweils einen Report für Produkte und Kategorien bereit. Sie dienen der Darstellung der aus Spartacus stammenden Kategorie- und Produktinformationen, die sich für Verweise auf Kategorie- bzw. Produktdetailseiten verwenden lassen.

Das Referenzprojekt enthält dafür die Verweisvorlagen category_link und product_link, die einem Kategorie- bzw. Produktverweis entsprechen. Sie ermöglichen die Referenzierung von Kategorie- bzw. Produktdetailseiten und sind jeweils äquivalent zueinander.
Suchverweis: Das Referenzprojekt enthält die Verweisvorlage search_link, die einem Suchverweis entspricht. Dieser ermöglicht die Verlinkung einer Suchergebnisseite zu einem definierten Suchbegriff.
Inhaltsverweis: Die im Referenzprojekt enthaltene Verweisvorlage content_link entspricht einem Inhaltsverweis. Er ermöglicht die Referenzierung von Seiten, die innerhalb des Referenzprojekts gepflegt sind.

Die Frontend-seitige Verarbeitung der Verweise erfolgt mithilfe des SemanticPathServices. Er erzeugt auf Basis der an ihn übergebenen CaaS-Daten die erforderlichen URLs.

5. Anwendungsfälle

Innerhalb des Verlaufs eines Projekts können unterschiedliche Situationen auftreten, die bestimmte Handlungsschritte erfordern. Die nachfolgenden Unterkapitel stellen Situationen dar, die typischerweise in Integrationsprojekten vorkommen können, und beschreiben anhand des mitgelieferten Referenzprojekts die notwendigen Schritte für ihre Auflösung.

5.1. Entwicklung eines Content-Moduls

Innerhalb des mit der FirstSpirit Connect (Headless): For SAP Commerce Cloud-Integration geschaffenen Gesamtsystems übernimmt die Spartacus Storefront die Auslieferung der redaktionellen Inhalte. Die Erstellung und Pflege dieser Inhalte verlagert sich jedoch von der Commerce Cloud nach FirstSpirit. Das bereitgestellte Referenzprojekt FirstSpirit Connect Reference Project enthält aus diesem Grund die folgenden Absatzvorlagen:

teaser
carousel
multi_slot_container
location_overview

Jede dieser Absatzvorlagen setzt Spartacus-seitig jeweils eine Angular UI-Komponente voraus. Die UI-Komponenten nehmen die darzustellenden Inhalte entgegen und definieren ihre Ausgabe im Shop.

Die Entwicklung eines neuen Content-Moduls umfasst somit neben der Ergänzung einer weiteren Absatzvorlage im FirstSpirit-Projekt immer auch die Implementierung einer zugehörigen Angular UI-Komponente im Frontend. Im Detail sind die folgenden Schritte erforderlich, die im Verlauf des Kapitels näher erläutert werden:

Erzeugung einer Absatzvorlage inklusive gepflegter Inhalte
Import und Konfiguration des DataVisualizers
Erstellung eines Converters
Implementierung der Angular UI-Komponente
Erweiterung der Storefront

Erzeugung einer Absatzvorlage

Die Entwicklung eines neuen Content-Moduls erfordert zunächst die Erstellung einer neuen Absatzvorlage innerhalb des SiteArchitects. Die Vorlage ist anschließend in einer Seite einzubinden und in allen verfügbaren Sprachen mit Inhalt zu füllen. Mit der Speicherung dieser Inhalte werden sie automatisch in den Preview CaaS übertragen und stehen somit in der Vorschau zur Verfügung.

In den nachfolgenden Schritten ist an verschiedenen Stellen die Angabe des Referenznamens der neuen Absatzvorlage erforderlich. Diese Stellen sind alle durch den Platzhalter <SECTION_REF_NAME> markiert. Der Platzhalter ist in allen Fällen durch den Referenznamen zu ersetzen.

Dasselbe gilt für eine in dem Absatz enthaltene Eingabekomponente, die in den nachfolgenden Schritten den Namen st_input_component besitzt.

Import und Konfiguration des DataVisualizers

Die fs-spartacus-view-components-Bibliothek enthält unter anderem den DataVisualizer, der eine unverarbeitete Ausgabe der im CaaS gespeicherten JSON-Struktur im ContentCreator ermöglicht. Er erfordert dafür einen Import in das Hauptmodul der Spartacus-Applikation (app.module.ts) sowie die Konfiguration als Darstellungskomponente für die zuvor erstellte Absatzvorlage. Für die Bereitstellung aller Funktionalitäten ist darüber hinaus der Import des ConfigModuls notwendig.

Import des ConfigModuls

import { ConfigModule } from '@spartacus/core';

Der folgende Code-Ausschnitt zeigt die notwendigen Anpassungen im Hauptmodul. Der Platzhalter <SECTION_REF_NAME> ist durch den Referenznamen der im ersten Schritt angelegten Absatzvorlage zu ersetzen.

Import und Konfiguration des DataVisualizers

import { ConfigModule } from '@spartacus/core';
import { DataVisualizerComponent } from 'fs-spartacus-view-components';

[...]

@NgModule({
   imports: [
      ConfigModule.withConfig({
         cmsComponents: {<SECTION_REF_NAME>: {component: DataVisualizerComponent}}
      })
   ]
})
export class AppModule { }

Nach der Einbindung des DataVisualizers zeigt die Seite, die den neuen Absatz enthält, dessen zugehörige CaaS-Informationen in der Vorschau des ContentCreators an. Mit dem Button COPY TO CLIPBOARD lassen sich die dargestellten Daten außerdem in die Zwischenablage übernehmen. Sie sind für die nachfolgende Erstellung des Converters erforderlich.

Die Storefront setzt die in den dargestellten Daten enthaltenen Parameter uid und typeCode voraus. Sie müssen daher zwingend im Rückgabewert des nachfolgend zu erstellenden Converters enthalten sein.

Abbildung 13. Data Visualizer

Beispiel
Im Falle eines Absatzes, der beispielsweise lediglich eine CMS_INPUT_TEXT-Eingabekomponente für eine Überschrift (st_headline) besitzt, entspricht die Ausgabe des DataVisualizers dem folgenden Code-Ausschnitt:

Ausgabe des DataVisualizers

{  "uid": "headline",
   "typeCode": "headline",
   "otherProperties": {
      "formData": {
         "st_headline": {
            "fsType": "CMS_INPUT_TEXT",
            "name": "st_headline",
            "value": "Only this week: 20% discount"
         }
      },
      "previewId": "b547b345-6077-4574-97b1-308ebcc2e58d.en_GB"
   }
}

Erstellung eines Converters

Die im CaaS gespeicherten Daten für den neuen Absatz sind sehr verschachtelt und enthalten darüber hinaus Informationen, die für die Ausgabe im Shop nicht benötigt werden. Aus diesem Grund ist es empfehlenswert, vor der Übergabe der Daten an die Angular UI-Komponente zunächst einen zusätzlichen Transformationsschritt hinzuzufügen. Die Transformation der Informationen in ein für die Komponente optimales Format übernimmt ein Converter. Dieser muss den folgenden Code enthalten und ist unter dem Namen <SECTION_REF_NAME>.component.converter.ts an einer beliebiger Stelle im Spartacus-Projekt abzuspeichern. Der Platzhalter <SECTION_REF_NAME> entspricht dabei dem Referenznamen der zuvor erstellten Absatzvorlage.

Converter

import { Injectable, InjectionToken } from '@angular/core';
import { Converter, CmsComponent } from '@spartacus/core';

@Injectable({ providedIn: 'root' }) (1)
export class NewSectionComponentConverter implements Converter<CmsComponent, CmsComponent> { (2)
   public convert(source: CmsComponent): CmsComponent { (3)
      return {
         uid: source.uid,
         typeCode: source.typeCode,
         previewId: source.otherProperties.previewId,
         value: source.otherProperties.formData.st_input_component.value (4)
      } as CmsComponent;
   }
}

export const NewSectionConverterToken = new InjectionToken<Converter<CmsComponent,CmsComponent>>('NewSectionConverter'); (5)

1	Die Injectable-Annotation erzeugt einen neuen Angular-Service. Dieser erlaubt die spätere Injection des neuen Converters in die Bridge.
2	Die neue Klasse `NewSectionComponentConverter` implementiert das durch Spartacus bereitgestellte Converter-Interface, das die Methode `convert` erwartet. Bei jeder Verarbeitung des Absatzes, für den der Converter registriert ist, erfolgt ein automatischer Aufruf dieser Methode.
3	Mithilfe des `source`-Parameters erhält die `convert`-Methode alle für den Absatz verfügbaren Informationen aus dem CaaS. Der Rückgabewert der Methode ermöglicht die Filterung dieser Daten und definiert welche Parameter an die Angular UI-Komponente übertragen werden. Die Parameter `uid` und `typeCode` sind dabei zwingend erforderlich, da sie durch die Storefront vorausgesetzt werden.
4	Die Struktur der zugehörigen Werte ergibt sich aus dem CaaS-Dokument und ist insbesondere für die zu übergebenden Formulardaten entsprechend anzupassen. Die dargestellte Zeile bezieht sich auf eine einfache `CMS_INPUT_TEXT`-Eingabekomponente.
5	Der an dieser Stelle erzeugte `NewSectionConverterToken` ermöglicht die spätere Registrierung des `NewSectionComponentConverters` im Hauptmodul der Spartacus-Applikation (`app.module.ts`).

Implementierung der Angular UI-Komponente

Das mithilfe des Converters definierte Datenformat ermöglicht anschließend die Implementierung der Angular UI-Komponente, die unter dem Namen <SECTION_REF_NAME>.component.ts an einer beliebigen Stelle im Spartacus-Projekt abzuspeichern ist.

Der folgende Code-Ausschnitt zeigt ein Beispiel für den Inhalt der Komponente:

Angular UI-Komponente

import { CmsComponent } from '@spartacus/core';
import { CmsComponentData } from '@spartacus/storefront';
import { Component } from '@angular/core';

@Component({ (1)
   template: (2)
      `<ng-container *ngIf="(componentData?.data$) | async as convertedData">
         <h1 [attr.data-preview-id]="convertedData.previewId">{{convertedData.value}}</h1> (3)
      </ng-container>`,
})

export class NewSectionComponent { (4)
   constructor(public componentData: CmsComponentData<CmsComponent>) { }
}

1	Die Erzeugung der neuen Angular UI-Komponente erfolgt über die Component-Annotation. Die Annotation ermöglicht die spätere Injection der Komponente in die Bridge.
2	Die `template`-Eigenschaft definiert die HTML-Ausgabe der übergebenen Daten im Shop, die projektspezifisch an die zu erstellende Komponente anzupassen ist. Die Ausgabe erfolgt über ein Container-Element (`ng-container`), das lediglich im Fall existierender Daten angezeigt wird. Existieren Daten, werden sie mithilfe der Variablen `convertedData` asynchron an das Content-Modul übergeben.
3	In diesem Beispiel gibt die Komponente lediglich eine Überschrift aus. Dafür greift sie auf den im Converter festgelegten Parameter `value` zurück, der die zugehörigen Formulardaten des anfangs erstellten Absatzes enthält. Darüber hinaus enthält sie das Attribut `data-preview-id`, das als Wert die vom Converter übergebene `previewId` besitzt und die Bearbeitung der Überschrift im ContentCreator erlaubt.
4	An dieser Stelle erfolgt die Erstellung der neuen Angular UI-Komponente. Sie erhält als Konstruktorparameter die vom Converter zurückgegebenen Daten.

Erweiterung der Storefront

Die Ausgabe des im ersten Schritt erstellten Absatzes im Shop setzt die Einbindung der implementierten Angular UI-Komponente sowie die Registrierung des neuen Converters in der Storefront voraus. Dafür ist die nachfolgende Erweiterung des Hauptmoduls der Spartacus-Applikation (app.module.ts) erforderlich:

Erweiterung des Hauptmoduls

import { NewSectionComponent } from './<SECTION_REF_NAME>.component';
import { NewSectionConverterToken, NewSectionComponentConverter } from './<SECTION_REF_NAME>.component.converter';
import { FsComponentConverter } from 'fs-spartacus-common';

@NgModule({
   declarations: [NewSectionComponent], (1)
   imports: [
      ConfigModule.withConfig({
         cmsComponents: {<SECTION_REF_NAME>: { component: NewSectionComponent }} (2)
      })
   ],
   providers: [
      {  provide: NewSectionConverterToken, (3)
         useClass: NewSectionComponentConverter,
         multi: true
      },
      {  provide: FsComponentConverter, (4)
         useValue: {
            <SECTION_REF_NAME>: NewSectionConverterToken
         },
         multi: true (5)
      }
   ],
   entryComponents: [NewSectionComponent] (6)
})
export class AppModule { }

1	Innerhalb des Hauptmoduls erfolgt zunächst eine Deklaration der neuen Komponente, um sie im Spartacus-Projekt einzubinden.
2	Das `imports`-Attribut verknüpft die im ersten Schritt erstellte Absatzvorlage mit der Komponente und weist Spartacus damit an, bei einer Verarbeitung des Absatzes immer diese Verknüpfung zu verwenden. Der Platzhalter `<SECTION_REF_NAME>` ist dabei durch den Referenznamen der neuen Absatzvorlage zu ersetzen.
3	Die Registrierung des Converters erfolgt in zwei Schritten mithilfe des `providers`-Attributs: Der erste `provide`-Eintrag deklariert den Converter als Angular-Service in der Storefront. Er bewirkt, dass die Storefront zur Laufzeit bei jeder Verwendung des `NewSectionConverterTokens` automatisch eine Instanz des Converters erzeugt. Für eine Registrierung weiterer Converter anderer Absätze ist dieser Eintrag zu duplizieren und entsprechend anzupassen.
4	Der zweite `provide`-Eintrag macht den Converter der Bridge bekannt, indem mithilfe des `useValue`-Parameters eine Verknüpfung zwischen dem neu erstellten Absatz und dem Token des Converters hergestellt wird. Die Bridge greift somit bei jeder Verarbeitung des Absatzes auf den Token zu, der seinerseits die Erzeugung einer neuen Instanz des Converters anstößt. Der Platzhalter `<SECTION_REF_NAME>` ist dabei auch an dieser Stelle durch den Referenznamen der neuen Absatzvorlage zu ersetzen. Die Werte des `useValue`-Parameter sind in ihrer Anzahl unbegrenzt und entsprechen jeweils einem Key/Value-Paar. Sollen der Bridge weitere Converter für andere Absätze bekannt gemacht werden, lassen sich die zugehörigen Key/Value-Paare kommasepariert hinzufügen: Beispiel: `useValue: { headline: HeadlineConverterToken, carousel: CarouselConverterToken }`
5	Der Parameter `multi` verhindert in beiden Fällen eine Überschreibung vorheriger Deklarationen zur Laufzeit.
6	Der Eintrag `entryComponents` teilt dem Offline Template Compiler (OTC) von Angular mit, dass eine Erzeugung der Komponente zur Laufzeit möglich ist.

5.2. Verwendung von Datensätzen

Die Ausgabe der in FirstSpirit gepflegten Inhalte erfolgt Spartacus-seitig über Angular UI-Komponenten. Diese nehmen die darzustellenden Inhalte entgegen und definieren die HTML-Darstellung im Shop.

Die Pflege der Inhalte basiert auf Absatzvorlagen, die neben reinen Inhalten auch Datensätze einbinden können. Die Verwendung von Datensätzen setzt eine FS_INDEX-Eingabekomponente voraus, die wiederum die zugehörige Datenquelle referenziert.

Das bereitgestellte Referenzprojekt FirstSpirit Connect Reference Project enthält als Beispiel die Absatzvorlage location_overview. Diese erlaubt die Eingabe einer Überschrift und die Auswahl beliebig vieler Datensätze, die jeweils einer Adresse entsprechen. Dafür besitzt sie die FS_INDEX-Eingabekomponente st_locations, die ihrerseits die Datenquelle locations referenziert.

FS_INDEX-Eingabekomponente

<FS_INDEX name="st_locations" height="1" useLanguages="no">
   <LANGINFOS>
      <LANGINFO lang="*" label="Locations"/>
      <LANGINFO lang="DE" label="Standorte"/>
   </LANGINFOS>
   <SOURCE name="DatasetDataAccessPlugin">
      <TEMPLATE uid="locations.locations"/>
   </SOURCE>
</FS_INDEX>

Die selektierten Datensätze werden im CaaS lediglich als Referenz an dem Absatz gespeichert. Bei der Abfrage der Daten prüft die Bridge daher automatisch alle Dokumente auf solche Referenzen und ermittelt die Datensätze anhand ihrer ID. Der dem Absatz zugehörige Converter nimmt die Daten Spartacus-seitig entgegen und wandelt sie in ein für die Angular UI-Komponente optimales Format um. Jede dieser Komponente ist einer FirstSpirit-Absatzvorlage zugeordnet und definiert die HTML-Ausgabe der übergebenen Daten im Shop.

Für die Absatzvorlage location_overview stellt die Integration die Komponente location-overview zur Verfügung. Sie stellt die im FirstSpirit-Projekt selektierten Datensätze in Form einer Übersicht unterhalb der angegebenen Überschrift dar.

5.3. Erzeugung einer FirstSpirit Driven Page

Die Pflege redaktioneller Inhalte erfolgt sowohl in FirstSpirit als auch in der Commerce Cloud auf Basis einer Seite. Die Integration unterscheidet dabei zwischen Shop und FirstSpirit Driven Pages.

Im Gegensatz zu den Shop Driven Pages existieren die FirstSpirit Driven Pages ausschließlich in FirstSpirit und besitzen keine zugehörige Seite in der Commerce Cloud. Sie dienen der Erzeugung von Inhalts- oder Kampagnenseiten, die nicht zwingend im Standardumfang des Shops enthalten sind. FirstSpirit Driven Pages können entweder das Layout einer Shop Driven Page oder ein eigenes Layout verwenden, das in der Storefront definiert ist. In beiden Fällen erfolgt das Styling der FirstSpirit Driven Pages in Angular beispielsweise in der styles.scss-Datei der Storefront.

Für die Erzeugung einer neuen FirstSpirit Driven Page sind sowohl SAP- und Spartacus-seitig als auch in FirstSpirit einige Schritte durchzuführen, die nachfolgend beschrieben sind.

SAP- und Spartacus-seitige Konfiguration

Die Bridge erwartet ihrerseits neben verschiedenen CaaS-Angaben eine Definition der Seiten, deren Bearbeitung im ContentCreator möglich sein soll. Für FirstSpirit Driven Pages ist bei der Konfiguration zu berücksichtigen, ob die Seite das Layout einer Shop Driven Page oder ein eigenes Layout verwendet.

Im ersten Fall muss Commerce Cloud-seitig eine Dummy-Seite existieren, die bis auf das gewünschte Layout leer ist. Das heißt, dass sie beispielsweise lediglich einen allgemeinen Header und Footer einbindet, ansonsten jedoch keine Inhalte besitzt. Eine solche Seite ist für jedes Layout erforderlich, dass von FirstSpirit Driven Pages verwendbar sein soll.

Im zweiten Fall ist der FirstSpirit Driven Page keine Commerce Cloud-Seite und somit auch kein Layout einer solchen Seite zugeordnet. Die Storefront weiß daher nicht, welche Slots existieren und in welcher Reihenfolge diese auszugeben sind. Aus diesem Grund ist die layoutConfig-Konfiguration entsprechend zu erweitern.

FirstSpirit-seitige Konfiguration

Im Gegensatz zur Auslieferung der Inhalte erfolgt ihre Erstellung und Pflege im FirstSpirit ContentCreator. In diesem lassen sich mithilfe des Omnichannel Managers sowohl Shop als auch FirstSpirit Driven Pages darstellen und bearbeiten.

Die Erzeugung und Bearbeitung redaktioneller Inhalte setzt in FirstSpirit eine Seitenvorlage voraus, die gegebenenfalls anzulegen ist. Dabei ist sicherzustellen, dass die Inhaltsbereiche mit den in der Bridge konfigurierten Slots übereinstimmen: Für jeden definierten Slot muss die Seitenvorlage einen Inhaltsbereich mit demselben Namen besitzen. Andernfalls werden die redaktionellen Inhalte von der Storefront ignoriert und nicht im Live-Stand ausgegeben.

Darüber hinaus müssen alle Seitenvorlagen die Texteingabekomponenten pt_seoUrl und pt_cc_identifier besitzen. Die Eingabekomponente pt_seoUrl ermöglicht die Definition einer SEO-Url, während die Eingabekomponente pt_cc_identifier die Erreichbarkeit der Seite im ContentCreator sicherstellt.

Die Übertragung neuer oder veränderter Inhalte in den Online CaaS erfolgt mit jeder Freigabe. Der CaaS persistiert die Inhalte im JSON-Format in Form von Inhaltsfragmenten und macht sie für die Storefront verfügbar, die sie zusammen mit den Commerce Cloud-Inhalten in den Shop integriert.

5.4. Auswahl eines Produkts oder einer Kategorie

Das Modul stellt im ContentCreator einen Produkt- und einen Kategorie-Report bereit. Diese dienen der Darstellung der aus der Commerce Cloud stammenden Produkte und Kategorien. Über das Suchfeld der Reports können die Listen gefiltert werden.

Die CMS WebServices-Schnittstelle der Commerce Cloud ermöglicht keine Suche in einer anderen Sprache. Eine Suche nach Kategorien oder Produkten in den entsprechenden Reports muss daher mit Suchbegriffen in der Standardsprache der Commerce Cloud erfolgen.

5.5. Bearbeitung von Seitenattributen

Im Gegensatz zur Auslieferung der Inhalte verlagert sich deren Erstellung und Pflege von der Commerce Cloud nach FirstSpirit. FirstSpirit stellt dafür den ContentCreator zur Verfügung. In ihm lassen sich sowohl Shop als auch FirstSpirit Driven Pages darstellen und bearbeiten.

Die Pflege spezifischer Seitenattribute, wie beispielsweise einer SEO-URL, setzt für alle Seitentypen eine entsprechende FirstSpirit-Seitenvorlage voraus. Diese besitzt ein Formular aus verschiedenen Eingabekomponenten, die der Speicherung der Attribute dienen und im ContentCreator über den Bearbeitungsdialog der aktuell angezeigten Seite editierbar sind. Der Bearbeitungsdialog ist über den Eintrag Open page settings im Bereich zur Anzeige der Seiteninformationen aufrufbar, der sich beim Überfahren des Seitenstatus' mit dem Cursor öffnet.

Abbildung 14. Bearbeitung von Seitenattributen

5.6. Übersetzung redaktioneller Inhalte

FirstSpirit verfolgt konsequent das Konzept der Mehrsprachigkeit und erlaubt die Ausgabe unterschiedlicher Sprachvarianten. Die Übersetzung redaktioneller Inhalte in diese Sprachen erfolgt oft in Zusammenarbeit mit externen Übersetzungsagenturen oder mithilfe von Übersetzungsservices. Die Integration unterstützt daher TranslationStudio, welches den Export zu übersetzender Inhalte in ein Zielsystem sowie den anschließenden Import der Übersetzung in das FirstSpirit-Projekt ermöglicht.

Ist TranslationStudio im Projekt konfiguriert, stellt der ContentCreator verschiedene Arbeitsabläufe bereit. Diese sind über das Aktionen-Menü ausführbar und dienen der Durchführung folgender Aufgaben:

Übersetzung der aktuellen Seite oder einzelner Absätze auf dieser Seite
Übersetzung aller Seiten in einem spezifischen Ordner
Übersetzung mehrerer Seiten
Übersetzung der Datensätze einer Datenquelle

Jeder dieser Arbeitsabläufe öffnet einen Dialog, in dem verschiedene Einstellungen für die Übersetzung vorzunehmen sind. Diese unterscheiden sich in Abhängigkeit der zu übersetzenden Elemente und sind im Detail im TranslationStudio Editor Manual beschrieben. Ein Klick auf den Button Request Translation stößt den Export der zu übersetzten Inhalte in das definierte Zielsystem an. Sobald die Übersetzung abgeschlossen ist, importiert ein zuvor ausgewählter Arbeitsablauf die Inhalte automatisch in das FirstSpirit-Projekt und bindet sie an den richtigen Stellen ein.

Für die Übersetzung einzelner Seiten oder Absätze ist alternativ ein EasyEdit-Button verfügbar. Dieser zeigt zunächst ebenfalls den Konfigurationsdialog und öffnet anschließend den Dialog des sogenannten TranslationHelpers. Dieser stellt sowohl den Ausgangstext als auch dessen Übersetzung nebeneinander dar und ermöglicht bei Bedarf die sofortige Editierung.

5.7. Verwendung der Fallback-Sprache

Wie im vorhergehenden Kapitel beschrieben, verfolgt FirstSpirit konsequent das Konzept der Mehrsprachigkeit und erlaubt die Ausgabe unterschiedlicher Sprachvarianten. In dem durch die FirstSpirit Connect (Headless): For SAP Commerce Cloud-Integration geschaffenen Gesamtsystem übernimmt die Storefront die Auslieferung der Inhalte und bestimmt somit die Sprache, in der diese dargestellt werden. Aus diesem Grund müssen alle in der Storefront verfügbaren Sprachen im FirstSpirit-Projekt konfiguriert sein.

In einem mehrsprachigen Projekt sind jedoch in manchen Fällen nicht für alle Sprachen Inhalte verfügbar. Für diese Fälle ermöglicht die FirstSpirit Connect (Headless): For SAP Commerce Cloud-Integration optional die Definition einer Fallback-Sprache für nicht übersetzte Inhalte. Inhalte sind dadurch schnell und einfach präsentiertbar, ohne vollständig übersetzt zu sein. Darüber hinaus erlaubt die Fallback-Sprache die Überschreibung bereits bestehender Inhalte.

Für die Verwendung der Fallback-Sprache ist zunächst ihre Definition in der Bridge-Konfiguration erforderlich. Des Weiteren muss die verwendete Absatzvorlage die nachfolgend beschriebene Eingabekomponente st_languageFallbackEnabled und die ihr zugehörige Regel enthalten. Die Eingabekomponente entspricht einer Checkbox, mit der die Verwendung der Fallback-Sprache steuerbar ist. Durch ihre Aktivierung im Formular eines Absatzes werden dessen Inhalt und die Inhalte aller ihm untergeordneten Absätze durch den Inhalt der Fallback-Sprache ersetzt. Dies hat zur Folge, dass die Eingabekomponente im Fall von verschachtelten Absätzen nur im äußersten Absatz verfügbar ist. In den untergeordneten Absätzen wird sie durch die Regel ausgeblendet.

Der nachfolgende Code-Ausschnitt zeigt die Eingabekomponente st_languageFallbackEnabled. Ihre Aktivierung ermöglicht die Verwendung der Fallback-Sprache für den entsprechenden Absatz.

Eingabekomponente st_languageFallbackEnabled

<CMS_INPUT_TOGGLE name="st_languageFallbackEnabled" hFill="yes" preset="copy" singleLine="no" useLanguages="yes">
   <LANGINFOS>
      <LANGINFO lang="*" label="Enable language fallback"/>
      <LANGINFO lang="DE" label="Ersetzung für nicht gepflegte Sprache einschalten"/>
   </LANGINFOS>
</CMS_INPUT_TOGGLE>

Die im folgenden Code-Ausschnitt dargestellte Regel steuert die Sichtbarkeit der Eingabekomponente st_languageFallbackEnabled. Da diese im Fall verschachtelter Absätze nur im außenliegenden Absatz verwendbar ist, blendet die Regel sie in untergeordneten Absätzen aus.

dazugehörige Regel

<RULE>
   <WITH>
      <NOT>
         <EQUAL>
            <PROPERTYname="CONTAINERTYPE"source="#global"/>
            <TEXT>FS_CATALOG</TEXT>
         </EQUAL>
      </NOT>
   </WITH>
   <DO>
      <PROPERTY name="VISIBLE" source="st_languageFallbackEnabled"/>
   </DO>
</RULE>

5.8. Löschung von Seiten

Im Verlauf eines Projekts sind einige Seiten nur für eine bestimmte Zeit erforderlich. Sie werden danach nicht mehr benötigt und können aus dem Projekt entfernt werden. Das Referenzprojekt stellt zu diesem Zweck den Löscharbeitsablauf der BasicWorkflows zur Verfügung.

Dieser ermöglicht sowohl die Entfernung von Seiten als auch von Medien aus dem FirstSpirit-Projekt. Die Löschung lässt sich dabei entweder direkt oder anhand des Vier-Augen-Prinzips durchführen. Nach der Löschung des entsprechenden Elements gibt der Arbeitsablauf die übergeordnete Struktur frei. Die Änderungen werden somit direkt in den Preview und in den Online CaaS übertragen.

Die Ausführung des Lösch-Arbeitsablaufs erfordert sowohl das Lösch- als auch das Freigaberecht. Fehlt der ausführenden Person eines dieser Rechte, steht der Arbeitsablauf nicht zur Verfügung.

5.9. Server Side Rendering

Suchmaschinen steuern die Relevanz einzelner Webseiten über ein Ranking. Dieses ist ein Indikator für die Benutzerfreundlichkeit und Bedienbarkeit einer Seite und ist von unterschiedlichen Faktoren abhängig. Zu diesen Faktoren zählen unter anderem die Ladezeit und Übertragungsdauer. Im Rahmen der Suchmaschinenoptimierung (SEO = Search Engine Optimization) kann es daher förderlich sein, die Seite vor der Auslieferung bereits auf dem Server zu generieren. Dies minimiert die Last für den Client, beschleunigt den initialen Seitenaufruf und ermöglicht die Optimierung der Caching-Strategie.

Die Vorgenerierung einer Seite erfordert die Aktivierung des Server Side Renderings (SSR) auf dem Server. Im Fall eines Spartacus-Projekts sind dafür einige Schritte durchzuführen, die SAP in einem Guide zusammengefasst hat. Darüber hinaus hat SAP verschiedene SSR Coding Guidelines definiert, die für den Betrieb eines Servers im SSR-Modus zu berücksichtigen sind.

In Verbindung mit FirstSpirit ist zu beachten, dass die TPP-Snap-Implementierung nicht im SSR-Modus verwendbar ist. Dies führt dazu, dass bei dessen Aktivierung jeder Seitenaufruf in der Vorschau eine Vorgenerierung des gesamten Webauftritts auf dem Server anstößt. Um dies zu vermeiden, ist eine Exkludierung der Vorschau und damit des ContentCreators aus dem SSR-Modus sinnvoll.

Die Exkludierung des ContentCreators ist mithilfe einer Überprüfung des Referer Headers möglich: Enthält der Header eine ContentCreator-URL, muss die Generierung der angefragten Seite clientseitig ablaufen. Andernfalls erfolgt eine Vorgenerierung auf dem Server.

Für die Überprüfung des Referer Headers ist eine Anpassung der server.ts-Datei erforderlich, die im folgenden Code-Ausschnitt dargestellt ist:

Anpassung der server.ts-Datei

// All regular routes use the Universal engine
server.get('*', (req, res) => {
   // return CSR when opened on a preview URL
   if(req.header('referer')?.includes('<CONTENT_CREATOR_BASE_URL>')) {
      res.sendFile(distFolder + '/index.html');
   } else {
      res.render(indexHtml, {
         req,
         providers: [{ provide: APP_BASE_HREF, useValue: req.baseUrl }],
      });
   }
});

6. Rechtliche Hinweise

FirstSpirit Connect (Headless): For SAP Commerce Cloud ist ein Produkt der Crownpeak Technology GmbH, Dortmund, Germany.
Für die Verwendung des Moduls gilt nur die mit der Crownpeak Technology GmbH vereinbarte Lizenz.

7. Hilfe

Der Technical Support der Crownpeak Technology GmbH bietet qualifizierte technische Unterstützung zu allen Themen, die FirstSpirit™ als Produkt betreffen. Weitere Hilfe zu vielen relevanten Themen erhalten und finden Sie in auch in unserer Community.

Dokumentation

für die Version 24.9.0
Aktualisiert: 09.09.2024

Unternehmen

Kontakt

Crownpeak Technology GmbH
Stockholmer Allee 24
44269 Dortmund, DE
+49 231 477 77 0
Kontaktieren Sie uns