Erweiterung contao-pdfforms-bundle (DE)

Diese Contao-Erweiterung von Softleister erweitert den Formulargenerator um die Möglichkeit, mit den im Online-Formular eingegebenen Daten eine PDF-Vorlage auszufüllen, zu speichern und zu versenden. 

Die Erweiterung contao-pdfforms-bundle installiert sich als eingeschränkte Demo. Die Demoversion druckt bei vollem Funktionsumfang einen Demo-Hinweis in das PDF und ist auf 2 Ausgabeseiten begrenzt.
Mit einem Lizenzkey wird die volle Funktionalität freigeschaltet. Die Lizenz erlaubt ihnen den Einsatz der Erweiterung in der beim Kauf angegebenen Domain. Der Einsatz in weiteren Domains bedarf einer zusätzlichen Lizenz.

Die Contao-Versionen 5.3 und 5.7 benötigen unterschiedliche Releases der Erweiterung:

______
Stand: Version 2.4.1 - 14.03.2026
Softleister, Dipl. Ing. Hagen Klemp, info@softleister.de, www.softleister.de


Inhalt:

1. Voraussetzungen

Die Erweiterung in Version 2.4 ist für Contao 5 ab Version 5.7 freigegeben:
Für Contao 5 mit Version 5.3 ... 5.6 verwenden Sie bitte Version 2.3.
Für die Installation wird der Composer oder der Contao Manager benötigt.

2. Zusammenspiel mit anderen Erweiterungen

Mit folgenden Erweiterungen kann contao-pdfforms-bundle zusammen genutzt werden:

notification_center    (terminal42/notification_center)

contao-pdfforms-bundle versendet über die normalen „Contao Formulargenerator-Übertragungen“. Mittels Token kann die erzeugte Datei an die Mail angehängt werden.


mp_forms    (terminal42/contao-mp_forms)

Ab pdf_forms Version 2.1 werden auch mehrseitige Formulare unterstützt, die mit mp_forms aufgebaut sind.
Anmerkung: mp_forms ist für Contao 5.7 noch nicht verfügbar, konnte daher nicht getestet werden.

fineuploader    (terminal42/contao-fineuploader)

Ab pdf_forms Version 2.2 können auch Uploads über den Fine Uploader verwendet werden. Die Formularfelder haben dann den Namen fileuploader_0...x (wobei fineuploader der vergebene Feldname ist).
Anmerkung: fineuploader ist für Contao 5.7 noch nicht verfügbar, konnte daher nicht getestet werden.

3. Installation

Installieren Sie die Erweiterung einfach mit dem Contao Manager, suchen Sie nach

PDF-Formularausgaben        oder        do-while/contao-pdfforms-bundle

oder auf der Kommandozeile mit dem Composer:

composer require do-while/contao-pdfforms-bundle

Für Contao 5.3 ... 5.6 müssen Sie im Contao Manger der Version auf ^2.3 einstellen!

Sie können die Erweiterung erst als Demo installieren und die Eignung für Ihr Projekt prüfen, die Demo hat alle Features, ist nur auf 2 Ausgabeseiten begrenzt. Bevor Sie dann Online gehen, benötigen Sie Ihren Lizenzcode:
www.softleister.de/kontakt/anfrage.html?erw=pdfforms

Den Lizenzcode tragen Sie in die .env.local – Datei im Basisverzeichnis der Contao-Installation ein. Genauer ist das in Ihrem Lizenzdokument beschrieben, was Sie nach dem Kauf der Lizenz erhalten.

4. Erweiterte Formulareigenschaften

Nach erfolgter Installation stehen Ihnen in den Eigenschaften des Formular­gene­ra­tors weitere Funktionen zur Verfügung:
Unter der Überschrift PDF-Formular ausfüllen können Sie die Erstellung einer PDF-Datei einschalten.

image.png

Sie geben eine PDF-Vorlagendatei vor, in der das unausgefüllte Formular enthalten ist. Bitte beachten Sie, dass die PDF-Spezifikation 1.4 (Acrobat 5.x) vorliegen muss, Sie müssen ggf. die Vorlage unter einem älteren PDF-Format abspeichern.
Die PDF-Vorlage wird als Kopie mit den Online-Eingaben ausgefüllt und gespeichert. Die Seitengrößen der Vorlagenseiten werden übernommen.

Sie können unter Weiterverarbeitung angeben, dass die erzeugte Datei als Mailanhang in der Formularmail enthalten sein soll.

Für das Speichern der PDF-Dateien geben Sie ein Verzeichnis zur Speicherung an. Hier werden die erzeugten, ausgefüllten PDFs abgelegt. Mit der Checkbox Speichern im Home-Verzeichnis können Sie erreichen, dass bei eingeloggten Benutzern, die ein eigenes Home-Verzeichnis haben, dort das PDF abgelegt wird. Gibt es kein Home-Verzeichnis oder ist der Versender nicht eingeloggt, dann wird das normale angegebene Verzeichnis zur Speicherung verwendet.

Der Dateiname besteht aus dem Formularnamen und einem Zeitstempel, sie können den Aufbau des Dateinamen im Feld Dateinamen erweitern anpassen. Der Standardeintrag hängt das aktuelle Datum und Uhrzeit an. Die Verwendung von InsertTags ist möglich.


Es ist möglich Mehrfach-Vorlagen in einer Vorlagen-PDF zu ver­walten. Dazu stehen alle möglichen Ausgabeseiten hintereinander in der Vorlage-PDF. Durch Angabe der steuern­den Felder als Bedingung kann die Ausgabe auf bestimmte Seiten beschränkt werden. 

image.png

In Beispiel gibt es ein Radiobutton-Element, wo man Tarif A oder B wählen kann. Ent­sprechend der Auswahl im Formular werden nur die an­ge­gebenen Seiten aus­ge­ge­ben, so sind für Tarif A die Seiten 1, 2, 3 und 7 auszugeben, für Tarif B die Seiten 4, 5, 6 und 7 (Die Seitenzahlen beziehen sich immer auf die Vorlage). Mit weiteren Bedingungen lassen sich ggf. auch Anhänge steuern. 
Wenn Sie das Element Mehrfach-Vorlagen komplett leer lassen, wird das komplette Vorlagen-PDF verwendet.

Mit Alle gültigen Vorlagenseiten übernehmen steuern Sie, ob alle Vorlagenseiten in das PDF übernommen werden sollen, oder nur die Seiten, auf denen gültige Positionen eingetragen werden. So hat man die Möglichkeit, auch optionelle Seiten über die Vorlage anzulegen. Sollte trotzdem mal eine einzelne leere Seite (wie z.B. AGB) enthalten sein, geben Sie hierfür eine Position an, die ein Leerzeichen abdruckt. Bei Mehrfach-Vorlagen bezieht sich „Alle Seiten“ nur auf die über die Bedingungen freigegebenen Seiten der Vorlage.

Wenn Sie das Formular vermessen und die Positionen eintragen, kommt es häufig zu Differenzen zum Papierrand. Diese Verschiebung trifft dann auf alle Positionen des PDFs zu. Um nicht jede Position anpassen zu müssen, können Sie einfach den Grundoffset durch einen Eintrag in den Formulareigenschaften ausgleichen.

Für die Darstellung können Sie die Schreibfarbe im PDF und für die Datei­eigen­schaften den Titel und den Autor eintragen. 
Die Schreibfarbe kann in den einzelnen Positionen individuell überschrieben werden, z.B. um eine Überschrift farblich abzusetzen.

Es ist möglich, das erzeugte PDF mit einem Passwort zu schützen. Es gibt dazu 2 Möglichkeiten:

image.png

a) Einschränkung der Berechtigungen, geben Sie hier alle freigegeben Berechti­gun­gen an. Wenn das PDF-Passwort für Berechtigungen leer gelassen wird, wird ein Zufallspasswort erzeugt. Das Passwort ist dann unbekannt.

b) Passwortschutz beim Öffnen des Dokuments
Sie können hier ein Passwort eintragen, um das unberechtigte Öffnen des PDFs zu verhindern. Versenden Sie das Passwort zur Sicherheit in einer separaten Mail oder per SMS oder einem geeigneten Messenger.

Anmerkung: Der PDF-Schutz ist nicht absolut sicher. Mit geeigneten Programmen kann das Passwort u.U. umgangen werden!

Eigene Fonts verwenden:

image.png

Für die 4 möglichen Schriftschnitte (normal, fett, kursiv, fett+kursiv) in den PDF-Positionen können jeweils TTF- oder OTF-Schriften zugeordnet werden. Wo keine Schrift gewählt ist, bleibt die Standardschrift bestehen.

Es ist auch möglich verschiedene Schriften den Schriftschnitten zuzuordnen. So kann beispielsweise eine Schmuckschrift für besondere Effekte dem Schriftschnitt fett+kursiv zugeordnet werden um Einträge hervorzuheben.

5. Definition der Positionen im PDF

In der Übersicht der angelegten Formulare gibt es einen zusätzlichen Icon (ein PDF-Symbol), wenn die PDF-Erstellung aktiv ist. In der nachfolgenden Tabelle werden die Positionen der Einträge im Vorlagen-PDF festgelegt. Es können beliebig viele Positionen angelegt werden.

image.png

Es gibt die Möglichkeit direkt im Backend ein ausgefülltes Test-PDF zu erzeugen. Damit können Sie schnell überprüfen, ob alle Positionen die richtigen Stellen im Formular ausfüllen. Alle veröffentlichten Positionen werden ausgegeben, bei Formularfeldern steht dort der Feldname.
Da keine Eingangsdaten verfügbar sind, werden die Bedingungen nicht abgeprüft, es werden also alle Felder und alle Seiten in das Test-PDF übernommen.

image.png

Es gibt verschiedene Typen der Positionen:

Anlegen der einzelnen Positionen:

a) Textpositionen

image.png

Im ersten Abschnitt werden die einzutragenden Informationen eingestellt. Es gibt folgende Möglichkeiten:

Im Beispiel sind das die Formularfelder nachname und vorname und ein fester Text mit Komma. Diese einzelnen Definitionszeilen werden mit Leerzeichen aneinander gereiht (kein Leerzeichen vor einem Komma). Sollte das automatische Leerzeichen in seltenen Situationen stören, kann man dieses abschalten.

In der 2. Spalte kann für die Ausgabe eine Bedingung programmiert werden. Wenn die Bedingung leer ist, wird die Position immer ausgegeben. Im Beispiel ist das Komma abhängig davon, ob das Feld vorname im Formular ausgefüllt (ver­wen­det) wurde. Das Komma wird also nur ausgegeben, wenn der vorname ausgefüllt wurde.

Zusätzlich kann die Bedingung invertiert werden:
verwendet    = Feld ausgefüllt / Checkbox oder Radiobutton ausgewählt
leer                  = Feld ist leer / Checkbox oder Radiobutton nicht ausgewählt

Die festen Texte können auch InsertTags enthalten:

image.png

In diesem Beispiel wird "Berlin, 04.02.2024" oder aber nur "04.02.2024" im PDF eingetragen, je nachdem, ob ort angegeben ist oder nicht.

Um Checkboxen in der PDF-Vorlage anzukreuzen, verwendet man ein "X" mit dem Checkbox-Wert in der Bedingung

image.png

In der Zeile „Bemerkungen und Notizen“ können Sie Hinweise zu der Position speichern, beispielsweise bei Checkboxen oder Radiobuttons, wo nur ein „X“ ausgegeben wird, kann hier für die Backend-Ansicht die Option beschrieben werden.

Möchten Sie alle angekreuzten Werte in einer kommegetrennten Liste als Text anzeigen, dann geben Sie nur den Feldnamen an.

Im folgenden Teil des Backend-Formulars geht es um die Position im PDF, wo genau die gewählte Information eingetragen wird und um die Schriftattribute.

image.png

Die Position besteht aus der PDF-Seite (bezieht sich auf die Seite in der Vorlage), dem horizontalen Abstand vom linken Seitenrand und dem vertikalen Abstand vom oberen Rand. Optionell kann auch ein rechter Rand eingegeben werden. Das ist oft sinnvoll bei Formularfeldern vom Typ Textarea, wo der Zeilentext umbrechen soll. Abhängig von der verwendeten Schriftart gibt es möglicherweise eine konstante Verschiebung durch Über- und Unterlängen im Font.
Eine gute Möglichkeit, die Positionen zu ermitteln, ist das Ausmessen der PDF-Seite in Programmen, wie Photoshop. In einem Positionstest kann schnell der Versatz ermittelt und in den anderen Positionen eingerechnet werden.
Hinweis: Die Positionen beziehen sich immer auf den Grund-Offset in den Formulareigenschaften.

Beginnt eine Positionsangabe mit + oder ­-, dann wird die Position relativ zu vorigen Position platziert. Beispielsweise kann man durch Y-Position „+5“ die Ausgabe auf 5 mm unter der letzten Ausgabeposition setzen.

b) Bildposition

Für die Einbindung von Bildern in das PDF gibt es 4 Möglichkeiten:

image.png

Bei allen Bildpositionen wird die Seite, die Position und die Größe angegeben. Das Bild wird immer auf die angegebenen Maße zurecht geschnitten (MODE_CROP = Exaktes Format). Zusätzlich ist es möglich, eine Bedingung für die Einbindung anzugeben, das Bild wird dann nur eingebunden, wenn die Bedingung erfüllt ist. So lassen sich beispielsweise Bilder passend zu einem Auswahlfeld einbinden.

image.png

image.png

image.png

image.png

Contao 5.7: Jetzt ist es möglich, mit dem Datei-Upload mehrere Dateien hochzuladen. Um eine bestimmte Datei davon adressieren zu können, wird an den Feldnamen ein _0, _1, ... angehängt. Beispiel: ist der Feldname stdupload und es werden 3 Dateien hochgeladen, dann sind die Dateien unter den Feldnamen stdupload_0, stdupload_1 und stdupload_2 erreichbar.

c) Barcode

Binden Sie einen Barcode aus Ihren Daten in das PDF ein:

image.png

Folgende Barcode-Typen zur Auswahl:
(typenabhängig ist teilweise der Zeichensatz eingeschränkt)

2D-Barcodes

1D-Barcodes

Wie bei Textpositionen, können hier ver­schiedene Formulardaten, Texte und Insert­Tags verknüpft werden. Der re­sul­tierende Text wird in dem Barcode kodiert. Der Barcode wird normalerweise in der Standardfarbe ausgegeben, möchten Sie eine andere Farbe verwenden, geben Sie diese im Feld Textfarbe überschreiben an.

image.png

Darunter geben Sie die Position im PDF und die Größe des Barcodes an. Zusätzlich ist es möglich, eine Bedingung für die Einbindung anzugeben, der Barcode wird nur eingebunden, wenn die Bedingung erfüllt ist.

6. Einrichten des Mailanhangs

In den Formulareigenschaften gibt es in der Auswahl der Weiterverarbeitung die Option "PDF-Datei spiechern und an die E-Mail anhängen". Ist diese Weiterverarbeitung gewählt, wird die erzeugte Datei als Anhang mit der Mail mitgeschickt.

Bei Verwendung des Notification-Centers gibt es einen SimpleToken für das Feld „Dateianhänge via Tokens“ in der Benachrichtigung. Tragen Sie dort den Token ##form_pdfattachment## ein, um die generierte PDF-Datei anzuhängen.

7. Verzeichnisschutz, geschütztes PDF

Um direkte Downloads der PDF-Dateien, die oft personenbezogene Daten enthalten,  zu verhindern, kann das Vorlagen- und das Ablageverzeichnis in der Dateiverwaltung geschützt werden. Die Dateien sind trotzdem uneingeschränkt als Mailanhang verwendbar.

Zusätzlich kann das erstellte PDF mit einem Passwort geschützt werden. Der Schutz kann das Öffnen verhindern oder die Berechtigungen einschränken.

Anmerkung: Der PDF-Schutz ist nicht absolut sicher. Mit geeigneten Programmen kann das Passwort umgangen werden!

8. InsertTags

Die Erweiterung ersetzt InsertTags in den Positionsdaten, so dass ggf. dynamische Daten oder die Daten des angemeldeten Mitglieds verwendet werden können.

Die Erweiterung stellt auch eigene InsertTags zur Verfügung:

{{pdf_forms::pdfdocument}}

kann verwendet werden, um den Dateilink des erzeugten Dokuments in einen Download-Link einzubauen. Wenn Sie nicht das Contao-Download-Inhaltselement verwenden, muss die Datei öffentlich zugänglich sein, bei einem geschützen PDF-Verzeichnis muss der Download über das Contao-Inhaltselement erfolgen.

{{pdf_forms::pdfdocument::name}}

kann verwendet werden, um nur den Dateinamen des erzeugten Dokuments in der Antwortseite einzufügen. Das ist auch der Dateiname des PDF-Anhangs der Mail.

{{pdf_forms::password_random}}

erzeugt ein Zufalls-Passwort, z.B. als Änderungsschutz-Passwort des PDF.

{{pdf_forms::form_*}}

mit diesem InsertTag ist es möglich, übermittelte Inhalte aus einem Formularfeld, in den Formulareigenschaften im PDF-Dateinamen anzubringen. Beispielsweise eine Vorgangsnummer aus einem versteckten Tabellenfeld. 
Ersetzen Sie den * durch den Namen des Formularfeldes.

9. Für Programmierer und Entwickler

Dieser Abschnitt richtet sich an Programmierer, die in eigenen Modulen Einfluss auf diese Erweiterung nehmen wollen.

Interne Feldvariablen für PDF

Neu in der Version 2.3 sind interne Feldvariablen, die man über den pdf_formsBeforePdf-Hook eintragen kann. Diese Variablen lassen sich dann genauso verwenden, wie Formularfelder aus dem abgesendeten Formular. Für die Möglichkeit, diese Variablen auch in den Bedingungen verwenden zu können, muss ein Eintrag in der config/config.yaml erfolgen, damit diese Felder in die SELECT-Auswahl hinzugefügt werden:

# config/config.yaml

softleister_pdfforms:
    add_condition_options: [foo, bar]

Im Beispiel werden die Feldvariablen foo und bar für Bedingungen verfügbar gemacht. Nach dem Eintrag in die config.yaml-Datei muss der Symfony-Cache gelöscht/erneuert werden.

Die Variablen und deren Werte werden dann im pdf_formsBeforePdf-Hook angelegt (siehe unten).

Hooks

Im Programmablauf kann man sich an ver­schie­denen Stellen mittels einer HOOK-Registrierung einkoppeln. Die Erweiterung contao-pdfforms-bundle ruft die registrierten Hooks auf, sofern Registrierungen vor­handen sind.

Folgende Hooks sind verfügbar:

pdf_formsBeforePdf

Wird nach der Datenaufbereitung aufgerufen, bevor das PDF erstellt wird. Hier können in dem übergebenen Array $arrPDF weitere Einträge hinzugefügt oder vorhandene modifiziert werden. Der Hook muss das $arrPDF als Rückgabewert zurückgeben.

Unter 'options' gibt es bisher nur 'basename:Anzahl' für die Ausgabeformatierung von Dateinamen.

Beispiel:

// src/EventListener/Pdf_formsBeforePdfListener.php
<?php

namespace App\EventListener;

use Contao\CoreBundle\DependencyInjection\Attribute\AsHook;

#[AsHook('pdf_formsBeforePdf')]
class Pdf_formsBeforePdfListener
{
    public function __invoke(array $arrPDF)
    {
        // beliebiger Code

        // Beispiel: Hinzufügen von internen Feldvariablen
        //           Die Variablen können im PDF genauso verwendet werden, wie Formulardaten
        //           Um das Feld auch in Bedingungen zu verwenden, ist ein Eintrag in der
        //           config/config.yaml notwendig (siehe oben)

        $arrPDF['arrFields']['foo'] = ['type'=>'text', 'value'=>1,  'orig'=>'foo', 'options'=>''];
        $arrPDF['arrFields']['bar'] = ['type'=>'text', 'value'=>'', 'orig'=>'bar', 'options'=>''];


        // Beispiel: Die Textausgabe des Upload-Feldes mit dem feldnamen 'singleupload' soll
        //           den Dateinamen und 1 letztes Verzeichnis davor im PDF eintragen.
        //           Standard ist nur der Dateiname ohne Verzeichnis
        //
        //           Option: basename:Anzahl der Verzeichnisse davor

        if( isset( $arrPDF['arrFields']['singleupload'] ) ) {
          $arrPDF['arrFields']['singleupload']['options'] = 'basename:1';
        }

        return $arrPDF;
    }
}

pdf_formsPositions

Wird bei der PDF-Erstellung für jede Position im Formular aufgerufen. Hier besteht die Möglichkeit, noch Daten zu manipulieren. Die Seitennummer kann nicht verändert werden, da andernfalls die Ausgabe nicht korrekt funktioniert. Als Rückgabewert wird das übergebene und ggf. modifizierte Array $arrItem erwartet.

Beispiel:

// src/EventListener/Pdf_formsPositionsListener.php
<?php

namespace App\EventListener;

use Contao\CoreBundle\DependencyInjection\Attribute\AsHook;

#[AsHook('pdf_formsPositions')]
class Pdf_formsPositionsListener
{
    public function __invoke(array $arrItem, array $arrPDF)
    {
        // beliebiger Code
 
        return $arrItem;
    }
}

pdf_formsAfterPdf

Wird nach der Erzeugung, Speicherung und der Übergabe an die Formular­ver­arbeitung aufgerufen. Hier können weitere abschließende Aktivitäten per Hook eingefügt werden. Der Hook hat keinen Rückgabewert.

Beispiel:

// src/EventListener/Pdf_formsAfterPdfListener.php
<?php

namespace App\EventListener;

use Contao\CoreBundle\DependencyInjection\Attribute\AsHook;

#[AsHook('pdf_formsAfterPdf')]
class Pdf_formsAfterPdfListener
{
    public function __invoke(string $pdfdatei, array $arrPDF): void
    {
        // beliebiger Code
    }
}

10. Troubleshooting

Hier sind einige Punkte zusammengetragen, die zu Fehlern führen könnten:

Die PDF-Vorlage kann nicht gelesen werden

Damit das Vorlagen-PDF für den PDF-Generator lesbar ist, muss es im Format der PDF-Spezifikation 1.4 (Acrobat 5.x) vorliegen. Neuere PDF-Versionen müssen zuvor in das ältere Format konvertiert werden.
Im Adobe Acrobat auf "Speichern unter …" klicken, dann "Adobe PDF-Dateien, optimiert (*.pdf)" auswählen und in den Einstellungen dann "Acrobat 5.0 und höher" einstellen.

 

Der Text trifft nicht die richtige Stelle im Formular-PDF-Generator

Die ausgemessenen Positionen haben meist einen festen Offset, der durch die Über- und Unterlängen in den Schriftarten zustande kommen. Am einfachsten ist ein Test mit einer Position, in der man nach der Ausgabe die Abweichung von der Sollposition ermittelt. Diese Grund-Abweichung kann in den Formulareigenschaften als Grund-Offset eingetragen werden und wird dann bei der Ausgabe bei jeder Position eingerechnet.

 

Es gibt Felder, die im PDF-Formular nicht vorkommen, aber im Dokument trotzdem als Notizen ausgegeben werden sollen.

Geben Sie einfach eine zusätzliche Seitennummer an, wenn die Seite in der Vorlage nicht enthalten ist, wird eine Leerseite angefügt, wo die zusätzlichen Informationen in gleicher Weise ausgegeben werden können.