FragmentCreator ist ein CXT-Client, der auf das Anlegen und Bearbeiten von format-neutralen Fragmenten abgestimmt ist (siehe Introducing FragmentCreator).

Der FragmentCreator wird als Modul auf dem FirstSpirit-Server installiert. Anschließend muss der FragmentCreator explizit einem Projekt zugeordnet werden. Dazu muss für jedes Projekt im Bereich „Webapplikationen“ eine eigene Webanwendung definiert werden (s.u.).

Herkömmliche FirstSpirit-Projekte können nicht nachträglich als Fragment-Projekte konfiguriert werden.

Die folgende Dokumentation bezieht sich auf die Version 3.x des Moduls.

Modul-Datei

fragment-creator-[version].fsm

Installieren des Moduls

Das Modul wird über den FirstSpirit ServerManager installiert, und zwar im Dialog „Servereigenschaften / Module“ über die Schaltfläche „Installieren“:

(Zu weiteren Informationen zur Installation von Modulen siehe auch Module (→Dokumentation für Administratoren).)

Globale Webanwendung erstellen

Die Webanwendung muss anschließend über den FirstSpirit ServerManager im Bereich „Web-Applikationen“ als eigene, globale Webanwendung definiert und konfiguriert werden (Schaltfläche „Hinzufügen“ bei „Globale Web-Apps konfigurieren“, siehe dazu auch Web-Applikationen (→Dokumentation für Administratoren), Abschnitt „Installieren von globalen Web-Applikationen“).

Web-Komponente hinzufügen

Für diese globale Web-Applikation muss ein geeigneter Webserver ausgewählt sein, dann die Web-Komponente „FragmentCreator“ hinzugefügt und deployed (Schaltfläche „Installieren“ / „Aktualisieren“) werden.

Wird der Dialog mit „OK“ geschlossen, wird das zur Web-Komponente „FragmentCreator“ gehörige „ApplicationPlugin: FragmentCreator (WebApp)“ automatisch der Web-Applikation „Startseite“ hinzugefügt (siehe Seite „Zugang über die FirstSpirit-Startseite“, Absatz Bereich "Web-Applikationen" / "Startseite"). Dies ist erforderlich, damit das Icon, mit dem der FragmentCreator über die FirstSpirit Startseite gestartet werden kann, erscheint.
Dort muss die Web-Komponente auch deployed werden (Schaltfläche „Installieren“ / „Aktualisieren“).

Schließlich muss das „ApplicationPlugin: FragmentCreator“ im Bereich „Startseite“ hinzugefügt werden. Siehe dazu Seite „Zugang über die FirstSpirit-Startseite“, Absatz Bereich "Startseite".

Statusseite für die Fehleranalyse

Eine Quelle für Fehler ist häufig eine fehlerhafte Konfiguration. Sie kann dazu führen, dass die Software nicht oder nicht wie erwartet funktioniert.

Unter

/status

(angehängt an die URL des FragmentCreator) ist eine Statusseite erreichbar, die beim Aufdecken von Konfigurationsproblemen hilft, also z. B.

http://myServer:8080/fragments/status

Neben Informationen zum Server führt die Seite auch einen Test der Konfiguration durch, listet die letzten HTTP-Requests und Logmeldungen sowie alle aktuell registrierten MicroApps mit Erreichbarkeit, Name und URL auf.

Um Logmeldungen zu erhalten, muss der Parameter logging.file.name mit der gewünschten Log-Datei (z. B. /tmp/fc.log) angegeben werden, z. B.

logging.file.name=/home/tomcat/logs/fragments.log

Die Statusseite ist nur für Administratoren erreichbar.

Hinweis: Zum Testen der Erreichbarkeit sendet die Statusseite an jede MicroApp einen leeren Kontext zur Überprüfung. Das kann zu Warnmeldungen wie dieser im Log führen:

de.espirit.cxt.microapps.stereotype.UnsupportedContextException: Context is not supported

Konfiguration

per web.xml

Die Konfiguration der Web-Applikation erfolgt über die entsprechende web.xml oder über eine Properties-Datei.
Die standardmäßig verwendeten Platzhalter-Werte funktionieren nicht in jedem Setup und sollten geprüft und an das jeweilige Setup angepasst werden.

Speziell bei Änderungen des Standardwerts der URL für die Webanwendung „FirstSpirit Startseite“ fs5root (über den Parameter WEBAPP_ROOT_URL) funktioniert die automatische Ersetzung für den Platzhalter ${FIRST_SPIRIT_URL} nicht (z. B. cxt.fragmentcreator.internal-url). In diesem Fall muss der gewünschte Wert manuell angegeben werden.
(Zu weiteren Informationen zum Parameter WEBAPP_ROOT_URL siehe Web Applications (→Dokumentation für Administratoren).)

Beispiel: FirstSpirit-Server, Standardkonfiguration für cxt.fragmentcreator.internal-url in der web.xml:

<context-param>
   <param-name>cxt.fragmentcreator.internal-url</param-name>
   <param-value>${FIRST_SPIRIT_URL}/FragmentCreator/</param-value>
</context-param>

Ausgerolltes Modul auf dem Tomcat-Webserver (automatische Ersetzung):

<context-param>
   <param-name>cxt.fragmentcreator.internal-url</param-name>
   <param-value>http://demo.e-spirit.de:2001/FragmentCreator/</param-value>
</context-param>

Bei Änderung auf den Wert WEBAPP_ROOT_URL=/fs5root:

<context-param>
   <param-name>cxt.fragmentcreator.internal-url</param-name>
   <param-value>http://demo.e-spirit.de:2001/fs5root/FragmentCreator/</param-value>
</context-param>

Kommentare

Kommentare werden in der web.xml mit

<!--

eingeleitet.
Diese Zeichenfolge kann auch zum Auskommentieren von Parametern verwendet werden.

Kommunikation

cxt.platform.firstspirit.hostname: Hostname oder IP-Adresse des FirstSpirit-Servers.

cxt.platform.firstspirit.port: Port des FirstSpirit-Servers.

cxt.platform.firstspirit.connection-mode: Verbindungsmodus für die Kommunikation mit dem FirstSpirit-Server.

HTTP: normale Internetverbindung
SOCKET: direkter Verbindungsmodus (Standardeinstellung; Single-Sign-On nur im SOCKET-Modus)

cxt.platform.firstspirit.connection-timeout: Zeitlimit in Sekunden, nach dem FirstSpirit-Verbindungen automatisch geschlossen werden, wenn sie nicht mehr verwendet werden.
Ein zu niedriger Wert kann dazu führen, dass Benutzer unerwartet abgemeldet werden. Ein hoher Wert hingegen hält viele Verbindungen aufrecht, wenn Benutzer ihren Browser schließen, ohne sich abzumelden.
Standardwert: 43200 (12 Stunden)

cxt.fragmentcreator.internal-url: Die interne URL, die von der Plattform zur Kommunikation mit MicroApps verwendet wird, z. B.

cxt.fragmentcreator.internal-url=http://localhost:8080/FragmentCreator/

cxt.fragmentcreator.external-url: Die URL, mit der User per Browser auf den FragmentCreator zugreifen. Diese externe URL kann nicht in jedem Fall automatisch ermittelt werden und sollte daher manuell konfiguriert werden. In den meisten Fällen funktioniert folgende Einstellung:

cxt.fragmentcreator.external-url=https://external/FragmentCreator/

cxt.fragmentcreator.platform.internal-url: Die URL der Web-Applikation der CXT-Plattform. Wenn Plattform und FragmentCreator auf demselben Application Server betrieben werden, sollte eine localhost-Adresse verwendet werden, z. B.

cxt.fragmentcreator.platform.internal-url=http://localhost:8888/cxt-platform/

cxt.fragmentcreator.platform.external-url: Die URL, mit der User per Browser auf die Web-Applikation der CXT-Plattform zugreifen. Diese externe URL kann nicht in jedem Fall automatisch ermittelt werden und sollte daher manuell konfiguriert werden. In den meisten Fällen funktioniert folgende Einstellung:

cxt.fragmentcreator.platform.external-url=https://external/cxt-platform/

Authentifizierung (OAuth und Eureka)

cxt.fragmentcreator.platform.eureka-password: Verwenden Sie hier das Passwort, dass Sie über cxt.platform.eureka.password in der Konfiguration der Plattform vergeben haben.

cxt.fragmentcreator.platform.oauth-client-secret: Für eine Authentifizierung per OAuth verwenden Sie hier das Passwort, dass Sie über cxt.platform.oauth.client-secret in der Konfiguration der Plattform vergeben haben.

Content-Security-Policy Header (CSP)

cxt.fragmentcreator.csp-origins: Über diesen Parameter kann das HTTP-Header-Feld Content-Security-Policy (CSP) des Markdown Editor-iframes angepasst werden. Dies ist z. B. dann erforderlich, wenn Zugriffe auf den Markdown Editor von anderen Domains erlaubt werden sollen.
Bei inkorrekter bzw. fehlender Konfiguration des Parameters wird eine Fehlermeldung in der Browser-Konsole ausgegeben und der Markdown Editor wird nicht geöffnet.

Über den Parameter können die Origins angegeben werden, von denen ein Zugriff möglich sein soll. Dabei wird der vollqualifizierte Domänenname erwartet.
* kann als Wildcard verwendet werden, z. B. um alle URLs zuzulassen oder bestimmte Subdomains einer Domain.

Mehrere Einträge können per Leerzeichen getrennt voneinander angegeben werden.

Wird der Parameter nicht angegeben, wird der Standardwert 'self' verwendet. Damit werden ausschließlich Zugriffe vom selben Server erlaubt (derselbe Host und Port).

Beispiel:

cxt.fragmentcreator.csp-origins='self' *.e-spirit.de:8050

erlaubt Zugriffe von der Domain, von der der Header gesendet wird, sowie von Subdomains von e-spirit.de:8050.

Maximale Dateigröße bei Upload

Über den Upload-Dialog im FragmentCreator können standardmäßig Dateien bis zu einer Größe von 64 MB hochgeladen werden.

Bei Bedarf kann dieser Wert angepasst werden, und zwar über folgende Parameter in der Datei web.xml des Moduls „FragmentCreator“ bzw. in der Datei cxt-fragment-creator.properties:

spring.servlet.multipart.max-file-size: Erlaubte Dateigröße für ein Medium, das per Upload-Dialog hochgeladen wird.
Der Wert darf nicht größer sein als der Wert für spring.servlet.multipart.max-request-size.
Zu möglichen Größenangaben siehe Klasse DataSize (Spring Framework).
Standardwert: 64MB
spring.servlet.multipart.max-request-size: Jede Datei wird in einem separaten HTTP-Request übertragen. Daher muss der hier angegebene Wert mindestens so groß sein wie spring.servlet.multipart.max-file-size.
Zu möglichen Größenangaben siehe Klasse DataSize (Spring Framework).
Standardwert: 64MB

Markdown-Editor

Die Eingabe von formatierten Texten im FragmentCreator erfolgt über die Eingabekomponente FS_MARKDOWN (siehe dazu auch Seite FirstSpirit Markdown Editor).
Die Eingabekomponente basiert auf einem externen Markdown-Editor, je nach Konfiguration

auf „Quill“ (https://quilljs.com)
auf „SimpleMDE“ (https://simplemde.com)

cxt.fragmentcreator.markdown-editor-type: Über diesen Parameter kann definiert werden, welcher Editor verwendet werden soll. „Quill“ bietet mehr WYSIWYG-Komfort und dadurch eine bessere User Experience für den Redakteur.
Standardmäßig wird aktuell „Quill“ verwendet. Soll „SimpleMDE“ verwendet werden, muss der Wert simplemde angegeben werden.

Konfiguration	Auswirkung
quill	Verwendung von „Quill“
leer / keine Angabe	Verwendung des Standard-Markdown-Editors (aktuell „Quill“)
default	Verwendung des Standard-Markdown-Editors (aktuell „Quill“)
simplemde	Verwendung von „SimpleMDE“

Timeout für Registrierung von MicroApps

Das Registrieren von MicroApps kann speziell im Fall des Neustarts eines FirstSpirit-Servers bzw. des Tomcat Webservers einige Zeit in Anspruch nehmen.
Nach einer Zeitspanne von 10 Min. wird beim Starten des FragmentCreator folgende Fehlermeldung ausgegeben

x MicroApps could not be registered in a reasonable amount of time.

wenn sich die vorhandenen MicroApps nicht innerhalb dieser Zeit registrieren konnten, und der FragmentCreator wird nicht gestartet.

cxt.fragmentcreator.microAppRegistration.timeoutInMinutes: Bei Bedarf können Sie die Zeitspanne über diesen Parameter individuell anpassen.

Logausgaben

Optional können Parameter für erweiterte Logausgaben konfiguriert werden.
Siehe dazu Spring Boot Documentation (HowTo Logging).

logging.level: Spring Boot protokolliert Meldungen basierend auf dem Inhalt des Klassenpfades. Standardmäßig werden Meldungen mit dem Level WARN und höher geloggt. Zu Debug-Zwecken kann das Level über das Präfix logging.level in der web.xml aber temporär auch auf ein niedrigeres Level eingestellt werden. So können z. B. Logausgaben für CXT-Klassen über die Angabe des Packages de.espirit.cxt auf das Loglevel DEBUG eingestellt werden, z. B.

<context-param>
    <param-name>logging.level.de.espirit.cxt</param-name>
    <param-value>DEBUG</param-value>
</context-param>

logging.file.name: Über diesen Parameter können Logausgaben zusätzlich (zur Ausgabe in der Konsole) in eine Datei geschrieben werden, z. B.

<context-param>
    <param-name>logging.file.name</param-name>
    <param-value>/var/log/tomcat/cxt.log</param-value>
</context-param>

per Properties-Datei

Alternativ kann zur Konfiguration des FragmentCreator-Moduls eine Properties-Datei verwendet werden (cxt-fragment-creator.properties). Die dort hinterlegte Konfiguration überschreibt alle anderen Propertys (u.a. auch die Konfiguration über die Datei web.xml). Bei einem automatischen FirstSpirit-Update bleiben die in der Properties-Datei hinterlegten Einstellungen unverändert und werden nicht überschrieben bzw. zurückgesetzt.

Dazu muss im Classpath zunächst ein „config“-Verzeichnis erstellt und anschließend eine Datei

/config/cxt-fragment-creator.properties

angelegt werden. Bei Verwendung eines Tomcat z. B. im Verzeichnis

${TOMCAT_HOME}/lib

Innerhalb dieser Datei können die gewünschten Parameter konfiguriert werden, z. B.

markdownEditorType=simplemde

Deployment

Die wie oben beschrieben konfigurierte Web-Applikation für den FragmentCreator muss anschließend per Schaltfläche „Installieren“ auf dem gewählten Webserver ausgerollt werden.

Siehe dazu auch Web-Applikationen (→Dokumentation für Administratoren).

Druckversion | Seitenanfang