Module development in the Cloud, 2024.12

Dokumentation

Modul-Dokumentation

Dieses Dokument führt Sie durch den Modulentwicklungsprozess in der FirstSpirit-Cloud. Der allgemeine Prozess wird kurz erklärt. Links führen Sie zu einer detaillierten Dokumentation, in der bestimmte Schritte des Prozesses beschrieben werden.

Zielgruppe: (Neue) Modulentwickler im FirstSpirit-Cloud-Umfeld

Voraussetzungen: DTA (Developer Training Advanced)
Schulungs- und Coaching-Zentrum

Ihre FirstSpirit-Cloud-Umgebung

Ihre FirstSpirit-Cloud-Instanz umfasst standardmäßig drei Umgebungen: Dev, QA und Prod:

FirstSpirit Cloud-Umgebung

Entwicklung (Dev)
In dieser Umgebung können ein oder mehrere Entwickler arbeiten, ohne sich gegenseitig zu behindern oder den Live-Code zu gefährden.

Qualitätssicherung (QA)
Diese Umgebung ist der Staging-, bzw. Testbereich, in dem entwickelte Segmente getestet werden können, um die Qualität zu gewährleisten, bevor sie in die Produktionsumgebung übertragen werden. Diese Umgebung ist daher eine nahezu exakte Nachbildung der Produktionsumgebung.

Produktion (Prod)
Diese Umgebung enthält alle veröffentlichten Projekte, die möglicherweise bereits Inhalte enthalten und für Kunden verfügbar sind.

Die Projekte in allen drei Umgebungen sind fast identisch.
Änderungen an Vorlagen und Einstellungen werden regelmäßig in die nachfolgende Umgebung kopiert. Damit werden Abweichungen im Entwicklungsstand vermieden.
Die Umgebungen Dev und QA enthalten in der Regel Testinhalte. Prod zeigt den gesamten Inhalt des Live-Projekts an.

Unterstützende Tools für die Modulentwicklung

Entwicklungstool	Wird in der Crownpeak Cloud-Entwicklung verwendet
Programmiersprache	Java 17
Versionskontrolle	Git
Branching-Modell	Git-Flow
Quellcode-Repository	Bitbucket
CI/CD	Bamboo
Build-Automatisierungstool	Gradle
Artefakt-Repository	Artifactory

Erweiterung von FirstSpirit

FirstSpirit bietet mehrere Erweiterungsmöglichkeiten, die es Entwicklern erlauben, benutzerdefinierte serverseitige und clientseitige Funktionen zu implementieren. Die verschiedenen Erweiterungspunkte der FirstSpirit-API können von verschiedenen sogenannten Komponententypen genutzt werden.

Die Komponenten werden als FirstSpirit-Module verpackt und verteilt. Dabei handelt es sich im Grunde um ZIP-Dateien mit der Erweiterung .fsm, die alle Ressourcen und Abhängigkeiten sowie einen Moduldeskriptor im XML-Format enthalten. Definition des Moduls

Hinweis: Alle Cloud-Server verwenden den isolierten Modus. Einige zentrale Aspekte werden hier beschrieben: Modulentwicklung „Isoliert“

Erweiterung des FirstSpirit ContentCreators

Als Teil des nutzerzentrierten Designs von ContentCreator bietet Crownpeak Projektentwicklern die Möglichkeit, benutzerdefinierte Funktionen zu entwerfen, die zusätzliche Interaktionsfunktionen bieten, die Redakteuren bei der Ausführung bestimmter Aufgaben helfen. ContentCreator-Erweiterungen

Jeder dieser Plugin-Typen ist in einen anderen Bereich der ContentCreator-Benutzeroberfläche eingebunden und kann FirstSpirit-Daten sowie Umfrageeingaben von Benutzern verarbeiten:

Bildschirmfoto

Anwendungsfälle für ContentCreator-Module	Unterstützung
1. InlineEdit-Elemente Fügen Sie eine oder mehrere Aktionen in das Schaltflächen-Overlay ein, das angezeigt wird, wenn der Mauszeiger über einem Abschnitt, einem Seiteninhalt oder einem Datensatz bewegt wird, der im Vorschaufenster gerendert wird.	InlineEdit-Buttons
2. Template-Schaltflächen (FS_BUTTON) bieten Zugriff auf Skripts und Java-Klassen, die zusätzliche Funktionen implementieren. Diese Schaltflächen werden direkt in Seiten-, Abschnitts- oder Datensatzvorlagen platziert, ermöglichen Klick- und Drag-and-Drop-Interaktionen und können in Formularen, Vorschau-/generierten Darstellungen von Elementen oder beidem gerendert werden.	Vorlagen-Buttons
3. Menüelemente in der Werkzeugleiste Geben Sie ein oder mehrere Menüelemente an, die im Aktionsmenü der ContentCreator-Symbolleiste angezeigt werden.	Toolbar-Menüelemente
4. Berichte (Datenzugriff) Integrieren Sie externe Datenquellen (z. B. Webservices) in FirstSpirit, damit Daten aus diesen Quellen (z. B. Bilder, Youtube-Videos, etc.) innerhalb von FirstSpirit-Inhalten referenziert werden können.	Datenzugriff
5. Elementstatus- und Arbeitsablaufanzeigen Geben Sie einen projektweiten Algorithmus an, um den Seitenstatus zu bestimmen (ob die Seite als veröffentlicht, geändert oder als Teil eines Workflows gilt), der in der ContentCreator-Symbolleiste angezeigt wird.	Elementstatus- und Arbeitsablaufanzeigen
6. Seitenbasierte Benachrichtigungen Implementieren Sie Benachrichtigungen, die in der ContentCreator-Vorschau erscheinen. Sie werden im Seitenstatus-Flyout der ContentCreator-Symbolleiste sowie — optional — gut sichtbar unter der Seitenstatusanzeige angezeigt.	Seitenbezogene Benachrichtigungen

Erweiterung des FirstSpirit SiteArchitect

Der FirstSpirit SiteArchitect bietet mehrere Möglichkeiten, Plugin-Komponenten zu integrieren. Diese können Automatisierungsfunktionen, zusätzliche Eingabekomponenten sowie Konnektoren zu Webdiensten implementieren, die als Datenanbieter oder weitere Tools zur Inhaltsbearbeitung dienen. SiteArchitect-Erweiterungen

Jeder dieser Plugin-Typen knüpft an einen anderen Bereich in der SiteArchitect-Benutzeroberfläche an und ist in der Lage, die FirstSpirit-API-Funktionalität zur Ausführung programmatischer Aktionen zu verwenden:

noch ein Screenshot

Anwendungsfälle für SiteArchitect-Module	Unterstützung
1. Kontextmenü-Elmente Fügen Sie eines oder mehrere Menüelemente im Kontextmenü von Store-Elementen, Untermenü „Neu“ bzw. „Plug-ins“ ein.	Kontextmenüeinträge
2. Toolbar-Elemente Fügen Sie Schaltflächen in die Werkzeugleiste ein, die über dem redaktionellen (mittleren) Workspace im SiteArchitect angezeigt wird. Arbeiten Sie im Kontext des FirstSpirit-Elements, das aktuell in diesem Workspace angezeigt wird, z. B. ein Abschnitt, dessen Formular gerade angezeigt wird.	Toolbar-Aktionen
3. Berichte (Datenzugriff) Integrieren Sie externe Datenquellen (z. B. Webservices) in FirstSpirit, damit Daten aus diesen Quellen (z. B. Bilder, Youtube-Videos, etc.) innerhalb von FirstSpirit-Inhalten referenziert werden können.	Datenzugriff

Einrichten Ihrer Arbeitsumgebung

Als Entwickler müssen Sie Ihre Umgebung einrichten:

Zugriff auf Git-Repositorys
Artifactory-Anmeldeinformationen

Die Einrichtung muss nur einmal durchgeführt werden, da die Konfiguration für alle Repositorys gemeinsam genutzt wird.

Einrichtung des Zugriffs auf Git-Repositorys

Um Zugriff auf das Git-Repository zu erhalten, müssen Sie Ihren SSH-Schlüssel in Ihrem Bitbucket-Profil angeben. Verwenden Sie einen vorhandenen oder neu erstellten Schlüssel. Fügen Sie den öffentlichen Schlüssel Ihrem Profil hinzu (Offizielle Bitbucket-Hilfe).

Einrichtung von Artifactory-Anmeldeinformationen für den Zugriff auf Modulabhängigkeiten

Die in Ihrem Modul angegebenen Abhängigkeiten werden von unserer Artifactory heruntergeladen, die als Maven-Repository fungiert. Damit dies funktioniert, müssen Sie die Anmeldeinformationen in Ihren persönlichen gradle.properties angeben.

Die gradle.properties-Datei befindet sich in $HOME/.gradle/gradle.properties.

Die Datei sollte mindestens enthalten:

artifactory_hosting_username=cloud_username artifactory_hosting_password=cloud_encrypted_password

cloud_username ist in der Regel Ihre vollständige E-Mail-Adresse.

Das verschlüsselte Passwort kann durch einen einfachen Artifactory REST-Aufruf abgerufen werden. Verwenden Sie bei der Anmeldung Ihre Cloud-Anmeldeinformationen.

Modul-Entwicklung

Der erste Schritt zur Entwicklung Ihres Moduls besteht darin, das vorhandene Repository aus Ihrem FirstSpirit-Cloud-Git zu klonen. Wenn noch kein Repository existiert, senden Sie eine Anfrage an das Crownpeak-Support-Team.

Die folgenden Schritte können Ihnen helfen, Ihre eigenen FirstSpirit-Module zu entwickeln:

Modul-Entwicklung	Unterstützung
1. Senden Sie eine Anfrage an das Support-Team, falls das Repository noch nicht existiert.	Support-Ticket erstellen Geben Sie die gewünschten, möglichst aussagekräftigen, Namen der Repositorys im Ticket an.
2. Klonen Sie das vorhandene Repository in Bitbucket Die Ersteinrichtung enthält bereits eine vorkonfigurierte Gradle-Umgebung.	Bitbucket Gradle Build Tool
3. Verpacken Sie das Moduls in eine FSM-Datei mithilfe des FirstSpirit Module Gradle Plug-ins. Es erstellt einen Moduldeskriptor und fügt dem Archiv alle erforderlichen Abhängigkeiten.	FirstSpirit Module Gradle Plug-in
Verwenden Sie einen lokalen Testserver für eine Beschleunigung der lokalen Entwicklung. Das FirstSpirit Gradle Plug-in kann einen solchen Server für Sie starten und das Modul automatisch installieren. Diese Funktion ist auch für automatische Integrationstests nützlich.
Verwenden Sie Webanwendungs-Komponenten Komponenten von Webanwendungen können entweder global oder projektlokal verwendet werden und sind aus Ressourcen- und Leistungsgründen erforderlich, um globale Komponenten zu erstellen.	FirstSpirit-Webanwendungen Support-Ticket erstellen Geben Sie folgende Informationen an: Name der Instanz Name der Komponente, die hinzugefügt werden soll Name der Web-App (z. B. „ContentCreator“) Optional: Konfiguration der Komponente

Modul-Verteilung

Je nach verwendetem Git-Branch löst ein Push-Commit einen automatischen Build-Prozess aus, der das Modul in einer deiner Cloud-Instanzen installiert. Die Namenskonvention ist dieselbe wie in Git Flow, einem Git-Workflow, dessen Verwendung wir empfehlen.

dritter Screenshot

Die folgenden Schritte können Ihnen helfen, Ihre eigenen FirstSpirit-Module zu entwickeln:

Modul-Verteilung	Unterstützung
1. Lokale Modul-Entwicklung	Die Entwicklung und das Testen neuer Features sollte immer lokal in einem Feature-Branch geschehen. Gepushte Commits auf diesen Branches werden von unserer CI-Pipeline kompiliert und getestet, wohingegen Ihre Cloud-Server unverändert bleiben.

Der Prozess in der CI-Pipeline wird abgebrochen, wenn nicht mindestens ein erfolgreicher Unit-Test vorliegt.


2. Pushen fertiger Funktionen in den Dev-Branch	Gepushte Commits auf dem Dev-Branch werden in der Dev-Cloud-Instanz installiert. Die Voraussetzung dafür ist eine fehlerfreie Kompilierung und ein erfolgreicher Testdurchlauf. CI/CD-Pipeline Wenn Ihr Modul WebApp-Komponenten enthält und Ihre Komponente zum ersten Mal deployt wird, wenden Sie sich an den technischen Support, um die Komponente der jeweiligen globalen Webanwendung (ContentCreator / Preview) hinzufügen zu lassen. Stellen Sie im Ticket folgende Informationen bereit: Bezeichnung der Instanz Bezeichnung der Komponente, die hinzugefügt werden soll Bezeichnung der Webanwendung (z. B. "ContentCreator") Konfiguration der Komponente (optional) Ticket beim Technischen Support

2. Pushen fertiger Funktionen in den Dev-Branch

Gepushte Commits auf dem Dev-Branch werden in der Dev-Cloud-Instanz installiert. Die Voraussetzung dafür ist eine fehlerfreie Kompilierung und ein erfolgreicher Testdurchlauf.

CI/CD-Pipeline

Wenn Ihr Modul WebApp-Komponenten enthält und Ihre Komponente zum ersten Mal deployt wird, wenden Sie sich an den technischen Support, um die Komponente der jeweiligen globalen Webanwendung (ContentCreator / Preview) hinzufügen zu lassen.

Stellen Sie im Ticket folgende Informationen bereit:

Bezeichnung der Instanz
Bezeichnung der Komponente, die hinzugefügt werden soll
Bezeichnung der Webanwendung (z. B. "ContentCreator")
Konfiguration der Komponente (optional)

Ticket beim Technischen Support

Das Aktualisieren eines Moduls kann ein Re-Deployment erfordern, z. B. für den ContentCreator. Dies kann bestehende User-Sessions in der Dev-Instanz beeinträchtigen.


3. Mergen von Änderungen im Master-Branch (QA)	Für den Release einer neuen Version Ihres Moduls ist dessen Installation in Ihrer QA-Instanz notwendig. Die Installation wird automatisch durchgeführt, nachdem die Änderungen in den Master-Branch gemergt wurden.

Der "Release"-Plan erzeugt die Modul-Versionsnummer im Master-Branch automatisch. Um die Versionsnummer des Snapshots manuell heraufzusetzen, muss zuerst die Versionsnummer aktualisiert und die Änderungen erst im Anschluss im Master-Branch gemergt werden.
Wir empfehlen die Verwendung von Semantic Versioning.


4. Modul-Installation in Prod-Instanz	Neue Modulversionen werden in der Prod-Instanz nur während der Patch-Tage installiert. Für eine detaillierte Vorgehensweise kontaktieren Sie bitte den Technischen Support von FirstSpirit. Stellen Sie im Ticket folgende Informationen bereit: Modulname Benötigte Versionsnummer Ticket beim Technischen Support

4. Modul-Installation in Prod-Instanz

Neue Modulversionen werden in der Prod-Instanz nur während der Patch-Tage installiert. Für eine detaillierte Vorgehensweise kontaktieren Sie bitte den Technischen Support von FirstSpirit.