PDF-Generierung

Syntax

pdfFile(html: $htmlContent, name: $filename,
    pageSize: $size, landscape: $landscape,
    pageWidth: $width, pageHeight: $height,
    marginLeft: $ml, marginRight: $mr,
    marginTop: $mt, marginBottom: $mb,
    resolution: $dpi
)

Beschreibung

Konvertiert HTML-Inhalte in ein PDF-Dokument. Das HTML wird als PDF gerendert, wobei die Flying Saucer-Bibliothek verwendet wird, die hochwertige PDF-Ausgaben aus wohlgeformtem XHTML erzeugt.

Diese Funktion akzeptiert vier Arten von Eingaben:

Zeichenkette: Einfaches HTML als mehrzeiliges String-Literal (mit dreifachen Anführungszeichen """...""")
HTML: HTML mit eingebetteten TLScript-Ausdrücken (mit HTML-Literal-Syntax mit dreifachen geschweiften Klammern {{{...}}})
Strukturierter Text: Rich-Text-Inhalte aus WYSIWYG-Editor-Feldern mit eingebetteten Bildern. Bilder werden automatisch in BASE64-Daten-URIs für das PDF-Rendering konvertiert
Binärdaten: Binärdaten mit Content-Type text/html oder text/plain, die HTML-Markup enthalten

Diese Funktion ist besonders nützlich für die Erstellung von Berichten, Rechnungen oder anderen Dokumenten, die dynamisch aus HTML-Vorlagen generiert und als PDF exportiert werden müssen.

Wichtig: Das HTML muss wohlgeformtes XHTML sein. Alle Tags müssen ordnungsgemäß geschlossen werden, und selbstschließende Tags sollten die XHTML-Syntax verwenden (z.B. <br/> statt <br>).

Parameter

Bezeichnung	Typ	Beschreibung	Pflicht	Standard
html	String, HTMLFragment, StructuredText oder Binärdaten	Der HTML-Inhalt, der in PDF konvertiert werden soll. Kann ein einfacher String (mit dreifachen Anführungszeichen `"""..."""`), ein HTMLFragment (mit dreifachen geschweiften Klammern `{{{...}}}` Syntax mit eingebetteten TLScript-Ausdrücken), ein StructuredText aus WYSIWYG-Editor-Feldern (mit automatisch eingebetteten BASE64-Bildern) oder eine Binärdaten mit Content-Type `text/html` oder `text/plain` sein. Muss wohlgeformtes XHTML sein, bei dem alle Tags ordnungsgemäß geschlossen sind.	ja
name	Zeichenkette	Der Dateiname für das generierte PDF. Die Erweiterung .pdf wird automatisch hinzugefügt, falls nicht vorhanden.	nein	document.pdf
pageSize	Zeichenkette	Standard-Papierformat. Unterstützte Werte: `A0`, `A1`, `A2`, `A3`, `A4`, `A5`, `A6`, `LETTER`, `LEGAL`, `TABLOID`. Wenn angegeben, werden `pageWidth` und `pageHeight` automatisch basierend auf der Auflösung berechnet. Werte sind nicht case-sensitiv.	nein	A4 (wenn weder pageSize noch pageWidth/pageHeight angegeben)
landscape	Boolean	Wenn `true`, werden Seitenbreite und -höhe für Querformat getauscht. Funktioniert sowohl mit `pageSize` als auch mit benutzerdefinierten `pageWidth`/`pageHeight`-Werten.	nein	false
pageWidth	Zahl/Zeichenkette	Überschreibung der Seitenbreite in Pixeln oder Größenangabe wie "15cm", "150mm", "7.5in". Wenn angegeben, hat dies Vorrang vor der `pageSize`-Breite.	nein	null
pageHeight	Zahl/Zeichenkette	Überschreibung der Seitenhöhe in Pixeln oder Größenangabe wie "15cm", "150mm", "7.5in". Wenn angegeben, hat dies Vorrang vor der `pageHeight`-Höhe.	nein	null
margin	Zahl/Zeichenkette	Der linke Rand in Pixeln oder Größenangabe wie "1cm", "15mm", ".5in".	nein	"15mm"
marginLeft	Zahl/Zeichenkette	Der linke Rand in Pixeln oder Größenangabe wie "1cm", "15mm", ".5in".	nein	null
marginRight	Zahl/Zeichenkette	Der rechte Rand in Pixeln oder Größenangabe wie "1cm", "15mm", ".5in".	nein	null
marginTop	Number	Der obere Rand in Pixeln oder Größenangabe wie "1cm", "15mm", ".5in".	nein	null
marginBottom	Number	Der untere Rand in Pixeln oder Größenangabe wie "1cm", "15mm", ".5in".	nein	null
resolution	Number	Die Rendering-Auflösung in DPI (Punkte pro Zoll). Höhere Werte erzeugen bessere Qualität, aber größere Dateien. Dies beeinflusst auch, wie `pageSize`-Dimensionen berechnet werden (z.B. A4 bei 150 DPI = 1240x1754 px, A4 bei 300 DPI = 2480x3508 px).	nein	150

Rückgabewert

Typ: BinaryData

Gibt ein Binärdaten-Objekt zurück, das das generierte PDF mit dem Content-Type application/pdf enthält. Gibt null zurück, wenn die HTML-Eingabe null oder leer ist.

Wenn die PDF-Generierung fehlschlägt, wird eine RuntimeException mit Details zum Fehler ausgelöst.

Beispiele

Einfaches PDF mit aus Text

	pdfFile("""
  <html>
    <body>
      <h1>Hallo Welt</h1>
      <p>Dies ist ein aus HTML generiertes PDF.</p>
    </body>
  </html>
""")

Ausgabe: Ein PDF-Dokument mit dem Namen "document.pdf", das "Hallo Welt" als Überschrift und einen Textabsatz enthält.

PDF mit HTMLFragment und dynamischem Inhalt

	pdfFile({{{
  <html>
    <body>
      <h1>Rechnung für {$customer.get(`my.module:Customer#name`)}</h1>
      <p>Datum: {dateFormat('yyyy-MM-dd').format(now())}</p>
      <p>Betrag: {$invoice.get(`my.module:Invoice#amount`)}</p>
    </body>
  </html>
}}}, "rechnung-" + $invoice.get(`my.module:Invoice#number`))

Ausgabe: Ein PDF mit dynamisch generiertem Inhalt. Die {{{...}}} Syntax ermöglicht das Einbetten von TLScript-Ausdrücken direkt im HTML, die vor der PDF-Generierung ausgewertet und sicher HTML-kodiert werden.

PDF mit benutzerdefiniertem Dateinamen

	pdfFile("""
  <html>
    <body>
      <h1>Rechnung</h1>
      <p>Rechnung #12345</p>
    </body>
  </html>
""", "rechnung-12345")

Ausgabe: Ein PDF-Dokument mit dem Namen "rechnung-12345.pdf". Die Erweiterung .pdf wird automatisch hinzugefügt.

Gestalteter Bericht mit dynamischem Dateinamen

	pdfFile({{{
  <html>
    <head>
      <style>
        body \{ font-family: Arial, sans-serif; \}
        h1 \{ color: #333366; \}
        table \{ border-collapse: collapse; width: 100%; \}
        th, td \{ border: 1px solid #ddd; padding: 8px; \}
        th \{ background-color: #4CAF50; color: white; \}
      </style>
    </head>
    <body>
      <h1>Verkaufsbericht</h1>
      <p>Erstellt am: {dateFormat('yyyy-MM-dd').format(now())}</p>
      <table>
        <tr>
          <th>Produkt</th>
          <th>Menge</th>
        </tr>
        <tr>
          <td>Widget A</td>
          <td>150</td>
        </tr>
      </table>
    </body>
  </html>
}}}, "verkaufsbericht-" + dateFormat('yyyy-MM-dd').format(now()))

Ausgabe: Ein gestalteter PDF-Bericht mit dem Namen "verkaufsbericht-2025-10-22.pdf", einschließlich Tabelle, eingebetteter CSS-Stile und dynamischem Datum.

Dynamischer Inhalt mit Iteration

	pdfFile({{{
  <html>
    <body>
      <h1>Rechnungspositionen</h1>
      <ul>
        {$items.map(item -> {{{
          <li>{item.get(`my.module:Item#name`)} - {item.get(`my.module:Item#price`)}</li>
        }}})}
      </ul>
    </body>
  </html>
}}})

Ausgabe: Ein PDF mit einer dynamisch generierten Liste von Rechnungspositionen.

PDF aus StructuredText (WYSIWYG-Inhalt)

	// WYSIWYG-Editor-Inhalt in PDF konvertieren
pdfFile($object.get(`my.module:Article#content`), name: "artikel.pdf")

Ausgabe: Ein PDF, das aus StructuredText-Inhalt generiert wurde. Alle eingebetteten Bilder im WYSIWYG-Feld werden automatisch in BASE64-Daten-URIs konvertiert und in das PDF eingefügt.

Verwendung von Standardpapierformaten

	// US Letter Papierformat
pdfFile("""
  <html>
    <body>
      <h1>US Letter Dokument</h1>
      <p>Dieses Dokument verwendet das US Letter Papierformat.</p>
    </body>
  </html>
""", name: "letter-doc.pdf", pageSize: "LETTER")

Ausgabe: Ein PDF mit US Letter-Papierformat (216 x 279 mm) bei der Standard-Auflösung von 150 DPI.

Querformat

	// A4 Querformat für breite Inhalte
pdfFile({{{
  <html>
    <body>
      <h1>Breiter Bericht</h1>
      <table style="width: 100%">
        <tr>
          <th>Spalte 1</th>
          <th>Spalte 2</th>
          <th>Spalte 3</th>
          <th>Spalte 4</th>
          <th>Spalte 5</th>
        </tr>
      </table>
    </body>
  </html>
}}}, name: "breiter-bericht.pdf", pageSize: "A4", landscape: true)

Ausgabe: Ein PDF im A4-Querformat (297 x 210 mm), ideal für breite Tabellen oder Diagramme.

Benutzerdefinierte Seitengröße und Auflösung

	// US Letter-Format bei 200 DPI mit benutzerdefinierten Rändern
pdfFile("""
  <html>
    <body>
      <h1>Hochqualitativer Bericht</h1>
      <p>Dieses Dokument wird mit höherer Auflösung gerendert.</p>
    </body>
  </html>
""", name: "bericht.pdf", pageSize: "LETTER", resolution: 200,
    marginLeft: 100, marginRight: 100, marginTop: 100, marginBottom: 100)

Ausgabe: Ein PDF mit US Letter-Seitengröße bei 200 DPI und 100-Pixel-Rändern auf allen Seiten.

Minimale Ränder für maximalen Inhalt

	// A4 mit minimalen Rändern
pdfFile({{{
  <html>
    <body>
      <h1>Ganzseitiger Inhalt</h1>
      <p>Dies verwendet minimale Ränder, um den Inhaltsbereich zu maximieren.</p>
    </body>
  </html>
}}}, name: "vollseite.pdf", pageSize: "A4",
    marginLeft: 20, marginRight: 20, marginTop: 20, marginBottom: 20)

Ausgabe: Ein PDF mit A4-Seitengröße und minimalen 20-Pixel-Rändern (ca. 3,4mm bei 150 DPI).

Großformate mit A3

	// A3 für große Diagramme
pdfFile({{{
  <html>
    <body>
      <h1>Architekturdiagramm</h1>
      <!-- Großer Diagramminhalt -->
    </body>
  </html>
}}}, name: "diagramm.pdf", pageSize: "A3")

Ausgabe: Ein PDF mit A3-Seitengröße (297 x 420 mm), geeignet für große Diagramme oder Poster.

Technische Hinweise

Standardeinstellungen: Standard-Seitengröße ist A4 (1240x1754 Pixel bei 150 DPI = 210mm x 297mm)
Standardpapierformate: Der pageSize-Parameter unterstützt A0 bis A6 sowie LETTER, LEGAL und TABLOID. Dimensionen werden automatisch basierend auf der Auflösung berechnet
Querformat: Bei landscape: true werden Breite und Höhe getauscht. Dies funktioniert unabhängig davon, ob pageSize oder benutzerdefinierte Dimensionen verwendet werden
Auflösung: Standardauflösung ist 150 DPI, geeignet für die meisten Druck- und Bildschirmansichten. Höhere Werte (z.B. 300 DPI) erzeugen bessere Qualität, aber größere Dateien
Ränder: Standardränder sind 15mm (links, rechts, oben) und 10mm (unten). Ränder werden in Pixeln bei der gewählten Auflösung angegeben
Seitengrößenberechnungen:
- A4 bei 150 DPI: 1240 x 1754 Pixel
- US Letter bei 150 DPI: 1275 x 1650 Pixel
- A4 bei 300 DPI: 2480 x 3508 Pixel
- Formel: Pixel = (Millimeter / 25,4) × DPI
CSS-Unterstützung: Grundlegende CSS2-Stile werden unterstützt. Komplexe CSS3-Features werden möglicherweise nicht korrekt gerendert
Bilder: Externe Bilder benötigen zugängliche URLs. Base64-kodierte Bilder werden unterstützt
Schriftarten: Standardschriftarten sind verfügbar. Benutzerdefinierte Schriftarten erfordern möglicherweise zusätzliche Konfiguration
Benannte Parameter: Verwenden Sie benannte Parameter für mehr Klarheit (z.B. pageSize: "A4", landscape: true). Dies vermeidet das Angeben von null für ungenutzte Positionsparameter