${underdocx} – Vorlagenbasierte Dokumentgenerierung neu gedacht

Was ist neu an Underdocx?

Obwohl bereits Template-Engines für unterschiedliche Dokument-Typen existieren, ist Underdocx eine Neuentwicklung, die Funktionen und Konzepte in einer Form zusammenführt, wie es andere Bibliotheken nicht tun. Zudem ist Underdocx mein erstes Open Source Projekt. Die grundsätzliche Idee entstand aus einem Kundenprojekt, bei dem wir uns eine derartige Bibliothek gewünscht hätten – sie aber nicht finden konnten. Die damals erwarteten und nun durch Underdocx erfüllten Anforderungen sind:

• Die Template-Engine soll kostenlos und Open Source sein.
• Das Lizenzmodell der Template-Engine soll unproblematisch für geschäftliche Nutzung sein.
• Die Template-Engine soll aktiv gepflegt werden und regelmäßig Updates erhalten.
• Die Template-Engine soll einfache, frei wählbare Platzhalter durch komplexe Strukturen wie z.B. dynamisch auszufüllende Tabellen oder mit Platzhalter versehene Unterdokumente (Komponenten) ersetzen können.
• Platzhalter sollen iterativ wiederholbar und kontext-spezifisch einsetzbar sein, z.B. um eine Tabelle mehrfach mit unterschiedlichen Daten in einer Schleife zu generieren.
• Die Template-Engine soll programmatisch erweiterbar sein, so dass eigene, bei Bedarf syntaktisch modifizierte Platzhalter definiert werden können, die individuell das Dokument modifizieren.
• Die Platzhalter sollen bei Bedarf parametrisierbar sein, um z.B. das Erscheinungsbild der zu generierenden Daten zu beeinflussen.

Durch die Möglichkeit, beliebige Funktionen über frei wählbare Platzhalter einzubinden, kann der Entwurf von Dokumentvorlagen extrem vereinfacht werden. So werden auch Nutzer und Nutzerinnen ohne softwaretechnisches Wissen in die Lage versetzt, Dokumentvorlagen zu erstellen, die durch die Anwendung dann schließlich automatisch befüllt werden.

Underdocx ermöglicht außerdem eine klare Trennung der anzuzeigenden Daten und ihrer Visualisierung durch Dokumentvorlagen. Softwareentwickelnde führen mittels Underdocx die Themenbereiche „Daten“ und „Visualisierung“ zusammen. Dabei kann flexibel entschieden werden, ob ggf. komplexe Anteile der Visualisierung durch einfache Platzhalter im Sinne wiederverwendbarer Komponenten ersetzt werden.

Anwendungsszenarien für Underdocx

Durch die oben erwähnte Vereinfachung der Vorlagenerstellung und die Trennung von Daten und ihrer Visualisierung lassen sich Systeme entwickeln, bei denen unterschiedliche Rollen mit unterschiedlichen Kompetenzen beteiligt sind, wie es die folgende Grafik skizziert:

Der „Customer“ entwirft eine oder mehrere Vorlagen mit Hilfe einfacher Platzhalter. Die Vorlagen können ein gemeinsames „Master-Layout“ einbeziehen, so dass zum Beispiel Kopf- und Fußzeilen nur einmal gestaltet werden müssen. Hinter den vereinfachten Platzhaltern können sich weitere Komponenten oder Erweiterungen verbergen, die von Softwareentwickelnden vorbereitet wurden. Letztere verbinden mithilfe von Underdocx die Datenquelle mit der Dokumentgenerierung. Die Daten selbst werden von Mitgliedern der Rolle „Data Provider“ bereitgestellt, die weder an der Erstellung von Templates noch an der Softwareentwicklung beteiligt sein müssen.

Die Möglichkeit der Trennung in verschiedene Rollen bedeutet aber nicht, dass Softwareentwickelnde Underdocx nicht auch „einfach nur“ verwenden können, um z.B. PDFs mit Hilfe von selbst gestalteten Templates zu erzeugen. Ein solcher Anwendungsfall wäre zum Beispiel die Erstellung einer Rechnung im WebShop.

Da sich auch Grafikdateien mit Platzhalter versehen lassen, kann Underdocx beispielsweise auch als Übersetzungswerkzeug für Grafiken genutzt werden. Eine Grafik wird einmal angefertigt und mittels Übersetzungsdaten in verschiedene Sprachen übersetzt. So lassen sich zum Beispiel Grafiken für internationale Wikis erstellen und vielfach wiederverwenden.

Ein kleiner Einblick

Zur Demonstration sei hier eine Dokumentvorlage vorgegeben, gespickt mit vielen verschiedenen Platzhaltern. Einige adressieren direkt die darzustellenden Daten wie zum Beispiel ${$address}, welcher die Adresse des Empfängers ausgibt. ${Date format: „yyyy-MM-dd“} hingegen ist ein parametrisierter Platzhalter, der das aktuelle Datum darstellt. Der Parameter „format“ gibt dabei die erwünschte Datumsformatierung an. Dieser Platzhalter ist ein Beispiel dafür, dass auf der Visualisierungsebene entschieden werden kann, wie Daten darzustellen sind. Andere Platzhalter hingegen verbergen technische Details wie zum Beispiel ${addAddressAndFooter}, der eine Master-Vorlage einliest und das Dokument um eine Kopf- und Fußzeile erweitert. ${membersTable} bindet ein anderes Dokument inklusive Tabelle und weitere Platzhalter ein. Dieser Platzhalter demonstriert, wie Komplexitäten durch die Definition einfacher Platzhalter verborgen werden können und dass sich auch auf diese Weise wiederverwendbare Komponenten realisieren lassen.

Der nachfolgende Code-Ausschnitt zeigt, wie die Template-Engine mit Daten „befüttert“ wird. Die Daten werden über die Engine in Variablen gespeichert, auf die sich die Platzhater beziehen können. Daten sind nicht nur einfache Texte, sondern können – wie in diesem Beispiel – auch Bilder und andere Dokumente sein.

Zusätzlich werden die bereits erwähnten Platzhalter ${addAddressAndFooter} und ${membersTable} registriert. Sie werden durch komplexere parametrisierte Platzhalter ausgetauscht, was den Dokumenterstellenden jedoch verborgen bleibt.

// Prepare document and engine
OdtContainer doc = new OdtContainer(is);
OdtEngine engine = new OdtEngine(doc);

// Alias placeholders
engine.registerStringReplacement("addHeaderAndFooter", "${Export $resource:\"master\"} ");
engine.registerStringReplacement("membersTable", "${Import $resource:\"membersTable\"} ");

// Variables / Data
engine.pushLeafVariable("membersTable", readResource("membertable.odt"));
engine.pushLeafVariable("master", readResource("master.odt"));
engine.pushLeafVariable("signatureImage", readResource("signature.png"));
engine.pushVariable("persons", createPersonsData());
engine.pushVariable("address", "Mr. Peter Silie\nKochstrasse 42\n38106 Braunschweig");
engine.pushVariable("contact", "Mr. Silie");
engine.pushVariable("signature", "Jon Sutton");

// Execute the engine
engine.run();
doc.save(os);
doc.writePDF(pos);

Die letzten drei Code-Zeilen führen schließlich die Ersetzung der Platzhalter aus und speichern das nun ausgefüllt Dokument als ODT und als PDF ab, das dann wie folgt aussehen könnte:

Wie geht es jetzt weiter?

Mittlerweile hat Underdocx einen gewissen Mindestumfang an Funktionen erreicht und kann einfach über das Maven Central Repository in das eigene Projekt eingebunden werden. Für Maven beispielsweise müsste die pom.xml wie folgt angepasst werden.:

<dependency>    
   <groupId>io.github.winterrifier</groupId>    
   <artifactId>underdocx</artifactId>    
   <version>0.10.1</version>
</dependency>

Underdocx befindet sich noch fortlaufend in der Entwicklung. Weitere Funktionen sind bereits in Arbeit, wie z.B. die Unterstützung weiterer Dateiformate. Zusätzlich muss auch Arbeit in die Bekanntheit und Sichtbarkeit des Projekts investiert werden. Nicht zuletzt auch deswegen ist die Webseite https://underdocx.org entstanden. Hier sind weitere detaillierte Informationen zum Projekt inklusive eines detaillierten „User Guide“ zu finden. Ich freue mich aber auch über direkte Kontaktaufnahme von Interessierten.