1. Einleitung

Ein Anwendungsfall für den FirstSpirit CaaS ist die Bereitstellung von Inhalten für Webseiten, die ihren Content aus mehreren unterschiedlichen Quellen beziehen. Das können beispielsweise Single-Page-Applications sein: Webseiten, die nur aus einer Seite (einem HTML-Dokument) bestehen und ihre Inhalte dynamisch nachladen. Diese Seiten basieren häufig auf einem Kachel- oder Card-Design, d.h. Inhalte zu unterschiedlichen Themen werden in bestimmten Inhaltsbereichen (Slots) neben- oder untereinander auf einer Webseite dargestellt. Das können beispielsweise Teaser, Produktbilder oder Videos sein, die ggf. zu Detailseiten führen. Ebenso gut können die Inhalte aber auch klassisch auf mehreren Webseiten verteilt sein.

Um solche Inhalte, die nicht direkt aus FirstSpirit heraus generiert werden, sondern aus externen Anwendungen ("Apps") stammen, trotzdem in FirstSpirit darstellen und nutzen zu können, kann der Omnichannel Manager (TPP) verwendet werden. Dabei werden die Inhalte der externen App im FirstSpirit ContentCreator dargestellt. Inhalt, der in FirstSpirit gepflegt wird (redaktioneller Content), kann dort ebenfalls dargestellt und auch bearbeitet werden.

Anders als bei klassischen FirstSpirit-Projekten können (je nach Projektdesign) auch einzelne FirstSpirit-Inhalte unabhängig voneinander (von unterschiedlichen Redakteuren) bearbeitet und freigegeben werden, obwohl sie auf einer (HTML-)Seite dargestellt werden. Das bedeutet, mehrere Redakteure können dann beispielsweise parallel die zentrale Homepage eines Online-Shops bearbeiten und einzelne Elemente unabhängig voneinander veröffentlichen.

Vorteile:

  • Darstellung und Bearbeitung von Inhalten aus mehreren, unterschiedlichen Quellen (unter anderem dem FirstSpirit CaaS)

  • Dynamisches, partielles Nachladen von Bereichen, in denen sich Inhalte geändert haben, statt Page-Reload für bessere Performance

  • Paralleles Bearbeiten von Content-Bereichen einer (HTML-)Seite

Die Funktionalität wird per FirstSpirit-Modul zur Verfügung gestellt: fs-tpp-[Version].fsm.

2. Architektur

Die TPP-Funktionalität wird per Modul zur Verfügung gestellt. Darüber hinaus sind Konfigurationen im FirstSpirit ServerManager sowie im FirstSpirit-Projekt und in der externen App erforderlich (siehe dazu Kapitel Modulinstallation).

Eine typische Architektur umfasst folgende Komponenten:

  • FirstSpirit-Server mit FirstSpirit-Projekt (TPP)

  • FirstSpirit CaaS

  • externe App

image9
Abbildung 1. Architektur

Der Austausch der Daten zwischen den Komponenten erfolgt im JSON-Format. Dieses Format kann von den meisten externen Apps verarbeitet werden.

Externe App ↔ FirstSpirit-Projekt

Mithilfe der TPP-Funktionalität wird der Inhalt der gewünschten externen App im FirstSpirit ContentCreator (in einem iFrame) dargestellt. Die Cross-Domain-Kommunikation wird dabei mithilfe von postMessage realisiert.

FirstSpirit-Projekt ↔ FirstSpirit CaaS

Die Inhalte werden zwischen dem FirstSpirit-Projekt und dem FirstSpirit CaaS in Form von JSON-Objekten ausgetauscht. Dazu muss die Definition der Inhalte in einem entsprechenden (CaaS-)Ausgabekanal erfolgen. Das JSON-Attribut previewId dient dabei zur Identifikation von FirstSpirit-Elementen. Dieses Attribut wird bei den meisten API-Funktionen als Parameter erwartet. Nach dem Bearbeiten der FirstSpirit-Inhalte werden diese Änderungen automatisch von FirstSpirit in den CaaS übertragen.

FirstSpirit CaaS ↔ Externe App

Auf die JSON-Daten, die zuvor aus dem FirstSpirit-Projekt an den FirstSpirit CaaS übertragen wurden, kann wiederum die externe App zugreifen, und zwar via HTTP GET-Request.

Ein exemplarischer Ablauf innerhalb der App kann dann beispielsweise wie folgt aussehen:

  1. Über REST-Calls an den CaaS werden Inhalte im JSON-Format angefragt.

  2. Die Inhalte werden in HTML-Elemente umgewandelt.

  3. Das Attribut _id für Objekte auf oberster Ebene (Seitenreferenzen, Datensätze, Medien) bzw. identifier für innere Objekte (z. B. die Seite und die Absätze von Seitenreferenzen) aus dem JSON wird in das HTML-Attribut data-preview-id überführt.

  4. Die HTML-Elemente werden an den dafür vorgesehenen Stellen in die dargestellte Seite eingefügt.

  5. Die Front-End Library (snap.js) dekoriert das Element bei mouse-over mit den Editier-Operationen.

  6. Klickt nun der Redakteur auf das Icon Bearbeiten, wird von der TPP-API der Bearbeitungsdialog geöffnet.

  7. Bestätigt der Redakteur seine Änderungen, wird ein Event mit dem aktualisierten JSON als Payload gefeuert. Mit diesen Daten müssen die Schritte 2 bis 5 erneut durchlaufen werden, um die dargestellten Inhalte zu aktualisieren.

3. Technische Anforderungen

3.1. FirstSpirit-Server

Der Einsatz der Funktionalität Omnichannel Manager erfordert einen FirstSpirit-Server mit einer Version ab 5.2R16 und Java 8.

3.2. Externe App

Folgende Anforderungen muss die externe App erfüllen, damit sie erfolgreich mit der Omnichannel Manager verwendet werden kann:

  • Die App muss in einem iFrame laufen dürfen (siehe MDN/X-Frame-Options).

  • Protokolle für den ContentCreator und die externe App:
    Stimmt das Protokoll des ContentCreators und der externen App nicht überein (http:‌//…, https:‌//…), führt dies zu einer Warnmeldung auf der JavaScript-Konsole. Diese kann ignoriert werden. Um die Warnmeldung zu unterbinden, sollte die externe App unter demselben Protokoll betrieben werden wie der ContentCreator. Alternativ können auch absolute Links verwendet werden, die mit // beginnen, statt mit http[s]://.

3.3. FirstSpirit CaaS

Innerhalb des Omnichannel Manager-Kontextes besteht die Aufgabe des FirstSpirit CaaS in der Bereitstellung nicht freigegebener Inhalte für die externe App. Dafür muss dem verwendeten Projekt eine Projekt-Komponente des CaaS-Moduls hinzugefügt und konfiguriert werden. Des Weiteren ist die Erzeugung einer weiteren CaaS-Instanz auf einem zweiten Host erforderlich. Die dafür notwendigen Schritte sind in der Dokumentation für Content as a Service beschrieben.

4. Modulinstallation

Das Modul muss mithilfe der mitgelieferten fs-ttp-[version].fsm-Datei auf dem FirstSpirit-Server hinzugefügt werden. Öffnen Sie dafür den ServerManager und wählen Sie den Bereich Server-Eigenschaften  Module.

ServerManager_Module_initia.png
Abbildung 2. Module

Im Hauptpanel ist eine Liste aller auf dem FirstSpirit-Server installierten Module zu sehen. Wählen Sie nach dem Klicken auf Installieren die fs-ttp-[version].fsm-Datei aus und bestätigen Sie die Auswahl mit Öffnen.

Nach der erfolgreichen Installation wurde der Liste der Ordner FirstSpirit ThirdPartyPreview hinzugefügt.

Er enthält folgende Komponenten:

  • FirstSpirit ThirdPartyPreview WebApp

  • TppApi

  • TppClientResourcePlugin

ServerManager_Module.png
Abbildung 3. Komponenten des TPP-Moduls

Die Komponente FirstSpirit ThirdPartyPreview WebApp muss als Web-Applikation für den ContentCreator aktiviert werden, entweder für alle Projekte des FirstSpirit-Servers (Server-Eigenschaften  Web-Applikationen):

ServerManager_Web-Applikati.png
Abbildung 4. Server-Eigenschaften

oder für einzelne Projekte (Projekteigenschaften  Web-Komponenten):

ServerManager_project_webApplication.png
Abbildung 5. Projekteigenschaften

Weitere Informationen zur Installation von Modulen und Konfiguration von Web-Applikationen bzw. Web-Komponenten finden Sie in der FirstSpirit Dokumentation für Administratoren, Seiten Module, Web-Applikationen und Web-Komponenten.

5. FirstSpirit-seitige Konfiguration

5.1. Konfiguration der Vorschau-URL

Die URL der externen Web-Applikation, die für die Vorschau in FirstSpirit genutzt werden soll, wird in das Textfeld Externe Vorschau-URL im Bereich FirstSpirit ServerManager  Projekteigenschaften  ContentCreator eingetragen:

SM_FAPS_PreviewURL.png
Abbildung 6. Konfiguration der Vorschau-URL

Die Vorschauanwendung kann dann im ContentCreator verwendet werden. Wenn die verlinkte Anwendung entsprechend vorbereitet ist, sind die im Vorschaubereich dargestellten Inhalte für den Redakteur dann mit den Funktionen des ContentCreators bearbeitbar und er kann Inhalte anlegen und löschen (zu Einschränkungen siehe Kapitel Editier-Oberfläche (ContentCreator)).

Die hier angegebene URL muss auch das Protokoll der externen Web-Applikation enthalten.

Ist das Textfeld leer (URL vergeben: http:‌//…), wird die interne Vorschau des ContentCreators verwendet.

Weitere Informationen finden Sie in der FirstSpirit Dokumentation für Administratoren.

5.2. Vorlagen-Code

Zur Identifikation eines FirstSpirit-Elements in einer bestimmten Projektsprache wird die Funktion previewId() verwendet. Sie dient der Kommunikation zwischen der Single-Page-Application und dem FirstSpirit ContentCreator.

Beispiel 
$CMS_VALUE(previewId())$

Der Funktion kann der optionale Parameter element mitgegeben werden. Mithilfe dieses Parameters kann ein FirstSpirit-Objekt (vom Typ IDProvider) übergeben werden, z. B. eine globale Seite aus den Globalen Inhalten (GCA) (#global.gca("…​")) oder die aktuelle Seite (#global.page).

Beispiel 
$CMS_VALUE(previewId(element:#global.page))$

Vgl. dazu auch die Funktion editorId(), in der FirstSpirit Online Dokumentation.

Die Funktion muss in den gewünschten Ausgabekanal der betreffenden Vorlage eingefügt werden. In der App kann dann per API auf diese ID zugegriffen werden (siehe Kapitel Konfiguration der Applikation).

Beispiel für JSON 
{
   "previewId": "$CMS_VALUE(previewId())$",
   "highlight": $CMS_VALUE(pt_highlight)$,
   "headline": "$CMS_VALUE(pt_headline)$,
   "Text": "$CMS_VALUE(pt_text.toString.toJSON)$"
}

Die Funktion previewId() liefert Informationen nur bis auf die Ebene von Absätzen zurück. Card-Objekte, die von FS_CATALOG zurückgeliefert werden, erhalten beispielsweise keine entsprechenden Informationen.

5.3. Arbeitsabläufe

Im TPP-Modus können prinzipiell Arbeitsabläufe verwendet werden. Mithilfe eines Freigabe-Arbeitsablaufs können so beispielsweise neue Inhalte und Änderungen an bestehenden Inhalten freigegeben werden, so dass sie in einer nächsten Veröffentlichung berücksichtigt werden. Zu Informationen zum Entwickeln und Konfigurieren von Arbeitsabläufen in FirstSpirit siehe FirstSpirit Online Dokumentation.

Um Inhalte in TPP löschen zu können, muss ein geeigneter Lösch-Arbeitsablauf im Projekt vorhanden sein. Das kann der von Crownpeak entwickelte Arbeitsablauf Löschen sein (enthalten in den BasicWorkflows, basicworkflows.fsm, erhältlich über den FirstSpirit Technical Support).

Damit dieser bei Betätigung des Löschen-Icons im ContentCreator deleteicon.png verwendet wird, muss er in den Projekteigenschaften (FirstSpirit ServerManager  Projekteigenschaften  Optionen) unter Arbeitsablauf zum Löschen von Elementen ausgewählt werden. Zu weiteren Informationen siehe auch FirstSpirit Dokumentation für Administratoren.

Darüber hinaus können auch kundenspezifische Arbeitsabläufe eingesetzt werden.

Arbeitsabläufe können sich in FirstSpirit nur auf Seiten der Struktur-Verwaltung oder Seiten der Inhalte-Verwaltung beziehen. Siehe dazu auch FirstSpirit Dokumentation für Administratoren.

5.4. Kundenspezifische Aktionen/Skripte/Plugins

Die Menge der externen Anwendungen, die mit FirstSpirit TPP verwendet werden können, ist breit gefächert, die verarbeiteten Daten und ihre Bearbeitungsmöglichkeiten sind vielfältig.

Standardmäßig werden einige Aktionen (z. B. Seite anlegen und bearbeiten, Medien hochladen und verwalten) von TPP angeboten. Darüber hinausgehende spezifische Aktionen, die eine externe Anwendung bietet und die in FirstSpirit abgebildet werden sollen, können über projektspezifische Skripte und Plugins umgesetzt werden.

Um den Redakteur oder andere Benutzer bestmöglich in seiner Arbeit unterstützen zu können, kann dazu in der Regel auch die Begrifflichkeit der externen Anwendung übernommen werden. Beispielsweise kann ein Skript zum Anlegen je nach Kontext/Framework dann heißen:

  • Seiten anlegen

  • Inhalt anlegen

  • Kampagne generieren

Zur Entwicklung von Skripten und Plugins siehe FirstSpirit Online Dokumentation, Kapitel Scripting und Plugin-Entwicklung.

5.5. Medien

Einen Spezialfall bei der Anforderung von Daten aus dem FirstSpirit CaaS stellen Medien dar: Um ein Medium aus dem CaaS in Form von Binärdaten zu erhalten, muss der URL, die vom CaaS zurückgeliefert wird, der Ausdruck /binary angehängt werden. In der HTML-Vorlage, die die zugehörige Vorschau in FirstSpirit rendert, wird diese URL dann in das img-Tag als src-Attribut eingefügt, z. B.

<img src='http://Servername:Port/Projectname/assets.files/ImageId/binary'>

Das funktioniert allerdings nur, wenn ein CaaS-Proxy verwendet wird. Der Proxy muss so konfiguriert sein, dass er die Anfragen an den CaaS weiterleitet und zusätzlich den API-Key an den Request Header hängt. Der Header muss dazu wie folgt aussehen:

Authorization:apikey="{apikey}"

Eine minimale Beispielimplementierung in node.js befindet sich auf GitHub.

Zu weiteren Informationen über die Verwendung von Medien mit dem CaaS finden Sie in der CaaS-Dokumentation.

6. Konfiguration der Applikation

Standardmäßig können Inhalte aus kundenspezifischen Apps nach den Schritten, die in den Kapiteln Modulinstallation und FirstSpirit-seitige Konfiguration beschrieben sind, im FirstSpirit ContentCreator mithilfe der Funktionalität Omnichannel Manager bereits dargestellt werden. Damit die App die Funktionalitäten des ContentCreators ansprechen kann, um die Inhalte auch bearbeiten zu können, sind Anpassungen am Code der App erforderlich. Dazu muss eine spezielle API verwendet werden (s.u.). Über diese API wird dem Redakteur die Pflege der in der App bereitgestellten Inhalte ermöglicht:

  • Anlegen von Inhalten

  • Ändern von Inhalten

  • Entfernen von Inhalten

  • Arbeitsabläufe starten und weiterschalten

Die API stellt im Kontext der Applikation die Funktionen über Editiericons bereit. Zur Anzeige des Bereichs, auf den sich die Funktionen beziehen, wird auch ein Rahmen um das jeweilige HTML-Element gezeichnet (beim mouseOver). Die Funktionen können einfach projektspezifisch erweitert werden.

editiericons.png
Abbildung 7. Beispiel für Editiericons

Weitere Funktionen werden über die Menüs des ContentCreator bereitgestellt.

6.1. API

Um die TPP-API in einer kundenspezifischen App nutzen zu können, muss im Frontend-Code eine JavaScript-Datei eingebunden werden. Diese Datei ist ein Bestandteil des ausgelieferten Moduls (zip-Format). Sie kann darüber hinaus über NPM eingebunden werden: https://www.npmjs.com/package/fs-tpp-api

Eine Dokumentation der API mit einer Beschreibung zur Einbindung sowie Code-Beispielen findet sich unter https://docs.e-spirit.com/tpp/snap.

Die mitgelieferte Demo-Anwendung (snap-shop) zeigt exemplarisch die Verwendung der API anhand der gängigsten Use-Cases.

7. Editier-Oberfläche (ContentCreator)

Zum Bearbeiten von Inhalten wird der FirstSpirit ContentCreator verwendet. Eine Dokumentation für Redakteure befindet sich im FirstSpirit Handbuch für Redakteure (ContentCreator) unter https://docs.e-spirit.com/odfs/documentation/editors und ist direkt aus dem ContentCreator erreichbar über den (?)-Knopf.

7.1. Einschränkungen

Inhalte aus externen Quellen können von FirstSpirit nur begrenzt kontrolliert und gesteuert werden. Aufgrund dieser technischen Gegebenheit sind einige Funktionen des ContentCreator bei einer Verwendung mit der Omnichannel Manager standardmäßig nicht möglich. Dies betrifft u.a. Drag-and-drop von Dateien vom Desktop in die Anwendung.

Menü-Schaltflächen und Icons, deren Funktionalität im TPP-Modus nicht zur Verfügung stehen, sind ausgeblendet. Fehlende Funktionalität kann über kundenspezifische Implementierung realisiert werden (siehe auch Kapitel Kundenspezifische Aktionen/Skripte/Plugins). Zu den Möglichkeiten und zu konkreten Beispielen siehe auch FirstSpirit Online Dokumentation

8. Release-Notes

Zu jeder Veröffentlichung einer neuen Version von TPP gibt es Versionshinweise mit Informationen zu den enthaltenen Änderungen.

9. Glossar

Begriff Bedeutung

EAP

Early Access Program

Softwareversion mit noch nicht freigegebenen Änderungen (Features und Bugfixes). EAP-Versionen genügen den selben Stabilitätskriterien wie freigegebene Versionen, in seltenen Fällen kann es aber bis zur Freigabe noch zu Änderungen an den bisher noch nicht freigegebenen Funktionen kommen.

SPA

Single Page Application

Eine SPA zeichnet sich dadurch aus, dass diese ohne Seiten-Reloads auskommt, was durch den Einsatz von JavaScript realisiert wird.

NPM

Node Package Manager

Ein Paketmanager für die JavaScript-Laufzeitumgebung Node.js, über den auch die Frontend-API der Omnichannel Manager bereitgestellt wird.

10. Rechtliche Hinweise

Das Omnichannel Manager-Modul ist ein Produkt der Crownpeak Technology GmbH, Dortmund, Germany.

Für die Verwendung des Moduls gilt gegenüber dem Anwender nur die mit der Crownpeak Technology GmbH vereinbarte Lizenz.

Details zu möglicherweise fremden, nicht von der Crownpeak Technology GmbH hergestellten, eingesetzten Software-Produkten, deren eigenen Lizenzen und gegebenenfalls Aktualisierungs-Informationen, finden Sie in der Datei THIRD-PARTY.txt, die mit dem Modul ausgeliefert wird.

11. 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.