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: Contao 5.3 ... 5.6: contao-pdfforms-bundle ^2.3Contao 5.7 ... : contao-pdfforms-bundle ^2.4 ______Stand: Version 2.4.1 - 14.03.2026Softleister, 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. 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.  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: 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: 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. 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. 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 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: 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 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. 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 ) 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) 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. 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: Folgende Barcode-Typen zur Auswahl: (typenabhängig ist teilweise der Zeichensatz eingeschränkt) 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. 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 '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