PDFs generieren mit CiviCRM

Es geht um die schlichte Aufgabe, ein HMTL- in ein PDF-Dokument zu verwandeln. Eine Funktion, die an verschiedenen Stellen sehr nützlich ist, etwa beim Erzeugen von Spendenbescheinigungen etc.

Natürlich wünschen wir uns ein PDF-Dokument mit einer angenehmen und sinngemäßen Formatierung. Wir müssen unsere HTML-Vorlage also mit Style-Sheets ausstatten, die beim Konvertieren berücksichtigt werden – und damit beginnen die Tücken...

Etwas technisches Verständnis ist hilfreich um diesem Beitrag zu folgen – dann wird er euch helfen die ärgsten Klippen zu umschiffen.

wkhtmltopdf statt dompdf

CSS-Programmierung ist eine knifflige Angelegenheit - nicht nur Browser interpretieren CSS-Regeln oft unterschiedlich. Für HTML-to-PDF-Konverter gilt dasselbe.
CiviCRM verwendet zum Generieren von PDFs einen Konverter namens dompdf. Wenig hilfreich ist, dass die von CiviCRM eingesetzte Version die 0.5er ist, und bereits seit 8 bis 9 Jahren veraltet. Mit nachvollziehbaren Ergebnissen bei der Konvertierung der PDFs ist hier eigentlich kaum zu rechnen.

Wir folgen einem Hinweis, den wir unter "Administration >> Systemeinstellungen >> Diverses" finden, und wenden uns einem anderen HTML-to-PDF-Konverter zu: wkhtmltopdf.

Der Umstieg auf wkhtmltopdf bereitet keine Probleme. Wir laden uns das Binary herunter, legen es an einen passenden Ort auf dem Server (/usr/local/bin/) und tragen den Pfad zum Programm im Web-Formular ein. Voilá.

UPDATE: wkhtmltopdf hat unter CiviCRM manchmal Probleme bei der Erzeugung größerer PDF-Dateien. Wir konnten diese umgehen, indem wir hinter den Pfad noch das Argument "-q" gesetzt haben. Der Pfad in CiviCRM könnte dann so aussehen: /usr/bin/wkhtmltopdf-amd64 -q

(Unsere Empfehlung an dieser Stelle: Gebt euch nicht mit einer veralteten Version aus euren Paketquellen zufrieden. Debian-Squeeze etwa nutzt wkhtmltopdf-0.9.9. Diese Version bereitete uns einige Schwierigkeiten, die sich durch den Einsatz des damals neuesten Release 0.11.0 erledigten.)

HTML-Vorlagen für Print-Formate

Nun lassen sich die HTML-Vorlagen bereits einigermaßen geschmeidig bearbeiten. Und doch stoßen wir wieder und wieder auf merkwürdige Ungereimtheiten: Schriftgrößen werden falsch interpretiert, Seitenränder entsprechen nicht unseren Angaben etc. Als wir uns genauer anschauen, was CiviCRM dem HTML-to-PDF-Konverter tatsächlich übergibt, kommen wir der Sache auf die Spur:

Um eine Nachrichten-Vorlage in CiviCRM anzulegen navigieren wir zu "Administration >> Kommunikation >> Nachrichtenvorlagen" und wählen „Nachrichtenvorlage hinzufügen“. Dort können wir unter „HTML Format“ unsere Vorlage schreiben und editieren. (Nach Möglichkeit nutzen wir eine bereits existierende Vorlage und passen sie an. Das spart viel Mühe.) Schließlich wählen wir ganz unten ein PDF-Seitenformat aus, aktivieren die Vorlage und speichern sie.

Nun dürfen wir jedoch nicht glauben, dass unser HTML-Code auch jener ist, der schließlich dem Konverter übergeben wird. Tatsächlich entkernt CiviCRM unseren HTML-Code und bettet ihn in eine weitere Vorlage ein: Unser Body wird zu einem Container namens crm-container und unsere Style-Sheets werden im Head-Bereich des neuen Dokuments untergebracht.

Damit verfolgt CiviCRM folgende Ziele: Erstens definiert es ein Style-Tag, in dem unser PDF-Seitenformat auftaucht. Und zweitens - und hier beginnen unsere Schwierigkeiten - lädt es eine css-Datei für Print-Medien nach: „sites/all/modules/civicrm/css/print.css“.

In dieser Datei werden reichlich Style-Sheets definiert, etwa zur Schriftart, Schriftgröße, Tabellen-Layout, Überschriften etc. Dass die Formatierung unseres PDF-Dokuments nicht unseren eigenen CSS-Regeln entspricht, ist also kein Wunder.

Nun wollen wir die zur Installation gehörige print.css nicht überschreiben. Also versuchen wir unseren eigenen CSS-Regeln gebenüber denen der print.css Gültigkeit zu verleihen. Wenn man sich nicht gerade mit der „Spezifität“ von CSS-Regeln auskennt, ist der einfachste Weg eine Regel durchzusetzen, ihr ein „!important“ anzuhängen.

Für all jene, die sich eine feinere Abstimmung wünschen sei angemerkt, dass sich nahezu alle CSS-Regeln in print.css der crm-container-ID bedienen. Sie haben dadurch gegenüber allen Regeln, die sich auf keine ID beziehen, eine höhere Spezifität und werden vorrangig berücksichtigt.

Fazit

Wenn ihr also versucht, mit CiviCRM PDFs zu generieren, dann installiert euch zunächst eine neuere Version von wkhtmltopdf. Und berücksichtigt beim Erstellen eurer Vorlagen, dass im Hintergrund zusätzliche CSS-Regeln geladen werden. Diese zwei Maßnahmen können euch viel Ärger und Arbeit ersparen.

Bild des Benutzers Thomas Leichtfuß
Über den Autor

Thomas Leichtfuß
Junior Entwickler bei SYSTOPIA

Vielseitig interessiert und motiviert geht er technische Herausforderungen schwungvoll an und lässt nicht mehr locker bis er zufrieden ist.