Wie gestalte ich ein dynamisches PDF-Dokument?

Cloudrexx ermöglicht die Erzeugung eines PDF-Dokuments von einer beliebigen URL der Website oder eines PDF-Anhangs zu einer E-Mail-Vorlage.

Für die Erzeugung eines PDF-Dokuments verwendet Cloudrexx die Open Source Bibliothek mPDF von Ian Back. Beachten Sie, dass dieser Artikel nur einen Teil der sehr umfangreichen Funktionspalette der zugrundeliegenden mPDF-Bibliothek abdeckt. Für weitere, in diesem Artikel nicht behandelte Gestaltungsmöglichkeiten wird auf die offizielle Dokumentation von mPDF verwiesen. Bei der Durchsicht der offiziellen mPDF-Dokumentation ist zu beachten, dass Cloudrexx nur die Verwendung von HTML control tags unterstützt. mPDF functions und mPDF Variables stehen nicht zur Verfügung, mit Ausnahme wenn die PDF-Generierung im Kontext eines individuellen Moduls eingesetzt wird.

Nachfolgend sind die häufigst verwendeten Gestaltungsmöglichkeiten bei der Erstellung von PDF-Dokumenten beschrieben:

1 Kopf- und Fusszeilen
- 1.1 Definition
  - 1.1.1 Beispiel
- 1.2 Integration
  - 1.2.1 HTML
    - 1.2.1.1 Beispiel
  - 1.2.2 CSS
    - 1.2.2.1 Beispiel
2 Seitennummerierung
3 Seitenränder
- 3.1 Beispiele
- 3.2 Referenzen
4 Seitenumbrüche
- 4.1 Referenzen
5 Seitengrösse & Ausrichtung
- 5.1 Beispiele
- 5.2 Seitengrösse zurücksetzen
- 5.3 Referenzen
6 Doppelseitige Dokumente
- 6.1 Ränder
- 6.2 Kopf- und Fusszeilen
7 Schriftarten
8 Inhaltsverzeichnis
- 8.1 Referenzen
9 Feindruck
- 9.1 Beispiel
- 9.2 Referenzen

Kopf- und Fusszeilen

Kopf- und Fusszeilen können wie folgt integriert werden:

Zuerst müssen die Kopf- und Fusszeilen definiert werden (unter Verwendung von <htmlpageheader> und <htmlpagefooter>).
Anschliessend können die definierten Kopf- und Fusszeilen entweder mit CSS (@page {header: ... / footer: ...}) oder HTML (<sethtmlpageheader> und <sethtmlpagefooter>) in das PDF-Dokument eingebunden werden.

Definition

Kopf- und Fusszeilen werden mit den speziellen HTML-Tags <htmlpageheader> und <htmlpagefooter> definiert. Jeder Kopf-/Fusszeile wird durch ihr name-Attribut identifiziert. Das Layout und der Inhalt einer Kopf-/Fusszeile werden durch den Inhalt des <htmlpageheader>- / <htmlpagefooter>-Tags bestimmt. Sie können so viele Kopf-/Fusszeilen definieren, wie Sie benötigen. Das bedeutet, dass Sie eine andere Kopf-/Fusszeile für die erste Seite oder unterschiedliche Kopf-/Fusszeilen für gerade und ungerade Seiten definieren können (siehe Doppelseitige Dokumente). Weiters können Kopf-/Fusszeilen auf jeder Seite geändert werden. Zudem kann auch fürs Inhaltsverzeichnis (siehe <tocpagebreak>) eine benutzerdefinierte Kopf-/Fusszeile definiert werden.

<htmlpageheader name="NAME">
  CONTENT
</htmlpageheader>

<htmlpagefooter name="NAME">
  CONTENT
</htmlpagefooter>

Verwendung wie folgt:

Ersetzen Sie NAME durch eine Textzeichenfolge, die zur Identifizierung der Kopf-/Fusszeile verwendet wird
Ersetzen Sie CONTENT durch den HTML-Inhalt, der als Kopf-/Fusszeile verwendet werden soll

Benennen Sie keine Kopf- oder Fusszeile mit dem Anfang html_. Dieses Präfix ist reserviert, um eine HTML-Kopf-/Fusszeile zu identifizieren, wenn deren Name in einer Referenz angegeben wird.

Die Tags <htmlpageheader> und <htmlpagefooter> müssen innerhalb des <body>-Tags definiert werden.

Beispiel

Die folgende Kopfzeile wird die aktuelle Seitennummer (aus {PAGENO} entnommen) anzeigen und wird unter dem Namen myHeader identifiziert.

Beachten Sie, dass der folgende Code noch keine Kopfzeile ausgibt. Es handelt sich nur um eine Kopfzeilen-Definition, die später mit HTML (<sethtmlpageheader>) oder CSS (@page {header: myHeader}) eingefügt werden kann.

<htmlpageheader name="myHeader">
  <div>{PAGENO}</div>
</htmlpageheader>

Integration

Definierte Kopf-/Fusszeilen (unter Verwendung von <htmlpageheader> / <htmlpagefooter>) können entweder mit HTML oder CSS auf einer Seite integriert werden. Bitte beziehen Sie sich auf die offizielle Dokumentation von <htmlpageheader> und <htmlpagefooter> für fortgeschrittene Anwendungen.

HTML

Die speziellen HTML-Tags <sethtmlpageheader> und <sethtmlpagefooter> können verwendet werden, um definierte Kopf-/Fusszeilen auf einer Seite zu integrieren, indem sie über das name-Attribut verwiesen werden:

<sethtmlpageheader name="NAME" page="PAGE" value="VALUE" show-this-page="SHOW-THIS-PAGE" />

<sethtmlpagefooter name="NAME" page="PAGE" value="VALUE" show-this-page="SHOW-THIS-PAGE" />

Verwendung wie folgt:

Ersetzen Sie NAME durch die zu integrierende Kopf-/Fusszeile
Ersetzen Sie PAGE durch eines der Wörter ODD, EVEN oder ALL, um sie nur auf ungeraden oder geraden Seiten, oder auf allen Seiten zu verwenden (siehe Doppelseitige Dokumente)
Ersetzen Sie VALUE entweder durch ON oder OFF, um die Kopf-/Fusszeile zu aktivieren oder zu deaktivieren
Ersetzen Sie SHOW-THIS-PAGE durch 1, um die Kopf-/Fusszeile auch auf der aktuellen Seite anzuzeigen (und nicht erst nach dem nächsten Seitenwechsel)

Für eine vollständige Übersicht zu den Einsatzmöglichkeiten, siehe die offizielle Dokumentation von <sethtmlpageheader> und <sethtmlpagefooter>.

Beispiel

Verwenden Sie die definierte Kopfzeile myHeader auf jeder Seite unseres PDF-Dokuments:

<sethtmlpageheader name="myHeader" value="on" show-this-page="1" />

Das Attribut value="on" aktiviert die Kopfzeile auf allen Seiten nach dem nächsten Seitenwechsel. Das Attribut show-this-page="1" zwingt das System, die Kopfzeile auch auf der aktuellen Seite einzufügen (was die erste Seite des zu generierenden PDF-Dokuments sein könnte).

CSS

Die Eigenschaften header und footer können verwendet werden, um die Integration der definierten Kopf- und Fusszeilen im Kontext einer @page-Regel zu konfigurieren.

Dies geschieht, indem der Wert von header / footer auf den Namen einer zuvor definierten Kopf-/Fusszeile (unter Verwendung von <htmlpageheader> / <htmlpagefooter>) gesetzt wird, vorangestellt von html_.

Setzen Sie den Wert auf _blank (oder einen Namen, der nicht definiert wurde), um Kopf-/Fusszeilen auszuschalten.

Beispiel

Verwenden Sie die definierte Kopfzeile myHeader auf jeder Seite unseres PDF-Dokuments:

@page {
  header: html_myHeader;
}

Beachten Sie, dass der Name der Kopfzeile mit html_ vorangestellt werden muss. Für weitere Informationen zur Verwendung siehe die offizielle Dokumentation der @page-Regel.

Seitennummerierung

Die folgenden Platzhalter im Zusammenhang mit der Seitennummerierung können innerhalb von Kopf- und Fusszeilen verwendet werden:

Platzhalter	Beschreibung

Platzhalter	Beschreibung
`{PAGENO}`	Gesamtanzahl der Seiten
`{nb}`	Gesamtanzahl der Seiten
`{nbpg}`	Anzahl der Seiten der aktuellen Gruppe, falls sie mit `<pagebreak resetpagenum="1">` zurückgesetzt wurde.

Für weitere Informationen siehe die offizielle Dokumentation auf Englisch:

Seitenränder

Seitenränder können mit CSS mit der margin-Eigenschaft im Kontext einer @page-Regel eingestellt werden.

Zusätzlich werden bei Verwendung von Kopf- und Fusszeilen die Eigenschaften margin-header und margin-footer verwendet, um den Abstand zwischen dem oberen Rand einer Seite und dem Beginn einer Kopfzeile bzw. dem unteren Rand einer Seite und dem Ende einer Fusszeile festzulegen.

Beispiele

Einen Rand von 1cm einstellen::

@page {
  margin: 1cm;
}

Individuelle Ränder einstellen:

@page {
  margin-top: 3cm;
  margin-bottom: 1cm;
  margin-left: 2cm;
  margin-right: 1cm;
}

Der obere und untere Rand (margin-top und margin-bottom) kann für gerade und ungerade Seiten unterschiedlich eingestellt werden (siehe Doppelseitige Dokumente) und kann auch innerhalb des Dokuments zurückgesetzt werden. Andererseits können der linke und rechte Rand (margin-left und margin-right) nur einmal gesetzt werden (für das gesamte Dokument). Bei doppelseitigen Dokumenten werden sie auf geraden Seiten gespiegelt.

Referenzen

Für ein ganzheitliches Verständnis zu Seitenränder, siehe die offizielle Dokumentation auf Englisch:

Seitenumbrüche

Seitenumbrüche können mit den speziellen HTML-Tags <pagebreak> und <formfeed> oder durch Verwendung der CSS-Eigenschaften page-break-before und page-break-after hinzugefügt werden.

Referenzen

Für ein ganzheitliches Verständnis zu Seitenumbrüche, siehe die offizielle Dokumentation auf Englisch:

Seitengrösse & Ausrichtung

Die anfängliche Seitengrösse kann mit der size-Eigenschaft im Kontext einer @page-Regel festgelegt werden.

Beispiele

Seitengrösse auf A4 Hochformat einstellen:

@page {
  size: 210mm 297mm;
}

Seitengrösse auf A4 Querformat einstellen:

@page {
  size: 297mm 210mm;
  }

Seitengrösse zurücksetzen

Die Seitengrösse kann innerhalb des Dokuments entweder wieder mit der size-Eigenschaft im Kontext einer @page-Regel oder mit einem der speziellen HTML-Tags, die Seitenumbrüche behandeln (<pagebreak> / <tocpagebreak>), zurückgesetzt werden.

Referenzen

Für ein ganzheitliches Verständnis zu Seitengrössen, siehe die offizielle Dokumentation auf Englisch:

Doppelseitige Dokumente

Doppelseitige Dokumente können erstellt werden. Dies ermöglicht individuelles Layout (Kopf-/Fusszeilen/Ränder) für ungerade und gerade Seiten.

Standardmässig wird das generierte PDF-Dokument als einseitiges Dokument erstellt. Um ein doppelseitiges Dokument zu generieren, registrieren Sie einfach die :left- und :right-Selektoren für die @page-Regel:

@page :left, @page :right {}

Der Kontext der @page-Regel kann leer bleiben.

Die erste Seite im generierten PDF-Dokument gilt als ungerade Seite und erscheint als rechte Seite in einem LTR-Dokument (oder als linke Seite in einem RTL-Dokument).

Ränder

Bei doppelseitigen Dokumenten werden die linken und rechten Ränder auf geraden Seiten gespiegelt. Das bedeutet, dass der linke Rand (margin-left) auf einer rechten (ungeraden) Seite dem rechten Rand auf einer linken Seite entspricht und umgekehrt für den rechten Rand (margin-right).

Kopf- und Fusszeilen

Verschiedene Kopf- und Fusszeilen können für ungerade (odd) und gerade (even) Seiten definiert werden.

In CSS wird dies mit den Eigenschaften odd-header-name, even-header-name, odd-footer-name und even-footer-name im Kontext einer @page-Regel erreicht.

In HTML wird dies mit dem PAGE-Attribut der Tags <sethtmlpageheader> und <sethtmlpagefooter> gemacht.

Schriftarten

Die Standard-Schriftart, die bei der Erstellung eines PDF-Dokuments verwendet wird, ist DejaVu (DejaVuSerifCondensed). Neben dieser sind mehrere Variationen verfügbar (DejaVuSans / DejaVuSansCondensed / DejaVuSerif / DejaVuSansMono), sowie eine weitere generische Schriftart, die GNU FreeFont (FreeSans / FreeSerif / FreeMono). Darüber hinaus stehen auch mehrere nicht-lateinische Schriftarten zur Verfügung. Die vollständige Liste der verfügbaren Schriftarten finden Sie in der Available fonts v6 and v7.

Eigene Schriftarten werden ebenfalls unterstützt und können wie folgt eingebunden werden:

Platzieren Sie Ihre benutzerdefinierten TrueType^[1]-Schriftartdateien im Verzeichnis /media/Pdf/ttfonts/ (via FTP).
Die Schriftart muss wie folgt benannt werden, um als solche erkannt zu werden:
- MyFont-Regular.ttf
- MyFont-Bold.ttf
- MyFont-Italic.ttf
- MyFont-BoldItalic.ttf
Binden Sie Ihre benutzerdefinierte Schriftart wie folgt ein:
Inline CSS:
<p style="font-family: MyFont;">Text in MyFont</p>
CSS:
font-family: MyFont;

Im Gegensatz zu HTML skalieren Boxen in mPDF den Text, anstatt den überlaufenden Teil abzuschneiden. Wenn eine Änderung der Schriftgrösse keine Wirkung zeigt, könnte dies bedeuten, dass die Box, die den Text enthält, zu klein für die gewählte Schriftgrösse ist.

^[1]Kashida and OTF are not supported yet.

Inhaltsverzeichnis

Ein automatisch generiertes Inhaltsverzeichnis kann mit dem speziellen HTML-Tag <tocpagebreak> eingefügt werden. Das Inhaltsverzeichnis unterstützt benutzerdefinierte Kopf- und Fusszeilen mit den Attributen toc-odd-header-name, toc-even-header-name, toc-odd-footer-name und toc-even-footer-name. Darüber hinaus unterstützt es eine benutzerdefinierte Seitengrösse und -ausrichtung durch Verwendung der Attribute toc-sheet-size und toc-orientation.

Einträge für das Inhaltsverzeichnis können mit dem speziellen HTML-Tag <tocentry> hinzugefügt werden.

Referenzen

Für ein ganzheitliches Verständnis, siehe die offizielle Dokumentation auf Englisch:

Feindruck

Registrier- und/oder Schnittmarken können mit der marks-Eigenschaft im Kontext einer CSS @page-Regel hinzugefügt werden. Wenn Sie Marken verwenden, nutzen Sie die Eigenschaft size, um die Grösse der Seitenbox zu definieren, und die Eigenschaft sheet-size, um die Grösse des Blattes festzulegen.

Beispiel

Registrier- und Schnittmarken zu einem A4-Querformatdokument hinzufügen, das auf A3-Querformatblättern gedruckt werden soll:

@page {
  marks: crop || cross;
  size: 297mm 210mm;
  sheet-size: A3-L;
}

Referenzen

Für ein ganzheitliches Verständnis, siehe die offizielle Dokumentation auf Englisch: