Die Dokumentenerstellung per Seriendruck besteht darin, Werte aus einer Datenquelle zu lesen und jeden davon in den passenden Platzhalter einer Vorlage einzusetzen. Sie behalten zwei Dinge: eine Vorlage mit den Seriendruckfeldern (den Variablen, die gefüllt werden) und eine Datenquelle, die die Werte sowie alles liefert, was auf jeder Kopie gleich bleibt. Die Reporting-Engine von PDF4me nimmt diese beiden Dateien und gibt ein fertiges Dokument zurück.
PDF4me akzeptiert Word-, HTML- und PDF-Vorlagen, und die reichhaltigste der drei ist Word. Mit einer kleinen, gut lesbaren Syntax entwerfen Sie eine einzige Word-Vorlage, die Rechnungen, Belege, Verträge, Angebote oder jedes personalisierte Dokument abdeckt, und erzeugen daraus Tausende aus Daten. Dieser Leitfaden führt durch die gesamte Syntax — Seriendruckfelder, Bedingungen, Formatierung, Tabellen, Bilder und Inline-HTML — mit Beispielen zum Kopieren und einer Beispielvorlage, die Sie herunterladen und ausführen können. Jeder Syntax-Link verweist auf genau die passende Seite in der Dokumentation zur Word-Vorlagen-Syntax.
Schreiben Sie Platzhalter als <<[FieldName]>> in ein Word-Dokument. Ergänzen Sie Bedingungen, Formatierung, Schleifen, Bilder und HTML mit einer Handvoll weiterer Tokens. Senden Sie diese Vorlage zusammen mit einer JSON- (oder XML-)Datendatei an die PDF4me-Aktion „Generate Document“, und Sie erhalten ein fertiges, personalisiertes Dokument zurück — einmal oder tausendfach.
Wie entwerfen Sie eine Word-Vorlage?
Alles beginnt mit einem Platzhalter. Überall, wo ein Wert eingesetzt werden soll, tippen Sie den Feldnamen, eingefasst in doppelte spitze Klammern und eckige Klammern:
<<[FieldName]>>
Der Name in den Klammern muss einer Eigenschaft in Ihrer Datenquelle entsprechen. Halten Sie Namen aussagekräftig, bleiben Sie bei einer Konvention (camelCase oder PascalCase) und vermeiden Sie Sonderzeichen. Hier eine minimale Vorlage und die Daten, die sie füllen:
Dear <<[CustomerName]>>,
Thank you for your order #<<[OrderNumber]>>.
{
"CustomerName": "John Smith",
"OrderNumber": "12345"
}
Die Engine gibt zurück:
Dear John Smith,
Thank you for your order #12345.
Das ist die ganze Idee. Alles Weitere unten ist eine Variation desselben Prinzips — Bedingungen, Schleifen und Formatierung umschließen alle ganz normale Seriendruckfelder. Vollständige Details finden Sie in der Syntax-Übersicht.
Wie fügen Sie einer Vorlage Bedingungen hinzu?
Die Aktion „Generate Document“ kann anhand Ihrer Daten verzweigen. Je nachdem, ob eine Bedingung wahr ist, wird der eine oder der andere Inhaltsblock eingesetzt. Die grundlegende if / elseif / else-Struktur sieht so aus:
<<if [condition1]>> Add the first block
<<elseif [condition2]>> Add the second block
<<else>> Add the fallback block
<</if>>
Bedingungen können einen Wert direkt prüfen oder sich auf die Enumerationsmethoden stützen (mehr dazu unten), zum Beispiel <<if [employees.Any(p => p.Age > 50)]>>. Den vollständigen Satz an Vergleichs- und Logikoperatoren finden Sie unter Bedingte Logik.
Wie formatieren Sie Werte in einer Vorlage?
Oft muss ein Rohwert vor dem Einsetzen aufbereitet werden — ein Datum in einem bestimmten Stil, eine gerundete Zahl, Text in Großbuchstaben. Fügen Sie nach dem Feldnamen eine Formatangabe hinzu, getrennt durch einen Doppelpunkt und in Anführungszeichen:
<<[token]:"format">>
Datumsangaben verwenden ein Muster im .NET-Stil:
Invoice Date: <<[invoiceDate]:"dd.MM.yyyy">>
Due Date: <<[dueDate]:"MMMM dd, yyyy">>
Für die Groß-/Kleinschreibung gibt es eigene kurze Schalter — :upper, :caps (jedes Wort großschreiben) und :firstCap:
Customer: <<[customerName]:upper>>
Product: <<[productName]:caps>>
Zahlen verwenden Standard-Zahlenformate, sodass <<[price]:"F2">> einen Wert auf zwei Nachkommastellen festlegt. Die vollständige Liste der Datums-, Text- und Zahlenmuster finden Sie unter Formatierung in Vorlagen.
Wie erstellen Sie Tabellen aus einer Liste?
Bei Tabellen zeigt die Dokumentenerstellung ihre Stärke — eine Vorlagenzeile wird zu so vielen Zeilen, wie Ihre Daten haben. Erstellen Sie eine normale Word-Tabelle, öffnen Sie eine <<foreach>>-Schleife in der ersten Zelle, fügen Sie in jede folgende Zelle ein Seriendruckfeld ein und schließen Sie die Schleife in der letzten Zelle:
Column 1: <<foreach [product in products]>><<[product.productName]>>
Column 2: <<[product.manufactured]:"yyyy.MM.dd">>
Column 3: <<[product.price]>><</foreach>>
Jedes Objekt im Array products wird zu einer Zeile, und Sie können Zellen inline formatieren wie überall sonst. Weitere Tabellenmuster, einschließlich gefilterter und aggregierter Zeilen, finden Sie unter Tabellen in Vorlagen.
Wie wiederholen Sie Absätze und Abschnitte?
Dieselbe <<foreach>>-Schleife funktioniert auch außerhalb von Tabellen. Umschließen Sie einen beliebigen Inhaltsblock — einen Absatz, eine Überschrift mit Text, einen ganzen Abschnitt — und er wiederholt sich einmal pro Element der Sammlung:
<<foreach [item in collection]>>
Content with <<[item.property]>>
<</foreach>>
Schleifen lassen sich verschachteln (ein Abschnitt pro Abteilung, eine Zeile pro Mitarbeiter darin) und können die Sammlung dabei filtern oder sortieren. Verschachtelte und bedingte Beispiele finden Sie unter Absätze und Abschnitte wiederholen.
Wie fügen Sie einer Vorlage Bilder hinzu?
PDF4me kann Bilder aus einer öffentlichen URL oder einem Base64-String in ein erzeugtes Dokument einfügen. Eine Regel ist wichtig: das Bildfeld muss in einem Word-Textfeld liegen. Erstellen Sie das Textfeld an der gewünschten Stelle und fügen Sie dann das Feld hinzu.
Aus einer öffentlichen URL:
<<image [imageUrl]>>
Aus einem Base64-codierten String:
<<image [imageBase64]>>
Die Größe steuern Sie mit Schaltern wie -keepRatio, -fitHeight, -fitWidth und -fitSize, z. B. <<image [companyLogo] -keepRatio>>. Die vollständige Größenreferenz und Beispiele für Bilder pro Zeile finden Sie unter Bilder einfügen.
Wie fügen Sie HTML in eine Vorlage ein?
Wenn Ihre Daten bereits formatiertes HTML enthalten, geben Sie es mit dem Schalter -html direkt aus, statt es als Klartext zu maskieren:
<<[token] -html>>
Die Engine parst den Feldwert als HTML und wendet die Formatierung an — Fett, Kursiv, Listen, Überschriften, farbige Spans und mehr — innerhalb des erzeugten Dokuments. Unterstützte Tags und Stile sind unter HTML einfügen aufgeführt.
Arbeiten Sie mit Ihren Daten über Enumerationsmethoden
Über einfache Felder hinaus stellt die Engine Methoden im IEnumerable-Stil bereit, die Sie direkt in einem Token aufrufen können — filtern, sortieren, zählen, mitteln und mehr. Ein paar Beispiele:
Total products: <<[products.Count()]>>
Average price: $<<[products.Average(p => p.price)]:"F2">>
Top items: <<foreach [p in products.OrderByDescending(x => x.price).Take(5)]>><<[p.name]>><</foreach>>
Diese lassen sich natürlich mit Bedingungen und Schleifen kombinieren. Die vollständige Methodenliste — Where, OrderBy, GroupBy, Sum, Any, First und der Rest — finden Sie unter Enumeration in Vorlagen.
Die Beispieldaten sehen so aus — ein Lieferant, ein Kunde und eine Produktliste, über die die Vorlage iteriert:
{
"VendorName": "PDF4me",
"VendorCity": "Zurich",
"VendorCountry": "Switzerland",
"VendorZip": "8630",
"VendorContact": "123456",
"InvoiceDate": "22-08-2022",
"CustomerName": "John Doe",
"CustomerCity": "Start City",
"CustomerCountry": "US",
"CustomerZip": "3214",
"products": [
{ "productName": "PDF Converter", "value": 2000, "expires": "01/08/2025" },
{ "productName": "PDF API", "value": 1250, "expires": "18/02/2029" },
{ "productName": "PDF Editor", "value": 1999, "expires": "12/12/2027" }
],
"comments": "This document is <b>computer generated</b> and does not require a signature."
}
Beachten Sie: comments enthält HTML — kombinieren Sie es mit dem Schalter <<[comments] -html>>, und das <b>-Tag wird in der Ausgabe fett dargestellt.
Schnellzugriffe für den Entwurf Ihrer Vorlage
Häufige Fragen
Wie erstelle ich Seriendruckfelder in einer Word-Vorlage?
Tippen Sie den Feldnamen in doppelte spitze und eckige Klammern, etwa <<[CustomerName]>>, überall dort, wo ein Wert eingesetzt werden soll. Der Name muss einer Eigenschaft in Ihrer JSON- oder XML-Datenquelle entsprechen. Sie können Felder überall manuell hinzufügen — Überschriften, Absätze, Tabellenzellen oder Textfelder.
Welche Vorlagenformate unterstützt PDF4me?
Word (.docx, .doc), HTML und PDF. Alle drei verwenden dieselbe Seriendruckfeld-Syntax, sodass sich Gelerntes von einer Word-Vorlage übertragen lässt. Word bietet die umfassendste Kontrolle über Layout, Bedingungen, Tabellen und Bilder.
Kann ich einer Word-Vorlage if/else-Bedingungen hinzufügen?
Ja. Umschließen Sie Inhalte mit <<if [condition]>> ... <<elseif [condition]>> ... <<else>> ... <</if>>. Eine Bedingung kann ein Feld direkt vergleichen oder eine Enumerationsmethode wie Any() oder Count() aufrufen. So bewältigt eine einzige Vorlage jede Variante Ihrer Daten, statt eine Datei pro Fall zu pflegen.
Wie formatiere ich Datum und Zahlen in einer Vorlage?
Setzen Sie das Format nach dem Feldnamen in Anführungszeichen: <<[invoiceDate]:"dd.MM.yyyy">> für ein Datum, <<[price]:"F2">> für eine Zahl mit zwei Nachkommastellen. Für die Groß-/Kleinschreibung gibt es Kurzschalter — :upper, :caps und :firstCap.
Wie erzeuge ich eine Tabelle, die mit meinen Daten wächst?
Erstellen Sie eine Word-Tabelle, öffnen Sie <<foreach [item in collection]>> in der ersten Zelle, setzen Sie in jede weitere Zelle ein Seriendruckfeld und schließen Sie mit <</foreach>> in der letzten Zelle. Jedes Element der Sammlung wird automatisch zu einer Zeile.
Fehlerbehebung
Nächste Schritte
Entwerfen Sie die Vorlage einmal, verbinden Sie sie mit Ihren Daten, und PDF4me liefert personalisierte Rechnungen, Verträge und Berichte auf Abruf — aus einem einzigen API-Aufruf oder einer Automatisierung, die Tausende auf einmal verarbeitet.