FirstSpirit™ FormEdit

e-Spirit AG

20.07.2020
Inhaltsverzeichnis

1. Einleitung

Das Modul FirstSpirit™ FormEdit besteht aus einer redaktionellen Komponente zur Erstellung von Web-Formularen über den FirstSpirit SiteArchitect bzw. ContentCreator und einer Web-Komponente in Form eines Servlets, das die vom Nutzer eingegebenen Daten entgegennimmt und weiterverarbeitet.

1.1. Übersicht der Funktionen

Folgende Formen der Weiterverarbeitung von Formulardaten werden unterstützt:

Speichern der Daten in einer Datei im CSV-Format
Diese Art der Weiterverarbeitung speichert alle vom Formular gesendeten Werte innerhalb einer freidefinierbaren Datei im CSV-Format ab.
Speichern der Daten in einer JDBC-fähigen Datenbank
Durch Verwendung dieses Typs der Weiterverarbeitung ist es möglich, die Werte innerhalb einer Datenbank zu speichern. Über die Konfigurationseinstellung kann ein individuelles Mapping für die Formularfelder definiert werden.
Versand der Daten als E-Mail
Bei dieser Art der Weiterverarbeitung können beliebige Formulardaten per E-Mail versendet werden. Mittels einer E-Mail-Vorlage kann der Aufbau der E-Mail individuell gestaltet werden. Die E-Mails können u.a. mit Dateianhängen versendet werden, ebenso sind cc- und bcc-Empfänger möglich.
Ausgabe der Daten in das Log-File der Servlet-Engine
Diese Funktion dient dazu, alle Werte des Formulars innerhalb des Log-Files der Servlet-Engine auszugeben, in der das FormServlet initialisiert ist.
Aufruf einer URL mit Parameterübergabe
Diese Funktion ermöglicht es, eine URL mit den definierten Parametern aufzurufen, ohne dass der Benutzer diese Seite im Browser sieht (z.B. Tracking).

Weiterhin ist es möglich, die Formulare über eigene Implementierungen auszuwerten. Die oben genannten Weiterverarbeitungsmethoden können darüber hinaus miteinander kombiniert werden.

1.2. Aufbau und Funktion

Die folgende Grafik zeigt den Aufbau und die Funktionsweise des Moduls am Beispiel des Live-Servers. Bei der Nutzung innerhalb der Preview oder des Stagings werden die in FirstSpirit verwendeten Web- und Applikationsserver benutzt.

Aufbau und Funktionsweise
Abbildung 1. Aufbau und Funktionsweise


1.3. Technische Voraussetzungen

Für den FormEdit-Einsatz müssen die folgenden technischen Voraussetzungen erfüllt sein:

  • das Modul FormEdit in der aktuellen Version
  • FirstSpirit (Isolated- oder Legacy-Mode) 5.2.181007 oder höher
  • einen aktuellen Servlet-Container

2. Installation und Konfiguration

Die Installation des Moduls FirstSpirit™ FormEdit erfolgt in drei Schritten:

2.1. Installieren des Moduls auf dem Server

Das Modul muss mithilfe der mitgelieferten fsm-Datei auf dem FirstSpirit-Server hinzugefügt werden. Öffnen Sie dafür den ServerManager und wählen Sie den Bereich Server-EigenschaftenModule.

Installation des Moduls auf dem FirstSpirit-Server
Abbildung 2. Installation des Moduls auf dem FirstSpirit-Server


Im Hauptchannel ist eine Liste aller auf dem FirstSpirit-Server installierten Module zu sehen. Wählen Sie nach dem Klicken auf Installieren die fsm-Datei aus und bestätigen Sie die Auswahl mit Öffnen. Nach der erfolgreichen Installation wird das Modul in der Liste angezeigt und muss Alle Rechte erhalten (vgl. Abbildung Installation des Moduls auf dem FirstSpirit-Server).

Bestandteile des Moduls FirstSpirit™ FormEdit sind die Projekt-Applikation FS FormEdit ProjectConfiguration, die Webanwendung FS FormEdit und die Bibliothek FS FormEdit Scripts.

Die Projekt-Applikation stellt Medien, Seiten-, Absatz-, Skript- und Tabellenvorlagen zur Verfügung, die zum Gestalten von Formularen verwendet werden können. Die Komponente ist Sichtbar für den Bereich Projekt. Damit handelt es sich um eine projekt-lokale Komponente. Diese kann nach der Installation den Projekt-Komponenten innerhalb der gewünschten Projekte zugefügt werden.

Die Webanwendung stellt Servlets zur Verfügung, die innerhalb des Projekts verwendet und aufgerufen werden können. Die Komponente ist Sichtbar für die Bereiche ProjektWeb. Damit handelt es sich um eine web-lokale Komponente. Diese kann nach der Installation den unterschiedlichen Web-Bereichen (preview, staging, live, ContentCreator) innerhalb der gewünschten Projekte zugefügt werden.

Die Bibliothek stellt die für die Skripte benötitgen Klassen zur Verfügung.

Nach jeder Installation oder Aktualisierung eines Moduls ist ein Neustart des FirstSpirit-Servers notwendig.

2.2. Installation und Konfiguration der Projekt-Komponente

Für den Einsatz des FirstSpirit™ FormEdit-Moduls ist eine projektspezifische Konfiguration notwendig. Diese wird über die Projekt-Komponente vorgenommen, die dem verwendeten Projekt hinzuzufügen ist. Öffnen Sie dafür den ServerManager und wählen Sie den Bereich Projekt-EigenschaftenProjekt-Komponenten.

Installation der Projekt-Komponente
Abbildung 3. Installation der Projekt-Komponente


Im Hauptpanel ist eine Liste aller bereits vorhandenen Projekt-Komponenten zu sehen. Wählen Sie nach dem Klicken auf Hinzufügen die FS FormEdit ProjectConfiguration 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 Installation der Projekt-Komponente). Selektieren Sie dafür den Eintrag in der Liste und öffnen Sie den zugehörigen Konfigurationsdialog über Konfigurieren (vgl. Abbildung Konfiguration der Projekt-Komponente).

Konfiguration der Projekt-Komponente
Abbildung 4. Konfiguration der Projekt-Komponente


Wählen Sie aus der Combobox Schema einen Datenbank-Layer und klicken Sie auf Templates importieren. In der Auswahlliste befinden sich alle für das Projekt zugelassenen Datenbank-Layer. Sollten Sie bisher keine Layer verwenden oder wünschen Sie für das Modul eine eigene Datenbank, wählen Sie den Eintrag Neuer Layer. Ist diese Option gewählt, wird ein neuer Layer erzeugt, der auf die FirstSpirit-interne Derby-Datenbank zeigt.

Weitere Informationen zu Datenbank-Layern finden Sie im FirstSpirit Dokumentation für Administratoren.

Nachdem Sie den Button Templates importieren angeklickt haben und den Dialog schließen, ist keine Änderung der Konfiguration mehr möglich. Ein erneutes Importieren ist nur mittels Löschen und erneutem Hinzufügen der Projekt-Komponente möglich.

2.3. Installation und Konfiguration der Web-Komponente

Zusätzlich zur Projekt-Komponente muss eine Web-Komponente hinzugefügt werden. Öffnen Sie hierfür den ServerManager und wählen Sie den Bereich Projekt-EigenschaftenWeb-Komponenten.

Installation der Webanwendung innerhalb der Web-Bereiche
Abbildung 5. Installation der Webanwendung innerhalb der Web-Bereiche


Innerhalb des Hauptpanels sind vier Registerkarten zu sehen, die jeweils eine Liste der bereits vorhandenen Web-Komponenten enthalten. Selektieren Sie nach dem Klicken auf Hinzufügen für jede der vier Registerkarten die FS FormEdit-Komponente und bestätigen Sie die Auswahl jeweils mit OK. Installieren Sie die Web-Komponente anschließend auf einem aktiven Webserver. Dieser kann über die Auswahlbox gewählt werden. Die Liste im Hauptpanel ist anschließend für alle vier Registerkarten um die Web-Komponente ergänzt.

Nach dem Hinzufügen zu einem Webbereich besteht die Möglichkeit, die Komponenten zu konfigurieren, entweder mit einer von der Komponente erzeugten web.xml oder einer generischen GUI (vgl. Abbildung Konfiguration der Webanwendung).

Konfiguration der Webanwendung
Abbildung 6. Konfiguration der Webanwendung


Für die Konfiguration stehen unterschiedliche Parameter zur Verfügung:

OK Redirect
In diesem Feld wird der Pfad zu der Datei angegeben, die nach erfolgreichem Versenden der Formulardaten angezeigt wird. Auf diesen Wert wird zurückgegriffen, falls im Formular keine spezielle Seite angegeben wurde (siehe Kapitel form-start). Über das Prefix redirect: bzw. forward: kann das Weiterleitungsverhalten beeinflusst werden. Der Wert forward:ok.jsp würde z.B. eine Weiterleitung mit allen Parametern auf die Seite ok.jsp erzeugen. Ist weder forward: noch redirect: angegeben, erfolgt immer ein Redirect.
Error Redirect
In diesem Feld wird der Pfad zu der Datei angegeben, die nach fehlerhaftem Versenden der Formulardaten angezeigt wird. Auf diesen Wert wird zurückgegriffen, falls im Formular keine spezielle Seite angegeben wurde (siehe Kapitel form-start). Über das Prefix redirect: bzw. forward: kann das Weiterleitungsverhalten beeinflusst werden. Der Wert forward:error.jsp würde z.B. eine Weiterleitung mit allen Parametern auf die Seite error.jsp erzeugen. Ist weder forward: noch redirect: angegeben, erfolgt immer ein Redirect.
Form Encoding
In diesem Feld wird das Encoding angegeben, welches zum Versenden der Formulardaten verwendet werden soll. Hierbei handelt es sich ebenfalls um einen Rückgriffswert, wenn in der Konfiguration einer Weiterverarbeitungskomponente kein Encoding angegeben wurde. Beispiele sind UTF-8 oder ISO-8859-1.

Achten Sie immer drauf, dass das gewählte Encoding mit dem verwendeten Encoding der generierten Seiten übereinstimmt (MetaTags bzw. Encoding der Sprache im ServerManager).

Path Prefix
In diesem Feld ist ein Prefix anzugeben, welches dem Pfad zur Mail-Vorlage vorangestellt wird, um diese verwenden zu können. Dieses Prefix beschreibt den Teilpfad zwischen dem WebApp-Root und dem von FirstSpirit erstellten Ordner. Für die Staging-Umgebung wäre dies beispielsweise die Auftrags-ID.
Loggers.ini Path

In diesem Feld muss der Pfad zur Konfigurationsdatei fs-formlogger.ini angegeben werden. Ist dieses Feld leer oder kann die Datei nicht gefunden werden, wird auf eine leere Konfigurationsdatei zurückgegriffen.

Beispiel Staging

2708/de/conf/fs-formlogger.ini

Dem Pfad für die Staging-Umgebung ist die Auftrags-ID – hier 2708 – vorangestellt.

Beispiel Live

de/conf/fs-formlogger.ini

Der hier anzugebende Pfad kann auch absolut angegeben werden. Dieses Beispiel sucht die Datei relativ zum WebAppRoot.

Captcha Width
In diesem Feld wird die Anzeigebreite der Captcha-Grafik in Pixel bestimmt. Ist dieses Feld leer, wird ein interner Rückgriffwert des Servlets benutzt: 100.
Captcha Height
In diesem Feld wird die Anzeigehöhe der Captcha-Grafik in Pixel bestimmt. Ist dieses Feld leer, wird ein interner Rückgriffwert des Servlets benutzt: 100.
Captcha Chars
In diesem Feld wird die Anzahl der Zeichen, die in der Captcha-Grafik angezeigt werden, angegeben. Ist dieses Feld leer, wird ein interner Rückgriffwert des Servlets benutzt: 6.

2.4. Liveserver-seitiges Logging

Das Modul FirstSpirit™ FormEdit kann zur einfacheren Fehleranalyse Logausgaben in eine entsprechende Logdatei ausgeben. Dazu wird auf das log4j2-Framework zurückgegriffen, weshalb dieses für die Webanwendung zunächst entsprechend eingerichtet werden muss, falls dies noch nicht der Fall ist. Dies geschieht durch Ablegen der log4j2-Konfigurationsdatei log4j2.properties ins Verzeichnis WEB-INFclasses. Falls dieses Verzeichnis noch nicht existiert, kann dies einfach manuell angelegt werden.

Eine beispielhafte log4j2-Konfigurationsdatei könnte folgendermaßen aussehen:

status = error
dest = err
name = PropertiesConfig

property.filename = target/rolling/rollingtest.log

filter.threshold.type = ThresholdFilter
filter.threshold.level = debug

appender.console.type = Console
appender.console.name = STDOUT
appender.console.layout.type = PatternLayout
appender.console.layout.pattern = %m%n
appender.console.filter.threshold.type = ThresholdFilter
appender.console.filter.threshold.level = error

appender.rolling.type = RollingFile
appender.rolling.name = RollingFile
appender.rolling.fileName = ${filename}
appender.rolling.filePattern = target/rolling2/test1-%d{MM-dd-yy-HH-mm-ss}-%i.log.gz
appender.rolling.layout.type = PatternLayout
appender.rolling.layout.pattern = %d %p %C{1.} [%t] %m%n
appender.rolling.policies.type = Policies
appender.rolling.policies.time.type = TimeBasedTriggeringPolicy
appender.rolling.policies.time.interval = 2
appender.rolling.policies.time.modulate = true
appender.rolling.policies.size.type = SizeBasedTriggeringPolicy
appender.rolling.policies.size.size=100MB
appender.rolling.strategy.type = DefaultRolloverStrategy
appender.rolling.strategy.max = 5

logger.rolling.name = de.espirit.firstspirit.opt.formedit
logger.rolling.level = debug
logger.rolling.additivity = false
logger.rolling.appenderRef.rolling.ref = RollingFile

rootLogger.level = info
rootLogger.appenderRef.stdout.ref = STDOUT

Es ist zu beachten, dass abhängig von der Konfiguration auch Logausgaben aus anderen Modulen in der Logdatei auftauchen können.

3. Konfiguration des FirstSpirit-Projekts

Für diesen Abschnitt werden Kenntnisse im Umgang mit FirstSpirit im Bereich Datenquellen vorausgesetzt.

Die verschiedenen Weiterverarbeitungsmöglichkeiten der Formulardaten werden durch sogenannte Logger im Projekt konfiguriert. Jedem Logger wird ein bestimmter Weiterverarbeitungstyp (z.B. MailLogger) zugeordnet und mit entsprechenden Parametern versehen. Die verschiedenen Logger werden als Datensätze in einer Datenquelle gepflegt. Anhand der Logger-Konfiguration wird bei der Generierung die Logger-Konfigurationsdatei fs-formlogger.ini erzeugt. Das dazu notwendige Datenbankschema und die nötigen Tabellenvorlagen werden bei Installation der Projektkomponente erzeugt. Um Logger anlegen zu können, muss nur noch eine Datenquelle für die Tabellenvorlage form_edit.formLogger erstellt werden. Informationen zu den Logger-Typen und deren Konfigurationsmöglichkeiten finden Sie im Kapitel Logger-Konfiguration der Weiterverarbeitung.

Bitte beachten Sie, dass Sie das Mapping innerhalb der Tabellenvorlage form_edit.formLogger noch für die fehlenden Sprachen setzen. (Im Auslieferungszustand ist nur die Sprache Deutsch gemapped.) Für die sprachabhängige Spalte formLogger_description sollten weitere Spalten mit _<Sprachkürzel> angelegt werden.

3.1. Anlegen der Logger

Öffnen Sie das Projekt im SiteArchitect. Nun gibt es zum Anlegen oder Bearbeiten der Logger zwei Möglichkeiten:

  • direkt über die Datenquellen (Datenquelle: FormLogger) in der Datenquellen-Verwaltung

    Neuer Datensatz (Datenquellen)
    Abbildung 7. Neuer Datensatz (Datenquellen)


  • aus dem Absatz form-start heraus

    Neuer Datensatz (form-start)
    Abbildung 8. Neuer Datensatz (form-start)


Nach einem Klick auf den Button Neuer Eintrag in der Datenquellenansicht oder in der Eingabekomponente innerhalb des formstart-Absatzes wird folgendes Formular geöffnet:

Anlegen der Logger
Abbildung 9. Anlegen der Logger


In diesem Formular werden alle logger-spezifischen Daten erfasst:

Logger Name
Hier kann der Logger mit einem Namen versehen werden. Der Name wird innerhalb der Konfigurationsdatei als Referenzname verwendet. Der Name darf keine Leer- oder Sonderzeichen enthalten und muss projektweit eindeutig sein.
Logger Typ

Der Logger Typ wird für die Erstellung der Logger-Konfigurationsdatei fs-formlogger.ini benötigt. Folgende Logger-Typen stehen zur Verfügung:

Beschreibung
In diesem Feld kann eine kurze Beschreibung eingegeben werden, um den Logger später einfacher zuordnen zu können. Die Eingabe ist optional und nimmt keinen Einfluss auf die Funktion des Loggers.
Logger Parameter

Hier können die logger-spezifischen Konfigurationsparameter festgelegt werden. Bei einem Eintrag ist zwischen drei Vorlagen zu wählen:

  • logger-text-value

    Diese Vorlage wird bis auf eine Ausnahme – die Auswahl der Mail-Vorlage – für alle Parameter verwendet.
  • formLoggerPassword

    Diese Vorlage kann für Parameter verwendet werden, deren Inhalt in FirstSpirit nicht sichtbar sein soll.
  • logger-template-ref

    Diese Vorlage wird ausgewählt, wenn eine Mail-Vorlage für den MailLogger bzw. MailUploadLogger aus der Struktur gewählt werden soll. Die Parameter, die hier verwendet werden können, werden im nachfolgenden Kapitel erläutert.