Was ist eine Vorlage?

Ein dynamische Vorlage, manchmal auch Template genannt, ermöglicht Ihnen, zeit- und kundenspezifische Daten oder globale Elemente in Ihre Dokumente zu integrieren, graphisch oder logisch aufbereitet und bereit zur direkten Verteilung an Ihre Kunden als Emails oder PDFs.

Wie funktioniert's?

Das Grundprinzip ist einfach: Sie erstellen eine .docx-Datei mit einem Textverarbeitungsprogramm wie Microsoft Word oder LibreOffice. Dann verwenden Sie Platzhalter, um anzugeben, wo und wie Daten aus ihrem System eingefügt werden sollen.

Mit low-code Funktionen können unterschiedliche Datensätze intelligent verarbeitet werden, aber Vorlagen können sich auch selbst durch modulare Komponenten Ihrer Kundenstory anpassen. Darüber hinaus können Daten in Diagrammen und Tabellen visualisiert werden und das Dokument mit Grafiken und QR-Codes ein noch zentralerer Teil ihrer Kundenkommunikation werden.

Die ersten Schritte

1. Rendern mit dem Vorlageneditor
2. Kundendaten einbinden mit Platzhaltern
3. Standardwerte und Dokumenterstellung vereinheitlichen
4. Globales und dynamisches Bildmanagement

1. Rendern Ihrer Vorlage

Der Vorlageneditor

Der Vorlageneditor ist Ihr Hauptwerkzeug, um zu testen wie Ihre Vorlagen innerhalb des Output.Rocks-Frameworks gerendert werden. Während fertige Vorlagen entweder als Dokument-Vorlage oder als E-Mail-Vorlage im System gespeichert werden können, dient der Vorlageneditor dazu, Vorschauen von lokalen oder in Cloud-Diensten gespeicherten Dokumenten zu erstellen.

Zuerst brauchen Sie ein Dokument, das Sie über die folgenden Optionen in den Editor laden können:

Dann benötigt der Editor Testdaten aus dem System, um die Ausgabe zu simulieren. Ein JSON-Datensatz zum Testen sieht beispielsweise so aus:

{
  "customer" : {
    "firstname" : "Max",
    "surname" : "Mustermann"
  },
  "contract" : {
    "id" : "1234567890",
    "date" : "2024-01-01"
  }
}

In diesem Beispiel wird ein Satz Kundendaten und ein Satz Vertragsdaten in den Objekten customer und contract gespeichert. Die einzelnen Daten haben einen Identifikator und einen Wert, angegeben in der JSON-Syntax "key" : "value".

Mit dem Button...

...erzeugen sie jetzt ihr erstes Dokument.

'Identifier' von Elementen: Eindeutige Namen

Wenn Sie eine Vorlage abspeichern wollen, werden Sie als erstes mit dem Feld 'Identifier' konfrontiert. Was hat es damit auf sich?

Diese Identifier sind technischen Namen im Backend und erlauben intern die eindeutige Auswahl, Zuweisungen und das Rendering und bleiben dabei für Admins und Redakteure lesbar. Output.Rocks löst viele Konfigurationsobjekte über ihren Identifier auf — deshalb sollte ein Identifier für dieselbe Art von Element normalerweise technisch einzigartig sein.

Parallel zur gleichen Zeit wählbare Elemente steuern Sie besser mit Vorlagen-Gruppen, welche wiederum über sogenannte Gruppen-Identifier und Gruppenbedingungen verwaltet werden. Eine Renderanfrage steuert dann alle Dokumente mit demselben Gruppen-Identifier an, gerendert werden davon dann alle, die ihre jeweiligen Bedingung erfüllen.

2. Kundendaten einbinden

Platzhalter für ihre Daten

Um Daten aus ihrem System oder Testdaten in das Dokument zu integrieren, nutzt Output.Rocks Platzhalter. Das sind spezielle Textstellen, die mit einem Wert aus Ihren Daten oder einem hinterlegten Objekt beim Rendern ersetzt werden. So können beispielsweise Kunden- und Vertragsdaten, Verbrauchswerte und ganze Tabellen in das Dokument integriert werden.

Beispielsweise kann in dem Dokument nun eine Anrede mit einem Platzhalter für den Namen des Kunden genutzt werden. Dafür muss innerhalb der Tags erst das entsprechende Objekt, ein Punkt . und dann der darin enthaltene Identifikator des Wertes angegeben werden.

Sehr geehrte(r) <<customer.firstname>> <<customer.surname>>,

Die gerenderte Ausgabe dieses Platzhalters sieht dann so aus:

Struktur von Platzhaltern

Der Syntax-Struktur des JSON-Datensatzes folgt jeder Platzhalter, egal ob sein Zielwert verschachtelt oder freistehend ist. Ebenen innerhalb des Datensatzes werden durch Punkte getrennt und können beliebig tief aneinendergereiht werden. Ein Beispiel:

Datensatz mit einem freistehenden und einem verschachtelten Wert:

{
  "name" : "Einzelgänger",

  "schachtel" : {
    "objekt" : {
      "name" : "Matruschka"
    },
  },
}

Verwendung im Dokument:

Freistehende Daten nennt man <<name>>
und verschachtelte <<schachtel.objekt.name>>.

Formatierung von Platzhaltern

Die Formatierung des Platzhalters wird beim Rendern automatisch übernommen. Das bedeutet, dass die eingesetzten Daten genau so aussehen, wie die Tags des Platzhalter im Dokument formatiert sind.

Der Inhalt eines Platzhalters kann jedoch zur besseren Lesbarkeit für Redakteure auch anders formatiert werden. Zum Beispiel kann der Name kursiv hervorgehoben werden <<customer.firstname>>, ohne dass dies im gerenderten Dokument so angezeigt wird.

3. Standardwerte und Dokumenterstellung vereinheitlichen

Neben Event- oder Kunden-spezifischen Daten können auch globale Elemente wie Grafiken oder Standardwerte in Vorlagen integriert werden. Das ist vor allem dann hilfreich, wenn sie beispielsweise in verschiedenen Dokumenten dasselbe Element oder denselben Wert benötigen und zentral verwalten möchten.

Außerdem können systemisch verwaltete Elemente auch dynamisch reagieren, beispielsweise auf Kundenstories, zeitliche Ereignisse wie Kampagnen oder auf Ereignisse in ihrem System.

Gute Beispiele für systemisch verwaltete Elemente sind:

• das Impressum und andere rechtlichen Informationen
• Logos und andere Firmen-Identitäten
• Bankdaten
• Kontaktinformationen

Globale Standardwerte

Globale Standardwerte funktionieren ähnlich wie Platzhalter, sind aber nicht an einen Datensatz oder ein bestimmtes Dokument gebunden. Sie können also an beliebigen Stellen in jedem Dokument verwendet werden, solange sie definiert sind.

Ein Standardwert wird zuerst im Backend unter Vorlagen-Management -> Standardwerte definiert:

Dann kann neben dem eigentlichen Wert auch ein Identifier vergeben werden. Jetzt ist der Standardwert in jedem Dokument verfügbar.

Standardwert im Backend:

Identifier: 'companyCEO'
Wert: 'Claus Chef'

Ein Standardwert wird wie ein Platzhalter im Dokument verwendet, allerdings mit dem Prefix standard.:

Verwendung im Dokument:

Mit freundlichen Grüßen,
<<standard.companyCEO>>, CEO 

Kommentare in Templates

Tornado unterstützt Kommentare in Templates, die beim Rendern komplett entfernt werden. Kommentare sind nützlich für Notizen oder das temporäres Deaktivieren von Template-Bereichen.

4. Globales und dynamisches Bildmanagement

Natürlich können Sie weiterhin in einem Textverarbeitungsprogramm Bilder in den Header, Footer und den Body ihrer Vorlagen-Dokumente einfügen. Solche Bilder werden dann automatisch im finalen Rendering beibehalten.

Es hat aber Vorteile, ihre Bilder zentral zu verwalten und dynamisch einzufügen:

• Logos und Identitäten werden zentral für alle Dokumente verwaltet
• Änderungen gelten sofort für alle ihre Dokumente
• Sicherstellung der Konsistenz aller Branding-Elemente
• Kampagnen oder andere Ereignisse werden dynamisch umgesetzt
• Kunden-spezifische Grafiken werden automatisch integriert

Bildplatzhalter haben immer zwei Komponenten:

• Ein beliebiges Platzhalter-Bild im Dokument, welches die Position und Maße des Bildes repräsentiert...
• ...und ein Identifier für das System-Bild, welcher den Pfad zum Bild in der Bilderverwaltung repräsentiert.

Das Platzhalter-Bild wird beim Rendering durch den Identifier ersetzt. Dafür kann jedes beliebige Bild genutzt werden, es empfiehlt sich aber eines zu wählen, das Redakteuren sofort als Platzhalter erkennbar ist. Das folgende Beispiel dürfen sie frei verwenden:

Die Größe des eingefügten Bildes entspricht der Größe des Platzhalter-Bildes, folgt aber Regeln die an ein Präfix gebunden sind:

Dahinter wird in der Bild-Syntax der im System beim Upload vergebene Identifier gesetzt. Das zusammengesetzte Bild-Objekt img_identifier oder imgfit_identifier kann nun über 2 verschiedenen Methoden eingefügt werden: Entweder statisch aus der globalen Bilderverwaltung oder dynamisch aus dem JSON-Payload.

Statische Bilder aus der globalen Bilderverwaltung

Die meisten Bilder werden statisch aus der globalen Bilderverwaltung eingefügt. Ihr Platzhalter wird entweder mit einer Textmarke oder einem Bildnamen nach dem Standard-Schema versehen:

img_identifierDesBildes

• Für Microsoft Word: Nach Klick auf das Platzhalter-Bild über Einfügen (DE) oder Insert (EN) als Textmarke (DE) oder Bookmark (EN) einfügen.
• Für LibreOffice: Nach Rechts-Klick auf das Platzhalter-Bild über Eigenschaften (DE) oder Properties (EN) im Tab Optionen als Name einfügen.

Nun wird das entsprechende Bild aus der Bilderverwaltung beim Rendern ersetzt.

Dynamische Bilder

Wenn Bilder von Daten abhängig sind, kann der Identifier auch dynamisch eingesetzt werden. Dafür benötigen wir eine im Dokument lokale Variable, die durch <<$lokaleVariable = 'Inhalt der Variable'>> definiert wird.

Damit Bildmarken oder Bildnamen diese Variable verwenden können, muss sie wie für statische Bilder beschrieben eingesetzt werden. Das Format erhält aber ein zweites Präfix var_ vor der eigentlichen Variable:

img_var_lokaleVariable

Jetzt kann der Identifier des Bildes dynamisch zusammengesetzt werden, etwa mit einem Standardwert des Systems:

Verwendung im Dokument:

<<$fotoIdentifier=standard.companyCEO>>

Nächste Schritte