1. Einleitung

FirstSpirit bietet für statisch generierte Seiten eine eigene, vorlagenbasierte Navigationsfunktion. In der modernen Headless-Welt bedarf es einer anderen Lösung, bei der eine dynamische Zuordnung zwischen einer Navigationsroute und dem entsprechenden Inhalt dahinter nahtlos integrierbar ist.

Das Navigation Service-Modul ermöglicht einen Weg, den Aufbau der FirstSpirit-Strukturverwaltung eines Projekts in ein JSON-Format zu überführen und über den Navigation Service-Endpunkt zur Verfügung zu stellen. Gemäß der Dokumentation des Navigation Service-Endpunkts kann die Struktur daraufhin über eine REST-Schnittstelle abgefragt werden.

1.1. Architektur

Die Funktionalitäten des Navigation Services werden über eine Architektur verschiedener Komponenten realisiert (vgl. Abbildung Architektur).

Bei diesen Komponenten handelt es sich um:

  • Navigation Service

  • Navigation Service-Modul

architecture
Abbildung 1. Architektur

Das Zusammenspiel der Komponenten erfolgt immer nach dem folgenden Schema:

  • Die Erstellung sowie die Aktualisierung navigationsrelevanter Inhalte finden FirstSpirit-seitig statt. Änderungen an der Struktur werden dem Navigation Service-Endpunkt (vgl. REST API) im Rahmen einer Aktualisierung bereitgestellt. Dafür erzeugt der FirstSpirit-Server eine Verbindung zu diesem und überträgt alle relevanten Daten.

  • Der Navigation Service empfängt diese Daten und aktualisiert anhand der in ihnen enthaltenen Informationen sein internes Datenmodell.

  • Die Endanwendung des Kunden fordert die gespeicherten Informationen nach Bedarf vom Navigation Service-Endpunkt an, der dafür eine REST API bereitstellt. Die Abfrage der Daten erfolgt somit nach dem pull- und nicht nach dem push-Prinzip.

Die Kommunikation zwischen dem FirstSpirit-Server und dem Navigation Service erfolgt standarmäßig per HTTPS.

2. Komponenten

Der Einsatz des Navigation Services in einer bestehenden FirstSpirit-Projektinfrastruktur erfordert zwei zusätzliche Komponenten.

Mit der Verwendung des Navigation Service-Moduls wurden ein FirstSpirit-Service mit dem Namen Navigation Client Service sowie eine Projekt-Komponente namens Navigation Project Configuration auf dem FirstSpirit-Server bereitgestellt.

Navigation Client Service

Bei der Installation des Navigation Service-Moduls wird der Navigation Client Service dem FirstSpirit-Server hinzugefügt und aktiviert. Für eine Übertragung an den Navigation Service-Endpunkt muss die Projekt-Komponente dem jeweiligen Projekt hinzugefügt werden. Der Navigation Client Service sorgt anschließend für die Erzeugung der Navigationen der FirstSpirit-Projekte.

Der Navigation Client Service muss gestartet sein, damit der Einsatz des Navigation Services funktioniert.

Navigation Project Configuration

Über das Hinzufügen der Projekt-Komponente Navigation Project Configuration zu einem FirstSpirit-Projekt wird gesteuert, ob Navigationen für dieses erzeugt werden. Diese besitzt eine eigene Konfiguration, die im Kapitel Konfiguration der Navigation Service Projekt-Komponente beschreiben ist.

3. Konfiguration

Die Einrichtung des Navigation Services für den Betrieb auf einem FirstSpirit-Server erfolgt über die Konfiguration der Projekt-Komponente: Navigation Project Configuration.

Die nachfolgenden Unterkapitel beschreiben die erforderlichen Konfigurationsschritte.

3.1. Konfiguration der Navigation Service Projekt-Komponente

Mit der Verwendung des Navigation Service-Moduls wird dem FirstSpirit-Server die Projekt-Komponente Navigation Project Configuration zur Verfügung gestellt.

Über das Hinzufügen dieser Projekt-Komponente zu einem Projekt, wird dieses aktiviert und es werden somit Navigationen erzeugt.

Durch das Hinzufügen der Navigation Project Configuration zu einem FirstSpirit Projekt, wird eine initiale Erzeugung der Navigationsstruktur ausgelöst.

Beim Entfernen der Navigation Project Configuration werden die erstellten Navigationen im Navigation Service gelöscht.

Öffnen Sie für das Hinzufügen der Projekt-Komponente den ServerManager und selektieren Sie den Bereich Projekt-Eigenschaften  Projekt-Komponenten.

Im Hauptpanel ist eine Liste aller bereits vorhandenen Projekt-Komponenten zu sehen. Wählen Sie nach dem Klicken auf Hinzufügen die Navigation Project Configuration und bestätigen Sie die Auswahl mit OK.

projectcomponents add
Abbildung 2. Hinzufügen der Projekt-Komponente: Navigation Project Configuration

Die Projekt-Komponente wird der Liste im Hauptpanel hinzugefügt und muss anschließend noch konfiguriert werden (vgl. Abbildung Hinzufügen der Projekt-Komponente: Navigation Project Configuration).

Selektieren Sie dafür den Eintrag in der Liste und öffnen Sie den zugehörigen Konfigurationsdialog über Konfigurieren.

Die Felder sind wie nachfolgend beschrieben zu befüllen.

projectcomponents config
Abbildung 3. Navigation Service - Konfiguration
CaaS 3.x Modus

Dieses Modus steht zur Auswahl, falls auf dem FirstSpirit-Server das Content as a Service-Modul in einer Version gleich oder größer als 3 installiert ist. Ist der CaaS 3.x Modus aktiviert, so werden in der Navigation für die Referenzierung der Daten die korrekten CaaS-Routen benutzt. Außerdem wird die Advanced URLs UrlFactory für die SEO Routen verwendet.

Content Reference URL Prefix

In diesem Feld kann optional ein Präfix eingetragen werden. Der Wert wird den erzeugten ContentReference URLs jeder FirstSpirit-Seitenreferenz vorangestellt.

Content Reference URL Factory

An dieser Stelle ist die URL Factory auszuwählen, welche für die Erzeugung der Pfade zu den referenzierten Inhalten zuständig ist. Dieses Auswahlfeld ist deaktiviert, sobald der CaaS 3.x Modus eingeschaltet worden ist.

SEO Route Url Factory

An dieser Stelle ist die URL Factory auszuwählen, welche für die Erzeugung der SEO Routen zuständig ist. Dieses Auswahlfeld ist deaktiviert, sobald der CaaS 3.x Modus eingeschaltet worden ist.

Navigation URL (Release und Preview)

Die aufgelisteten Navigation URLs zeigen an, an welche Stellen die für das Projekt erzeugten Navigationen übermittelt werden. Dies sind die Endpunkte für die Front-End entwickelnde Personen, welche von e-Spirit bereit gestellt werden.

Verfügbar in Sprachen

Hierbei handelt es sich um eine Auflistung aller Sprachen des aktuellen FirstSpirit-Projekts, für die jeweils eine Navigation bereitgestellt wird.

Fehler ignorieren

Dieser Modus ist nicht empfohlen und per Default in allen Projekten deaktiviert. Falls er aktiviert ist, werden Fehler bei der Generierung der Navigation ignoriert. Stattdessen werden an den betroffenen Stellen null Werte geschrieben. Sie verlieren dadurch die Gewissheit, dass Daten im Navigation Service stets korrekt sind.

Permissions

Hier kann konfiguriert werden, ob Permissions Informationen Teil der Navigation sein sollen. Der Input Name definiert den Namen der CMS_INPUT_PERMISSION Eingabekomponente. Nur wenn dieser Wert gesetzt ist werden Permissions in die Navigation geschrieben. Der Activity name gibt an, welche Menge von Permissions genutzt werden soll.

4. Verwendung

Das Navigation Service-Modul stellt die Möglichkeit bereit, den Aufbau der Strukturverwaltung eines FirstSpirit-Projekts über den Navigation Service-Endpunkt zur Verfügung zu stellen.

Die nachfolgenden Unterkapitel beschreiben, wie sich einer solchen Navigation weitere Informationen hinzufügen lassen und wie ihre anschließende Erzeugung erfolgt.

4.1. Erzeugung der Navigation

Die Navigationen für den Vorschau- sowie den Freigabe-Stand werden bei jeder Änderung bzw. Freigabe einer Seitenreferenz, Strukturordner, sowie jedem Root-Knoten der Strukturverwaltung aktualisiert. Zusätzlich wird eine Aktualisierung des Vorschau-Standes der Navigastionsstruktur durch Änderungen an Seiten angestoßen. Auf eine Seite muss dabei von mindestens einer Seitenreferenz verwiesen werden.

Bei Änderungen in den globalen URL Einstellungen des Projekts werden sowohl der Vorschau als auch der Freigabestand aktualisiert.

Die Navigationen werden jeweils pro Sprache des Projekts sowie pro Releasestand erzeugt.

Navigationen, die zu einer Sprache gehören, die nicht Teil des Projekts ist, werden täglich im Rahmen einer durch eine Änderung ausgelösten Aktualisierung gelöscht.

4.1.1. Robustheit

Das Aktualisieren der Navigation kann aus verschiedenen Gründen fehlschlagen. Die Ausführung des Vorgangs wird daher über einen Tag lang mehrfach erneut probiert.

4.1.2. Aufträge

Es ist zusätzlich möglich die Generierung der Navigation durch einen FirstSpirit Auftrag anzustoßen. Beim Installieren der Projekt-App werden hierfür zwei Aufträge zum Projekt hinzugefügt: Navigation Live Generation und Navigation Preview Generation. Diese bestehen aus jeweils zwei Aktionen, welche die aktuellen Navigationen in allen Sprachen an den Navigation Service übermitteln und existierende Navigationen, zu denen keine korrespondierende Sprache im Projekt vorhanden ist, löschen.

Das NavigationInspectionExecutable kann genutzt werden um zur Generierungszeit den Navigationsbaum für ein konkretes Element zu berechnen. Es erwartet folgende Parameter:

Name Typ Beschreibung

element

de.espirit.firstspirit.access.store.IDProvider

Das FirstSpirit-Element (Seitenreferenz, Strukturordner oder Root-Knoten der Strukturverwaltung), für das die Navigation berechnet werden soll.

language

de.espirit.firstspirit.access.Language

Das FirstSpirit-Sprachobjekt, für das die Navigation berechnet werden soll.

key (optional)

String

Das Attribut, welches als Ergebnisobjekt zurückgeliefert werden soll. Ohne Angabe wird das gesamte Navigationselement zurück gegeben.

Rückgabewert ist ein JSON-Objekt, über die Methode .toString() erhält man das serialisierte JSON des Objektes. Falls der key Parameter angegeben wurde und das spezifizierte Attribut einen primitiven Typ hat, so wird immer direkt ein String zurück gegeben.

4.2. Custom Data

Falls die Navigationsdaten im generierten Standardformat nicht ausreichend sind, besteht die Möglichkeit, der Navigation weitere Informationen hinzuzufügen. Das Navigation Service-Modul stellt dafür das sogenannte Custom Data Script bereit. Es ermöglicht selbst definierte Inhalte mit an den Navigation Service-Endpunkt zu übermitteln.

Ein Anwendungsfall hierfür ist beispielweise eine Seitenbeschreibung, die zusätzlich neben den Navigationsinformationen zur Darstellung benötigt wird.

Das folgende Kapitel beschreibt die Einrichtung von genau diesem Anwendungsfall.

4.2.1. Einrichtung eines Custom Data Scripts

Öffnen Sie den SiteArchitect und fügen Sie ein Skript zu Ihrem Projekt mit folgendem Referenznamen hinzu: navigation_service_custom_data.

Innerhalb des Skripts schreiben Sie Ihren Code in den ersten Ausgabekanal.

Beispielimplementierung eines Custom Data Scripts
import de.espirit.firstspirit.access.store.pagestore.Page;
import de.espirit.firstspirit.access.store.sitestore.PageRef;

if (e instanceof PageRef) {
    page = e.getPage();
    formData = page.getFormData();
    pageDescription = formData.get(language, "pt_pageDescription").get();
    customData.put("pageDescription", pageDescription);
}

Das CustomData Script wird direkt nach der Erstellung bei jeder folgenden Änderung am FirstSpirit-Projekt sowie der Freigabe mit ausgewertet.

Das hierbei erzeugte JSON einer beispielhaften FirstSpirit-Seitenreferenz
{
    "id": "815c307c-2ca6-4f02-9653-fa3454988fc2",
    "label": "Produkte",
    "seoRoute": "/Produkte/Produkte.html",
    "seoRouteRegex": null,
    "contentReference": "/beispielPrefix/Produkte/Produkte.html",
    "customData": {
        "pageDescription": "Unser Produktangebot"
    },
    "_links": {
        "self": {
            "href": "https://navigation-example.e-spirit.live/navigation/preview.7c5c1555-c706-45a7-8371-ccddbb4ba8be/node/815c307c-2ca6-4f02-9653-fa3454988fc2?depth=10&language=de_DE"
        },
        "path": {
            "href": "https://navigation-example.e-spirit.live/navigation/preview.7c5c1555-c706-45a7-8371-ccddbb4ba8be/node/815c307c-2ca6-4f02-9653-fa3454988fc2/path?depth=10&language=de_DE"
        },
        "seoRoute": {
            "href": "https://navigation-example.e-spirit.live/navigation/preview.7c5c1555-c706-45a7-8371-ccddbb4ba8be/by-seo-route/Produkte/Produkte.html?depth=10&language=de_DE"
        }
    },
    "visible": false,
    "permissions": {
        "allowed": ["customer", "admin"],
        "forbidden": ["anonym"]
    },
    "children": null,
    "hasChildren": false
}

Alle Informationen zur Nutzung sowie zum Format der erzeugten Navigationsstruktur finden Sie in der Dokumentation des Navigation Service-Endpunkt.

Neben dem bereits erwähnten IDProvider stehen dem Skript im Kontext der Ausführung weitere Felder zur Verfügung:

Name Typ Beschreibung

e

de.espirit.firstspirit.access.store.IDProvider

Das aktuelle FirstSpirit-Element (Seitenreferenz, Strukturordner oder Root-Knoten der Strukturverwaltung).

context

de.espirit.firstspirit.access.BaseContext

Hierbei handelt es sich um einen FirstSpirit-SpecialistBroker.

language

de.espirit.firstspirit.access.Language

Das FirstSpirit-Sprachobjekt zur Laufzeit.

customData

Map<String, Object>

Einträge in dieser Map werden in die Custom Data geschrieben und anschließend über den Navigation Service-Endpunkt bereitgestellt.

Bitte beachten Sie, dass die maximale Größe der customData-Map auf fünf Einträge begrenzt ist.

Die Werte müssen äquivalent zu JsonPrimitiven sein (z.B. String, Number oder Boolean).

Falls Sie einen Anwendungsfall haben, welcher durch die oben erwähnten Felder nicht abgedeckt werden kann, kontaktieren sie bitte den e-Spirit Support.

4.3. Contentprojektionen

Im Fall einer Contentprojektion für Detailansichten enthalten die zugehörigen Navigationsknoten ein Attribut, das zur Auflösung dynamischer Routen genutzt werden kann. Eine Contentprojektion gilt als Projektion für Detailansichten, sofern folgende Eigenschaften im Daten-Reiter einer Seitenreferenz konfiguriert sind:

  • Die Anzahl der Einträge pro Seite ist größer als 0 (z.B. 1)

  • Die Maximale Seitenanzahl beträgt nicht 1 (z.B. 0)