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
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 .
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.
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.
- SEO Route Url Factory
-
An dieser Stelle ist die URL Factory auszuwählen, welche für die Erzeugung der SEO Routen zuständig ist. Der Standardwert ist "get from CaaS Connect (recommended)" und setzt die SEO Routen auf denselben Wert, wie er in der Projektkomponente des Content as a Service-Moduls konfiguriert ist. Details zur Konfiguration der Projektkomponente des Content as a Service-Moduls finden Sie hier.
|
Auf Anfrage können Vorschaunavigationen so konfiguriert werden, dass neue URLs immer von der UrlFactory erzeugt werden. Bereits vorhandene stored custom URLs werden dann nicht in Vorschaunavigationen verwendet! Dies ist ein experimentelles Feature. |
- Content Reference Url Factory
-
Content Reference Url Factorys können nicht mehr konfiguriert werden. Stattdessen wird immer die CaaS Connect UrlFactory für diesen Zweck verwendet. Bereits konfigurierte alternative URL-Factorys aus früheren Modulversionen werden so lange weiterverwendet, bis ein Benutzer die Projekt-App-Komponente öffnet, die Option "get from CaaS Connect (recommended)" auswählt und die Konfiguration speichert.
- 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 Crownpeak Technology 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.
| Wenn gespeicherte URLs eines Elements zurückgesetzt werden, kann es vorkommen, dass durch die Aktualisierung der Navigation im Freigabestand sofort neue URLs gespeichert werden. |
| Die Navigationen werden jeweils pro aktivierte 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 aktivierten Sprachen an den Navigation Service übermitteln und existierende Navigationen, zu denen keine korrespondierende Sprache im Projekt vorhanden ist, löschen.
|
Sprachen gelten als aktiviert, sofern die Option |
Navigation zur Generierungszeit
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.
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. |
{
"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)
Falls eine solche Contentprojektion im Projekt existiert, enthält der zugehörige Navigationsknoten das Attribut seoRouteRegex. Der Wert des Attributs ist ein regulärer Ausdruck, der die dynamische Route der Contentprojektion beschreibt. Für das obere Beispiel einer Detailseitenansicht für Produkte würde der Wert ^[\/]?produkte\/[^\s\/]+$ für das seoRouteRegex Attribut erzeugt werden.
Dies sind die sogenannten Einstiegsseiten von FirstSpirit Contentprojektionen.
|
Der Navigation Service enthält keine dedizierten Informationen über einzelne Datensätze! |
Um auf die entsprechenden Datensätze der Contentprojektion zuzugreifen ist folglich ein weiterer Schritt notwendig. Üblicherweise ist dies ein Request an den Content as a Service, in dem auf Datensätze mit übereinstimmender Route gefiltert wird. Eine Beispielimplementierung findet sich im Frontend Referenzprojekt "Crownpeak PWA Template".
Der Navigation Service unterstützt darüberhinaus das Zurückführen einer dynamischen Route auf den zugehörigen Navigationsknoten. Weitere Informationen sind der Navigation Service Dokumentation aus dem Kapitel API Endpunkte zu entnehmen.
4.4. Ausschließen von Elementen aus der Navigation
Bei Bedarf ist es möglich bestimmte Seitenreferenzen oder ganze Ordner im Strukturbereich aus der Navigation auszuschließen. Im Falle von Ordner-Elementen werden auch alle Unterelemente automatisch ausgeschlossen. Dies kann für jedes Element einzeln konfiguriert werden mithilfe von Metadaten. Es muss sich dabei um ein CMS_INPUT TOGGLE handeln und dieses muss den Namen md_navservice_exclude haben.
<CMS_INPUT_TOGGLE name="md_navservice_exclude" type="radio" hFill="yes">
<LANGINFOS>
<LANGINFO lang="*" label="Exclude from Navigation Service"/>
</LANGINFOS>
<ON>
<LANGINFO lang="*" label="On" description="Excludes this element and all subelements from the Navigation Service."/>
</ON>
</CMS_INPUT_TOGGLE>|
Die Exclude-Direktive von Unterelemente wird durch die höchstgelegene Exclude-Direktive in der Vaterkette überschrieben. |
Die Exclude-Direktive in den Metadaten wird auch für Elemente angezeigt, die nicht im Strukturbereich liegen. Ausgewertet werden sie aber nur dort. Deshalb ist es sinnvoll mittels einer Regel den Eintrag in den Metadaten nur im Strukturbereich anzuzeigen.
<RULE>
<WITH>
<EQUAL>
<PROPERTY name="STORETYPE" source="#global"/>
<TEXT>sitestore</TEXT>
</EQUAL>
</WITH>
<DO>
<PROPERTY name="VISIBLE" source="md_navservice_exclude"/>
</DO>
</RULE>5. Authentifizierung
In der aktuellen Version des Navigation Service Stacks sind folgende Punkte in der Projektentwicklung zu berücksichtigen.
5.1. Authentifizierung für Lese-Zugriffe
Bitte beachten Sie, dass standardmäßig es derzeit keine Authentifizierungs-/Autorisierungsverfahren für alle GET-Aufrufe gegen die Navigationsendpunkte gibt. Dies betrifft nur das Lesen der Navigationen - das Schreiben erfordert eine Authentifizierung/Autorisierung. Dies hat zur Folge, dass jede redaktionelle Änderung an einem FirstSpirit-Projekt mit einer aktivierten Navigation Service Projekt-Komponente direkt in die Vorschau-Navigation übertragen wird und somit für jeden zugänglich ist.
Falls die Notwendigkeit besteht, lassen sich auch GET-Aufrufe entweder nur für Preview Navigationen oder komplett sperren. Wenden Sie sich dafür bitte an den Crownpeak Technology Support.
6. Rechtliche Hinweise
Das Navigation Service-Modul ist ein Produkt der Crownpeak Technology GmbH.
Für die Verwendung des Produkts gilt gegenüber dem Anwender 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.