PDFTemplate: API erstellt perfekte PDF‘s aus ODT Dateien mit Platzhaltern / Variablen

Egal ob Online-Rechnung, Vertragsdokumente, Infobroschüren, Produktkataloge oder Preislisten: PDF‘s sind allgegenwärtig und als Dokumentenformat weit verbreitet. Doch gerade die dynamische Erzeugung dieser ist online noch immer mit einigen Hürden verbunden. Wer zum Beispiel als Online-Shop Betreiber seinen Kunden nach einem Kaufabschluss die Rechnung als PDF per E-Mail zukommen lassen möchte, steht erst einmal vor dem Problem diese PDF zu erzeugen. Solange sich der Inhalt in Grenzen hält und man bereit ist Abstriche beim Layout der Rechnung einzugehen, lässt sich dies meist noch realisieren.

Bisheriges Problem: HTML-Formatierungen unterscheiden sich stark von denen in PDF-Dateien

Es existieren eine handvoll Tools und Bibliotheken, die zum Beispiel ein HTML Dokument in eine PDF überführbeispielen. So lässt sich zum Beispiel eine Rechnung mit gängigen HTML Werkzeugen in Kombination mit Stylesheets/CSS erstellen und daraus eine Rechnung generieren. Doch Vorsicht: Die Formatierungswerkzeuge in HTML unterscheiden sich stark von denen in PDF Dateien. Eine Bibliothek, die also ein HTML Dokument in eine PDF überführt muss diese Formatangaben daher in PDF kompatible Formatierungen übersetzen und wie bei der Übersetzung von gesprochener Sprache gehen auch hier Informationen während des Übersetzungsvorgangs verloren.

Eine perfekte 1 zu 1 Darstellung des HTML Dokuments als PDF ist daher nur schwer realisierbar und allenfalls bei sehr einfachen Dokumenten mit wenigen oder einfachen Formatierungen möglich.

Möchte man also zum Beispiel einen perfekt formatierten Vertrag mit individuellen Kundendaten und einem Briefkopf erstellen, wo die Adressdaten genau in das Sichtfenster des Briefumschlags passen, ist man meist aufgeschmissen.

Mit PDFTemplate einfach eine ODT-Datei mit Variablen über eine API befüllen und als PDF herunterladen

Was wäre, wenn man nun einfach hergehen könnte und eine ODT / Open-Office oder LibreOffice Datei erstellt, diese mit Platzhalten für alle relevanten Informationen befüllt und daraus vom System eine PDF erstellen lässt?

Genau dies ist nämlich möglich mit unserem PDFTemplate Service – ein kostenlos nutzbarer Dienst für alle, die perfekte PDF‘s erstellen wollen.

Das Prinzip ist super einfach: Man erstellt einfach eine ODT-Datei (Open-Document Datei) und kann diese genau so layouten, wie man später auch das Ergebnis als PDF erwartet. Es können dort beliebige Briefköpfe, Hintergründe, Bilder und auch automatische Platzhalte (z. B. Seitenzahl oder das aktuelle Datum) eingefügt werden.

Das Dokument kann nun mit beliebig vielen Platzhalten bzw. Variablen befüllt werden. Jeder Platzhalter wird zwischen geschweiften Klammern eingefügt.

Beispiel:

{Vorname}
{Nachname}
{Strasse_Nr}

Die Platzhalter können auch beliebig formatiert werden, z. B. in Fettschrift, unterstrichen, durchgestrichen in einer abweichenden Schriftart oder Schriftgröße, etc. Jeder Formatierung die Ihr Office-Programm hergibt ist möglich.

Wiederkehrende Platzhalter ermöglichen die Ausgabe mehrere Datensätze

Auch wiederkehrende Platzhalter können verwendet werden. Damit ist dann möglich bestimmte Bereiche oder Abschnitte eines Dokuments zu wiederholen und mit einem ganzen Satz an Daten zu befüllen. Wichtig ist dies zum Beispiel bei Rechnungen: hier soll ja zum Beispiel jedes gekaufte Produkt als eigene Belegzeile aufgeführt werden, je mit eigener Produktbezeichnung, der bestellten Menge, einem Einzelpreis und dem Gesamtpreis.

Ein weiteres Beispiel für wiederkehrende Platzhalter bzw. Variable-Sets sind mehrere Vertragspartner in Vertragsdokumenten. Hier wird dann zum Beispiel jeder Vertragspartner mit Namen, Anschrift und Telefonnummer einzeln aufgeführt.

Solche wiederkehrenden Platzhalter werden innerhalb eines Dokuments zunächst über einen eigenen Marker gekennzeichnet, um dem Dokument zu signalisieren: „Achtung, hier beginnt jetzt ein wiederkehrender Datensatz“. Eine solche Markierung sieht dann zum Beispiel so aus:

[!-- BEGIN row.zeile --]

Wiederkehrende Datensätze müssen auch wieder abgeschlossen werden, dazu wir dann ein ähnlich lautender Marker genutzt, um dem Dokument zu signalisieren, dass die Wiederholungen ab hier beendet werden.

Gemäß des obigen Platzhalters, hieße dann der Endplatzhalter für Wiederholungen so:

[!-- END row.zeile –]

Wir haben ein Beispiel-Dokument erstellt um die Verwendung von Wiederholungen besser zu veranschaulichen. Sie können das Demodokument hier herunterladen: Demodokument.

Auch Bilder können über Platzhalter in die Dokumente eingefügt werden

Sie können die Platzhalter auch mehrfach verwenden oder Platzhalter erstellen, die im späteren PDF Dokument dann durch Bilder ersetzt werden. Sinnvoll ist dies zum Beispiel wenn man auf eine Online-Rechnung (z. B innerhalb von Drupal Commerce) bei jeder Position das jeweilige Produktbild hinterlegen möchte.

Wir haben diese Funktion zum Beispiel bei der Berfusfelderkundungsplattform (kurz BFE) des Landes NRW integriert. Dort kann man jedes BFE Angebot als PDF herunterladen. Hinterlegt sind dort neben dem Angebotstitel, dem Umfang und der Beschreibung des Praktikums auch die Unternehmensdaten und ein Logo des anbietenden Unternehmens. Jede dieser Angaben ist über einen eigenen Platzhalter in der ODT-Vorlage integriert.

Wie können aus den ODT-Vorlagen nun PDF‘s erstellt werden?

Vereinfacht gesagt, wird die zuvor erstellte PDF Vorlage zusammen mit den Platzhalten und den gewünschten Ersetzungen an unseren PDFTemplate-Server gesendet, der die darin enthaltenen Platzhalter mit den gewünschten Werten befüllt, daraus eine PDF generiert und diese PDF wieder über die Schnittstelle zurücksendet.

Zu kompliziert?

Kein Problem, denn wir haben für diese Aufgabe eine eigene PHP Library erstellt, die Sie einfach in Ihr Projekt einbinden können.

Laden Sie die Library hier herunter: https://github.com/Kommune3/PDFTemplate

Alternativ können Sie die Library auch mit Composer in Ihr Projekt einbinden:

composer require kommune3/pdftemplate

PDFTemplate Library verwenden


require 'PDFTemplateAutoload.php';
$pdf = new PDFTemplate();

// Basic settings
$pdf->setFilename('example.pdf');
$pdf->setTemplate('odt/example.odt'); // Path to your local Open Document Template

// Set some vars
$pdf->addVar('first_name', 'John');
$pdf->addVar('last_name', 'Doe');

// Add a row
$row = new PDFTemplateRow('demoitems');
$row->addVar('position', '1');
$row->addVar('title', 'This is a title');
$row->addVar('quantity', '5');
$row->addVar('price', '15.99');

$pdf->addRow($row);

// Finally create the PDF
$pdf->createPDF();

Warum funktioniert PDFTemplate nur mit ODT Dateien? Kann ich trotzdem auch aus meiner Word-Datei eine PDF erstellen?

ODT steht für "Open Document Text Format" und bereits an seinem Namen kann man erkennen, dass es sich hierbei um ein offenes Format handelt. Offen bedeutet hier, dass jeder uneingeschränkt das Recht hat solche Dateien zu öffnen und zu interpretieren. Und dies ist entscheidend: wenn wir Platzhalter in den Dokumenten ersetzen wollen, müssen wir diese Dokumente über unsere Software bzw. über unseren PDFTemplate Server zunächst öffnen um dann dort nach Platzhaltern zu suchen. Jeder gefundene Platzhalter wird dann durch seinen Wert ersetzt und das Dokument wieder gespeichert. Im nächsten Schritt erfolgt dann schon die Konvertierung.

Im Gegensatz zum ODT-Format ist das klassische Word-Format das zum Beispiel in Microsoft-Office eingesetzt wird nicht offen. Wir haben also technisch gar nicht die Möglichkeit in diesen Dokumenten nach Platzhaltern zu suchen und diese zu ersetzen.

Wie kann ich Word Dokumente mit PDFTemplate nutzen?

Am einfachsten ist es das gewünschte Word- oder MS-Office Dokument in ein ODT Dokument zu konvertieren. Dies kann man entweder direkt aus Microsoft-Office heraus tun, indem man das Dokument einfach im ODT Format abspeichert oder man öffnet das Dokument in LibreOffice, einem frei verfügbaren Office-Programm, welches von Haus aus mit ODT Formaten arbeitet.