Editor mit verschachtelten Templates/Formularen

Mit dem Editor "Formular (verschachtelt)", kurz "Editor Nested" lassen sich mehrseitige Dokumente, die aus Unterelementen bestehen, aufbauen. Dabei werden die einzelnen Seiten als Rahmen-Templates definiert, auf denen beliebige Print-Templates verschachtelt (englisch "nested") ausgegeben werden können. Diese Print-Templates können anhand einer x/y-Position auf dem Rahmen-Template platziert werden. Der Vorteil dieser Vorgehensweise ist, dass Print-Templates mehrfach verwendet werden können. Technisch gesehen wird die Logik des Editors "Formular (einfach)" für jedes Untertemplate ausgeführt, wodurch der Nested Editor nur die Platzierungslogik auf dem Rahmen-Template mitbringen muss.

Wie im Editor "Formular (einfach)" arbeitet der Anwender nur mittels Änderungen von Feld-Werten in einem Formular, die sich direkt in einer Bild-Vorschau auf der rechten Seite auswirken.

Anwendungsfälle sind zum Beispiel wiederkehrende Prospekte, Broschüren oder mehrseitige Flyer.

Voraussetzungen

Um den Editor Nested nutzen zu können, wird das Produkt publish benötigt. Im CMS muss die Seite mit dem Shortlink "editorNested" angelegt und konfiguriert sein.

Konfiguration

Basiskonfiguration

Es wird eine Artikelvorlage mit Editor "Formular (verschachtelt)" angelegt und als Kind-Datensatz an den gewünschten Artikel verknüpft.

Für jede gewünschte Seite des fertigen Print-Produkts muss ein Datensatz in der Tabelle "Bausteine" angelegt und als Kind an die Artikelvorlage verknüpft werden. In der Kind-Ansicht der Artikelvorlage werden diese Datensätze als "Verschachtelte Templates" dargestellt, auch "Bereiche" genannt.

Ein Bereichs-Datensatz benötigt als Kind ein Print-Template, das als Rahmen-Template fungiert. Es kann sich dabei um ein leeres A4-Template handeln. Es dient als Container dazu, die darunter liegenden Bausteine darauf zu platzieren.

Des weiteren hängen am Bereich die "Bausteine". Sie werden ebenfalls in der Tabelle "Bausteine" angelegt und an die übergeordneten Bereiche verknüpft. Sie entsprechen den verschiedenen Bausteinen auf dem Rahmen-Template und erscheinen im Frontend als Reiter (siehe Screenshot oben). Beim Baustein können x- und y-Koordinate gepflegt werden. Damit wird angegeben, an welcher Position der Baustein auf dem darüber liegenden Rahmen-Template von rechts oben in Millimetern platziert wird.

Am Baustein können nun ein oder mehrere Print-Templates hängen. Das Print-Template definiert dabei den Inhalt, der ausgegeben wird. Das Print-Template bringt seine eigene Formular-Maske mit und kann daher an anderen Bausteinen oder sogar bei einem Artikel mit dem Editor "Formular (einfach)" 1:1 verwendet werden. Hängen mehrere Print-Templates an einem Baustein, kann das Template vom Anwender im Editor gewechselt werden. So können dem Anwender z.B. verschiedene Varianten eines Gestaltungselements angeboten werden.

Für die Ausgabe wird die Logik von "Formular (einfach)" verwendet. Für das Eingabeformat "HTML5-Editor" und das Ausgabeformat PDF wird nun das Print-Template als dediziertes PDF mit den links eingegebenen Formularwerten gerendert und danach an der Position, die im übergeordneten Baustein definiert ist, auf das Rahmen-Template des wiederum übergeordneten Bereichs platziert. Dies wird für alle Bausteine wiederholt, was dann zur fertigen PDF-Seite mit verschiedenen Elementen aus verschiedenen Print-Templates führt.

Formularmaske

Jedes Print-Template bringt seine eigene Formularmaske mit, diese wird im Print-Template-Datensatz zugewiesen und muss unter Datenmodellierung > Formularmaske angelegt sein. Sie kann beliebige Felder enthalten. Felder können auch in Feldgruppen zusammengefasst werden und erscheinen dann im Nested Editor als Reiter. Alle nicht in einer Gruppe befindlichen Felder werden in einem Reiter "Allgemein" zusammengefasst.

Eingabeformate

Der Editor Nested kann mit verschiedenen Eingabeformaten umgehen. So können Print-Templates als HTML5-Editor-Template im System angelegt werden. Hierbei können die Feldwerte der dem Print-Template zugeordneten Formularmaske verarbeitet werden. Alternativ kann ein Word-Template im Docx-Format verwendet werden. In diesem werden Platzhalter mit $FELD-IDENTIFIER$ durch die im Formular gepflegten Werte ersetzt.

Ausgabeformate

Der Editor Nested unterstützt als Ausgabeformate "Verschachteltes PDF" oder "Verschachteltes Word-Dokument". Das Ausgabeformat wird bei der Artikelvorlage gepflegt. Da ein Word-Dokument fließt, kann ein Bereich mehr als eine Seite haben. In diesem Fall erscheint im Editor eine Seiten-Blätterfunktion, mit der sich die Seiten des Bereichs-Dokuments durchblättern lassen.

Bestellprozess

Artikelvorlagen im Editor Nested können mit abweichenden Bestellprozessen konfiguriert werden. In diesem Fall kann der Artikel nicht in den Warenkorb gelegt und durchbestellt werden, sondern folgt einem speziellen Ablauf. Folgende Werte können im Feld "Bestellprozess" der Artikelvorlage gepflegt werden:

Druckfreigabe

Um eine Druckfreigabe zu erzwingen, kann dieser Bestellprozess konfiguriert werden. Der Benutzer gelangt dann auf eine spezielle Seite, auf der er eine Vorschau aller Seiten der von ihm gestalteten Artikelvorlage sieht, sowie explizit eine Druckfreigabe per Checkbox setzen muss. Ferner müssen AGB und Widerrufsbelehrung akzeptiert werden. Bei Bestätigung wird eine Bestellung angelegt.

Double-Opt-In

Über diesen Bestellprozess besteht die Möglichkeit, die im Nested-Formular gesammelten Daten in einen Datenpool zu übertragen. Dies wurde in Verbindung mit deaktivierter Vorschau (siehe unten) entwickelt, um komplexe verschachtelte Formulare für die Sammlung von Daten zu nutzen. Da hierzu ein Double-Opt-In der Person notwendig ist, die das Formular ausfüllt, muss es zwingend ein E-Mail-Feld geben, das als Pflichtfeld definiert ist. Die Konfiguration hierfür wird im Feld "Vorlagenkonfiguration" der Artikelvorlage im JSON-Format gemacht:

form:
  datapool: 1
  fieldMail: personEmailAdress1
  repository: bewerberDatabase

Einstellung	Beschreibung

Einstellung	Beschreibung
datapool	Die ID des Datenpools, in dem die publish-Tabelle angelegt ist.
fieldMail	Der Identifier des Feldes, an dessen Wert die Double-Opt-In-Mail versendet werden soll.
repository	Der Identifier der publish-Tabelle,in diedie Formulardaten in einem neuen Datensatz gespeichert werden sollen.

Nach Ausfüllen des Formulars werden die gepflegten Wert in einer Übersicht gelistet, nach Bestätigung wird die Double-Opt-In-Mail verschickt. Erst bei deren Bestätigung wird der Datensatz angelegt.

Frontend

Vorschau abschalten

In Verbindung mit dem Bestellprozess "Double-Opt-In" kann die Vorschau des Editors abgeschaltet werden. Das Formular kann dann über die volle Breite laufen. Sofern man keine Druckdatei benötigt, kann so das Formular zum Sammeln von Daten verwendet werden. Hierzu muss bei der Artikelvorlage die Checkbox "Nur Formular darstellen" gesetzt werden. Dies entfernt auch jegliche Vorschau-Buttons.

Formular-Layout

Bei abgeschalteter Vorschau erstreckt sich das Formular auf die volle Breite. Felder können dabei nebeneinander dargestellt werden, um Platz zu sparen und für mehr Übersicht zu sorgen.

Hierzu können unter Softwarekonfiguration > Feldkonfiguration beim Formular-Feld folgende Werte definiert werden:

Einstellung	Beschreibung

Einstellung	Beschreibung
columns	Anzahl der Spalten im Raster des Styleguides, über die sich das Feld in der Breite erstreckt, z.B. 6
vertical	true oder false, bei true wird das Feld nicht in einer neuen Zeile dargestellt.

Constraints

Wird das Formular zum Sammeln von Daten verwendet, sind Constraints unerlässlich. Damit können z.B. Pflichtfelder definiert oder bestimmte Formate (z.B. Datum) erzwungen werden, ohne die das Formular nicht durchbestellt werden kann. Constraints werden unter Datenmodellierung > Feld direkt beim Formular-Feld unter "Feldeinschränkungen" gepflegt. Beispiel:

NotBlank()
Regex(pattern=/[^@]+@[^\.]+\..+/)

Es können alle in Symfony verfügbaren Constraints verwendet werden: https://symfony.com/doc/current/reference/constraints.html

Erfüllt ein Feldwert einen definierten Constraint nicht, wird eine Fehlermeldung dargestellt und das entsprechende Feld rot markiert.

Workflowsteuerung

Anwenderdaten-Workflows können zur Bearbeitung im Nested-Editor aktiviert werden. Dafür muss eine aktive Workflow-Warteschlange für den zugehörigen Session-Artikel existieren:

Das Feature kann in der Artikelvorlage im Feld Workflow-Steps im Verschachtelten Editor auslösen aktiviert werden.

Im Nested-Editor erscheint daraufhin rechts oben (über dem Warenkorb-Button) ein Button, der mit der Bezeichnung des nächsten Workflow-Schritts benamt ist, sofern der eingeloggte User das Recht hat, den Workflow-Schritt-Datensatz zu lesen.

Ein Klick auf den Button öffnet ein Modal:

Hier können weitere Einstellungen gemacht werden, sofern die zur Workflow-View gehörende config.json eine Spalte mit dem Attribut "isUseableInPublic": true, enthält, z.B.:

{
  "callbackTypes": [
    "shopArticle",
    "shopOrder",
    "shopSessionArticle"
  ],
  "columns": {
    "shopUser": {
      "formType": "feature",
      "feature": "input/foreignKey.single",
      "isUseableInPublic": true,
      "configuration": {
        "relation": {
          "repository": "shopUser",
          "column": "shopUserMail"
        }
      },
      "i18n": {
        "de": "Shop-Anwender",
        "en": "Shop-User"
      }
    }
  }
}

Die hier ausgefüllten Werte können genau wie bei der Ausführung von Workflow-Schritts im Backend in der zugehörigen Workflow-Engine weiterverarbeitet werden. Nach Bestätigen des Workflow-Schritts wird im Hintergrund automatisch der Button für den nächsten Workflow-Step geladen, sofern der Workflow nicht abgeschlossen ist und der eingeloggte User das Recht hat, diesen Workflow-Schritt zu lesen.

Da dieses Feature zur Steuerung von Freigabemechanismen von Editor-Dokumenten entwickelt wurden, lassen sich die Vorschau-Buttons im Nested-Editor anhand des Workflow-Fortschritts ausblenden.

Die notwendige Einstellung findet sich bei der Artikelvorlage im Reiter Augabensteuerung:

Es gibt 2 Einstellungsmöglichkeiten:

Button "PDF-Vorschau" verstecken, wenn Anwenderdaten-Workflow-Warteschlange vorhanden und nicht abgeschlossen

Der Button PDF-Vorschau wird nicht dargestellt, sofern eine Workflow-Warteschlange existiert und nicht abgeschlossen wurde.
Button "PDF-Vorschau" verstecken, wenn Anwenderdaten-Workflow-Warteschlange vorhanden und erster Step ausgeführt

Der Button PDF-Vorschau wird nicht dargestellt, wenn Workflow-Warteschlange existiert und mindestens der erste Step ausgeführt wurde.

In beiden Fällen werden die Buttons wieder dargestellt, sobald die Workflow-Warteschlange abgeschlossen wurde.

Ausgabensteuerung

In Verbindung mit den Editor Nested bietet sich die Möglichkeit einer ausgabengesteuerten Veröffentlichung von Nested-Dokumenten. Dabei werden die Artikel nicht über den Warenkorb bestellt, sondern im Backend anhand von Ausgaben vordefiniert. Pro Ausgabe gibt es eine Mastervorlage, die bestimmte Felder des Editors mit Werten vorbelegt. Auf Basis dieser Mastervorlage erhält dann der Kunde seine eigene Ausgabe, bei der bestimmte Felder verändert werden können. Hierfür wird seine Ausgabe mit seinen Anwenderdaten zusammengeführt. Dies hat den Zweck, dass fest stehende Daten wie Logo oder Firmenname nicht bei jeder Ausgabe neu erfasst werden müssen.

Die Ausgabensteuerung kann über den blauen Button in der Artikelübersicht geöffnet werden. Dieser erscheint bei Artikeln, die eine Artikelvorlage mit Editor Nested haben:

Über "Entwurf erstellen" kann eine neue Ausgabe angelegt werden. Dieser Entwurf entspricht der Ausgabe. Folgende Einstellungen sind möglich:

Einstellung	Beschreibung

Einstellung	Beschreibung
Standard-Entwurf	Ein Standard-Entwurf ist der Hauptentwurf für das Print-Produkt, von dem alle Ausgaben abgeleitet werden
ID des Entwurfs	Hier wird die ID des Entwurfs-Entities gespeichert, damit die Kundenausgaben der Hauptausgabe zugeordnet werden können. Dieser Wert muss bei der Anlage eine Ausgabe immer 0 sein
Entwurfs Workflow	Ein Workflow, der für die Ausgabe durchlaufen wird
Anwenderdaten Workflow	Ein Workflow, der für jede Kundenausgabe durchlauen wird
Name des Entwurfs	Der Name der Ausgabe
Entwurf zur Bearbeitung gesperrt	Ist das Häkchen gesetzt, lässt sich der Entwurf der Ausgabe nicht mehr im Frontend verändern. Dies muss vor der Erstellung der Kundenausgaben passieren, da sonst Änderungen am Entwurf dort nicht mehr wirksam werden. Diese Checkbox kann z.B. über einen Workflow-Step im Entwurfs-Workflow automatisch zu einem gewünschten Zeitpunkt gesetzt werden.
Ausgabe abgeschlossen	Ist das Häkchen gesetzt, können die Kundenausgaben im Frontend nicht mehr geöffnet werden

Die Vorlage des Entwurfs (Master) kann über den blauen Button bearbeitet werden. Dabei öffnet sich der Editor Nested im Frontend und die Felder können befüllt werden. Über den Play-Button lässt sich der Workflow für die Ausgabe starten. Dabei wird eine Workflow-Warteschlange vom definierten Entwurfsworkflow angelegt:

Anwenderdokumente lassen sich nun über das Plus-Symbol anlegen:

Im sich öffnenden Modal wird ein Kunde ausgewählt:

Über das Plus-Symbol kann dann das Anwenderdokument angelegt werden:

Dabei wird eine Kopie des Entwurfs (Master) erstellt und über das Feld "ID des Entwurfs" der Ausgabe zugewiesen. Ab diesem Zeitpunkt findet der Kunde seinen Entwurf in seinem Warenkorb und kann ihn bearbeiten und bestellen.Von der Ausgabensteuerung im Backend kann der Entwurf im Admin-Modus ebenfalls geöffnet und bearbeitet werden.

Datenstruktur

Folgende Entities sind im Rahmen der Ausgabensteuerung relevant:

Name	Beschreibung

Name	Beschreibung
w2pMasterData	Enthält die Vorbelegung der Nested-Felder eines Benutzers für eine Artikelvorlage, sowie die Auflage und die Information, ob die Anewnderdaten freigegeben wurden.. Die Anwenderdaten können unter "Mein Konto" gepflegt werden.
sessionArticle	Die Instanz des Artikels im Warenkorb.
sessionArticleNestedRelease	Enthält für einen Session-Artikel die für die Ausgabensteuerung relevanten Informationen, wie ID des Workflows, ID der Artikelvorlage, ID des Entwurfs
draftDocument	Dient als Verbindung von Session-Artikel und Anwenderdaten, referenziert die ID des Session-Artikels und der Anwenderdaten
nestedDocument	Enthält den Inhalt der Felder einer Nested-Vorlage