# Erweiterung contao-pdfforms-bundle (DE)

<span>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. </span>

<span>Die Erweiterung </span>**contao-pdfforms-bundle**<span> installiert sich als eingeschränkte Demo. Die Demoversion druckt bei vollem Funktionsumfang einen Demo-Hinweis in das PDF und ist auf 2 Ausgabeseiten begrenzt.</span>  
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:

- <span>Contao 5.3 ... 5.6: contao-pdfforms-bundle </span>**^2.3**
- <span>Contao 5.7 ... : contao-pdfforms-bundle </span>**^2.4**

\_\_\_\_\_\_  
Stand: Version 2.4.1 - 14.03.2026  
<span>Softleister, Dipl. Ing. Hagen Klemp, </span><info@softleister.de><span>, </span>[www.softleister.de](https://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](https://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.

<table border="1" id="bkmrk-" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>[![image.png](https://books.softleister.de/uploads/images/gallery/2026-02/scaled-1680-/0qXF3stzt1kMgQYN-image.png)](https://books.softleister.de/uploads/images/gallery/2026-02/0qXF3stzt1kMgQYN-image.png)

</td></tr></tbody></table>

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.

<table border="1" id="bkmrk--1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>[![image.png](https://books.softleister.de/uploads/images/gallery/2026-02/scaled-1680-/yVLZCSD83VOlrmiD-image.png)](https://books.softleister.de/uploads/images/gallery/2026-02/yVLZCSD83VOlrmiD-image.png)

</td></tr></tbody></table>

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:

<table border="1" id="bkmrk--2" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>[![image.png](https://books.softleister.de/uploads/images/gallery/2026-02/scaled-1680-/ObNddTHcLhdJFXSo-image.png)](https://books.softleister.de/uploads/images/gallery/2026-02/ObNddTHcLhdJFXSo-image.png)

</td></tr></tbody></table>

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.

<p class="callout danger">Anmerkung: Der PDF-Schutz ist nicht absolut sicher. Mit geeigneten Programmen kann das Passwort u.U. umgangen werden!</p>

##### Eigene Fonts verwenden:

<table border="1" id="bkmrk--3" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>[![image.png](https://books.softleister.de/uploads/images/gallery/2026-02/scaled-1680-/QTsFEIpL9WzemaWK-image.png)](https://books.softleister.de/uploads/images/gallery/2026-02/QTsFEIpL9WzemaWK-image.png)

</td></tr></tbody></table>

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.

<table border="1" id="bkmrk-" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td class="align-right">[![image.png](https://books.softleister.de/uploads/images/gallery/2026-02/scaled-1680-/wxl6gcsNKxgGmQhd-image.png)](https://books.softleister.de/uploads/images/gallery/2026-02/wxl6gcsNKxgGmQhd-image.png)

</td></tr></tbody></table>

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 <span style="text-decoration: underline;">alle Felder</span> und alle Seiten in das Test-PDF übernommen.

<table border="1" id="bkmrk--1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>[![image.png](https://books.softleister.de/uploads/images/gallery/2026-02/scaled-1680-/6S6Gb3RGeYobdbaF-image.png)](https://books.softleister.de/uploads/images/gallery/2026-02/6S6Gb3RGeYobdbaF-image.png)

</td></tr></tbody></table>

Es gibt verschiedene Typen der Positionen:

- **Textposition** - Ausgabe von Formularinhalten, Texten und InsertTags
- **Bildposition** - Ausgabe von Bilddaten
- **Barcode** - Ausgabe eines Barcodes aus Formularinhalten, Text, InsertTags

#### Anlegen der einzelnen Positionen:

##### a) Textpositionen

<table border="1" id="bkmrk--2" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>[![image.png](https://books.softleister.de/uploads/images/gallery/2026-02/scaled-1680-/LDP4krBQ1wdLpJuX-image.png)](https://books.softleister.de/uploads/images/gallery/2026-02/LDP4krBQ1wdLpJuX-image.png)

</td></tr></tbody></table>

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

- einen Feldnamen aus dem Formular
- ein fester Text in Anführungszeichen
- InsertTags müssen auch in Anführungszeichen gesetzt werden, da sie als Text verarbeitet werden sollen

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:

<table border="1" id="bkmrk--3" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>[![image.png](https://books.softleister.de/uploads/images/gallery/2026-02/scaled-1680-/hHuEwdxaUH1xxGvQ-image.png)](https://books.softleister.de/uploads/images/gallery/2026-02/hHuEwdxaUH1xxGvQ-image.png)

</td></tr></tbody></table>

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

<table border="1" id="bkmrk--4" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>[![image.png](https://books.softleister.de/uploads/images/gallery/2026-02/scaled-1680-/cYSSpo6yCX1KnOQp-image.png)](https://books.softleister.de/uploads/images/gallery/2026-02/cYSSpo6yCX1KnOQp-image.png)

</td></tr></tbody></table>

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.

<table border="1" id="bkmrk--5" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>[![image.png](https://books.softleister.de/uploads/images/gallery/2026-02/scaled-1680-/PkmRe6GR4nDtMzUG-image.png)](https://books.softleister.de/uploads/images/gallery/2026-02/PkmRe6GR4nDtMzUG-image.png)

</td></tr></tbody></table>

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:

- Ein Bild aus der Dateiverwaltung auswählen
- Ein Bild aus dem Upload, also aus dem Formular übernehmen
- Ein Bild, was als DataStream in den Formulardaten enthalten ist (z.B. aus der Unterschriften-Erweiterung [do-while/contao-signature-formfield-bundle](https://packagist.org/packages/do-while/contao-signature-formfield-bundle))
- Ein Bild über die UUID der Datei einbinden (z.B. 735e095f-a30e-11ee-9009d02fd8b3)
- Ein Bild über die Pfadangabe einbinden (z.B. files/contaodemo/media/demo-images/contao-on-blue.jpg)

<table border="1" id="bkmrk--6" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>[![image.png](https://books.softleister.de/uploads/images/gallery/2026-02/scaled-1680-/Rw1ctGNgeoPZ8q9U-image.png)](https://books.softleister.de/uploads/images/gallery/2026-02/Rw1ctGNgeoPZ8q9U-image.png)

</td></tr></tbody></table>

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.

<table border="1" id="bkmrk--7" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>[![image.png](https://books.softleister.de/uploads/images/gallery/2026-02/scaled-1680-/MUKHNDekb4mUYsl3-image.png)](https://books.softleister.de/uploads/images/gallery/2026-02/MUKHNDekb4mUYsl3-image.png)

</td><td>[![image.png](https://books.softleister.de/uploads/images/gallery/2026-02/scaled-1680-/WglkHbiFsglhGQVA-image.png)](https://books.softleister.de/uploads/images/gallery/2026-02/WglkHbiFsglhGQVA-image.png)

</td></tr><tr><td>[![image.png](https://books.softleister.de/uploads/images/gallery/2026-02/scaled-1680-/UTI8wLh1KBRsbdLV-image.png)](https://books.softleister.de/uploads/images/gallery/2026-02/UTI8wLh1KBRsbdLV-image.png)

</td><td>[![image.png](https://books.softleister.de/uploads/images/gallery/2026-03/scaled-1680-/u3HdOkS7jWvCrRef-image.png)](https://books.softleister.de/uploads/images/gallery/2026-03/u3HdOkS7jWvCrRef-image.png)

</td></tr></tbody></table>

**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:

<table border="1" id="bkmrk--8" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>[![image.png](https://books.softleister.de/uploads/images/gallery/2026-02/scaled-1680-/KWeeKLBjHfykOUSs-image.png)](https://books.softleister.de/uploads/images/gallery/2026-02/KWeeKLBjHfykOUSs-image.png)

</td></tr></tbody></table>

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

**2D-Barcodes**

- QR-Code - einfache Fehlerkorrektur
- QR-Code - mittlere Fehlerkorrektur
- QR-Code - bessere Fehlerkorrektur
- QR-Code - beste Fehlerkorrektur
- PDF417 (ISO/IEC 15438:2006)
- Datamatrix (ISO/IEC 16022:2006)

**1D-Barcodes**

- Code 39 - ANSI MH10.8M-1983 - USD-3 - 3 of 9
- Code 39 + Checksumme
- Code 39 Extended
- Code 39 Extended + Checksumme
- Code 93 – USS-93
- Standard 2 of 5
- Standard 2 of 5 + Checksumme
- Interleaved 2 of 5
- Interleaved 2 of 5 + Checksumme
- Code 128 AUTO
- Code 128 A
- Code 128 B
- Code 128 C
- EAN 8
- EAN 13
- UPC-A
- UPC-E
- 5-Ziffern UPC-Based Extension
- 2-Ziffern UPC-Based Extension
- MSI
- MSI + Checksumme (module 11)
- Codabar
- Code 11
- Pharmacode
- Pharmacode TWO-TRACKS
- IMB - Intelligent Mail Barcode - Onecode – USPS-B-3200
- Postnet
- Planet
- RMS4CC (Royal Mail 4-state Customer Code) - CBC (Customer Bar Code)
- KIX (Klant index - Customer index)

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.

<table border="1" id="bkmrk--9" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>[![image.png](https://books.softleister.de/uploads/images/gallery/2026-02/scaled-1680-/J2phJJBXjjW1eSz3-image.png)](https://books.softleister.de/uploads/images/gallery/2026-02/J2phJJBXjjW1eSz3-image.png)

</td></tr></tbody></table>

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.

<p class="callout danger">Anmerkung: Der PDF-Schutz ist nicht absolut sicher. Mit geeigneten Programmen kann das Passwort umgangen werden!</p>

# 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:

```yaml
# 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:

```php
// 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:

```php
// 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:

```php
// 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.