Druck (PDF)¶

KCForms erzeugt zu jedem Datensatz ein PDF — über das Drucker-Symbol in der Werkzeugleiste (Strg+P), eine Schaltfläche mit scriptHook: "printForm" oder im Skript mit pdf.render(...). Der Renderer baut auf Apache PDFBox auf und übersetzt das Schema ins Druckstück; die PDFs sind barrierefrei (PDF/UA).

Was du an diesem Druckstück gestalten kannst:

Titel, Autor, Stichwörter und Sprache des Dokuments festlegen — das, was der PDF-Reader unter Datei → Eigenschaften zeigt.
Seiten anlegen, mit Format (A4, A3, Letter …), Hoch- oder Querformat und eigenen Rändern.
Kopf- und Fußzeilen gestalten — Logo, Firmenanschrift, Seitenzahl, Druckdatum; auf Wunsch zentral als Druckvorlage für viele Formulare.
Rahmen und Hervorhebungen um Feldwerte setzen.
bestimmen, was gar nicht gedruckt wird — dauerhaft oder abhängig von einer Bedingung.
steuern, was mit zu langem Text passiert: umbrechen, abschneiden, verkleinern oder als Anlage ans Dokumentende hängen.
Ausdruck und PDF-Anlagen eines Datensatzes zu einem Sammel-PDF zusammenfassen.

Zusammenklicken reicht — das JSON ist zum Nachschauen da

Den ganzen Druck richtest du im Formular-Editor ein, ohne eine Zeile zu tippen: Dokumentangaben, Seiten, Kopf- und Fußzeilen und das Verhalten bei langem Text stehen in den Formular-Eigenschaften, die Einstellungen einzelner Felder in deren Eigenschaften-Dialog. Die eingeklappten Kästen „Hinter den Kulissen" auf dieser Seite zeigen, was der Editor dabei in das Formular schreibt. Das ist nützlich, wenn du ein Druckbild in ein anderes Formular übernehmen oder herausfinden willst, warum ein Ausdruck anders aussieht als erwartet — zum Arbeiten brauchst du es nicht.

Wie das Formular aufs Papier kommt¶

Ohne weitere Einstellungen druckt KCForms fließend: Die Inhalte laufen in Schema-Reihenfolge von oben nach unten über die Seiten. Dabei gilt:

Einspaltiges Layout (vertical): Beschriftung links, Wert rechts.
Raster (horizontal-2/-3): Beschriftung oben, Wert darunter; ein Feld kann mit kc:colspan mehrere Spalten überspannen.
Detail-Tabellen (kc:childTable) werden zu einer eigenen Tabelle mit Spaltenköpfen — im Block-Modus stattdessen zu Blöcken.
Leittexte (kc:text) werden zu Überschrift bzw. Absatz, Abschnitte (kc:section) zu einer Abschnittsüberschrift.
Bilder (kc:image) werden eingebettet, Grafiken (kc:svg) in ein Bild umgerechnet, Platzhalter (kc:spacer) bleiben leere Zellen.
Links und Schaltflächen (kc:link, kc:button) erscheinen nicht im PDF — auf Papier hätten sie keine Funktion.

Für millimetergenaue Druckbilder gibt es die Layout-Modi Hybrid und Absolut — siehe Absolute Druckpositionen.

Wo pflege ich das?¶

Im Formular-Editor in den Formular-Eigenschaften (Knopf Formulareigenschaften bearbeiten über der Vorschau):

Abschnitt	Inhalt
Druck (Dokumenteigenschaften und Darstellung)	PDF-Metadaten (Titel, Autor, Betreff, Stichwörter), Dokumentsprache, Druck-Stilklassen, Standard-Rahmen um Feldwerte, Standard-Hervorhebung, Rahmen in Detail-Tabellen
Seiten	Seiten mit Format, Ausrichtung und Rändern
Kopf- und Fußzeilen (Druck und Web-Darstellung)	Kopf- und Fußzeile des Formulars oder eine zentrale Druckvorlage
Layout-Modus / Text passt nicht in seine Spalte (oben)	Fließend/Hybrid/Absolut; Formular-Standard für Textüberlauf

Pro Feld: Eigenschaften-Dialog, Reiter Format (Überlauf, Hervorhebung) und Sichtbarkeit (Im PDF erscheinen = kc:printable).

Titel, Autor und Sprache des PDFs¶

title, author, subject und keywords landen in den Dokumenteigenschaften des PDFs (im PDF-Reader unter Datei → Eigenschaften); Makros sind darin erlaubt, der Titel darf also die Bestellnummer des Datensatzes enthalten. lang ist die Dokumentsprache — ohne Angabe gilt die Druck- bzw. Empfängersprache.

Hinter den Kulissen: Dokument-Eigenschaften (kc:document)

"kc:document": {
  "title":    "Bestellung ${value:bestellnr}",
  "author":   "${user:firstName} ${user:lastName}",
  "subject":  "B2B-Bestellung",
  "keywords": "bestellung, b2b",
  "lang":     "de"
}

Weitere Schlüssel in kc:document: layoutMode, printOverflow, header, footer, headerRef, footerRef (siehe unten). Alle Druck-Einstellungen des Formulars sammeln sich also an einer Stelle.

Seiten, Format und Ränder¶

Jede Seite, die du im Abschnitt Seiten anlegst, bekommt eine Bezeichnung und darf ihr eigenes Papierformat, ihre eigene Ausrichtung und eigene Ränder haben — eine Übersicht hochkant, die Anlagen quer.

Hinter den Kulissen: zwei Seiten, hoch und quer (kc:pages)

"kc:pages": [
  { "id": "uebersicht", "title": "Übersicht", "format": "A4", "orientation": "portrait",
    "margins": { "top": 20, "right": 20, "bottom": 20, "left": 20 } },
  { "id": "anlagen", "title": "Anlagen", "format": "A4", "orientation": "landscape" }
]

Jedes Feld trägt mit "kc:page": "<seiten-id>", auf welche Seite es gehört.

Format	Größe (mm)	Größe (pt)
A3	297 × 420	842 × 1191
A4	210 × 297	595 × 842
A5	148 × 210	420 × 595
Letter	215,9 × 279,4	612 × 792
Legal	215,9 × 355,6	612 × 1008

Bei orientation: "landscape" werden Breite und Höhe getauscht. Ränder stehen in Millimetern; fehlt ein Wert, gilt ca. 21 mm (60 pt). Sehr knappe Ränder (< 10 mm) sind erlaubt, drucken aber je nach Drucker unsauber.

Ohne kc:pages druckt KCForms eine A4-Hochformat-Seite. Felder ohne kc:page oder mit einer unbekannten Seiten-ID landen auf der ersten Seite — so geht beim Umbenennen einer Seite nichts verloren. Dieselben Seiten steuern im Web die Tabs; Details unter Seiten. Weitere Maße einer Seite (Kopf-/Fußbereich u. a.) öffnet ein Doppelklick auf den Seiten-Tab im Formular-Editor.

Kopf- und Fußzeilen¶

Kopf- und Fußzeile bestehen aus drei Feldern — links, Mitte, rechts — und erscheinen auf jeder PDF-Seite, auf Wunsch auch im Web-Formular. Jedes der drei Felder nimmt entweder einen Text oder ein Bild auf: links das Logo, in der Mitte der Formulartitel, rechts das Druckdatum; in der Fußzeile etwa Firmenanschrift, Seitenzahl und Druckdatum.

Hinter den Kulissen: Kopfzeile mit Logo, Fußzeile mit Seitenzahl

"kc:document": {
  "header": {
    "heightMm": 18,
    "separator": true,
    "showInForm": true,
    "showOnFirstPage": true,
    "left":   { "type": "image", "src": "logo.svg", "widthMm": 12, "heightMm": 12 },
    "center": { "type": "text", "content": "${form:info.title}", "size": 13, "bold": true },
    "right":  null
  },
  "footer": {
    "heightMm": 16,
    "separator": true,
    "left":   { "type": "text", "content": "Muster GmbH · Musterstraße 1\nAmtsgericht Musterstadt HRB 12345", "size": 7, "lineSpacing": 1.2 },
    "center": { "type": "text", "content": "${i18n:page} ${document:page} ${i18n:of} ${document:pages}", "size": 9, "showInWeb": false },
    "right":  { "type": "text", "content": "${i18n:printDate}: ${date(dd.MM.yyyy)|now}", "size": 9 }
  }
}

Ein nicht belegtes Feld steht als null da (hier right in der Kopfzeile).

Die einzelnen Einstellungen:

Schlüssel	Bedeutung
`heightMm`	Höhe des Bands
`separator`, `separatorStyle`	Trennlinie zum Inhalt (`strong` = kräftiger)
`showInForm`	Band auch im Web-Formular zeigen
`showOnFirstPage`	Kopfzeile auch auf Seite 1
`left` / `center` / `right`	Inhalt: `type: "text"` (mit `content`, `size`, `bold`, `lineSpacing`; `\n` für weitere Zeilen) oder `type: "image"` (`src`, `widthMm`, `heightMm`)
`showInWeb: false` (am Feld)	dieses Feld nur im PDF (z. B. Seitenzahl)

Seitenzahlen, Druckdatum und Sprachwörter liefern die Makros ${document:page}, ${document:pages}, ${date|now} und ${i18n:…}. Ein Text als Wert ("footer": "Seite ${document:page}") funktioniert weiterhin als einfache Fußzeile.

Druckvorlagen¶

Kopf- und Fußzeilen, die viele Formulare teilen (Briefkopf, Pflichtangaben), pflegst du zentral unter System-Administration → Formular-Bausteine → Druckvorlagen: Name, Beschreibung, Schrift, Kopf- und Fußzeile, „Im Web-Formular anzeigen", aktiv ja/nein. Im Formular wählst du die Vorlage im Abschnitt Kopf- und Fußzeilen aus (kc:document.headerRef / footerRef). Eine lokale Kopf- oder Fußzeile am Formular hat Vorrang vor der Vorlage. Ändert sich die Vorlage, ändert sich der Druck aller Formulare, die sie nutzen.

Rahmen und Hervorhebung¶

Einstellung	Schlüssel	Wirkung
Standard-Rahmen um Feldwerte	`kc:pdfFieldBorders`	Kästen um die Werte (Standard an)
Standard-Hervorhebung aller Felder	`kc:printHighlightDefault`	stärkerer Rahmen, hellblau oder hellgrau gefüllt
Rahmen in Detail-Tabellen	`kc:pdfChildBorders`	dünne Rahmen um jede Tabellenzelle (Standard aus)
Im Druck hervorheben (am Feld)	`kc:printHighlight`	Hervorhebung für ein einzelnes Feld
Druck-Stilklassen	`kc:printStyleClasses`	benannte Schrift-/Farbstile für das Absolut-Layout

Den Rahmen bekommt alles, was ein Eingabefeld ist — auch Mehrfachauswahl und Stichwortlisten. Ohne Rahmen bleiben nur die Felder, die ihre eigene Darstellung mitbringen: Ankreuzfelder (die zeichnen ihr Kästchen, ein Rahmen darum wäre ein Kasten im Kasten), Options- und Mehrfach-Ankreuzgruppen sowie Leittexte, Bilder und Schaltflächen.

Ankreuzfelder¶

Ein Ankreuzfeld erscheint im PDF als gezeichnetes Kästchen, nicht als Wort:

Zustand	Im PDF
angekreuzt	ausgefülltes Quadrat
nicht angekreuzt	leeres Quadrat
dreiwertig und unentschieden (`kc:nullable`)	Quadrat mit Querstrich

Der Querstrich beim dritten Fall ist Absicht: Ein leeres Kästchen wäre die Aussage „nicht angekreuzt“ — und die hat niemand getroffen.

Warum gezeichnet und nicht als Zeichen ☐

Die Kästchen-Zeichen fehlen in den meisten Schriften. Von den fünf mitgelieferten hat keine das angekreuzte Quadrat und nur eine das leere. Welche Schrift gilt, hängt am Theme — ein Zeichen wäre also je nach Installation unsichtbar. Gezeichnete Linien sind davon unabhängig.

Was wird nicht gedruckt?¶

Felder mit kc:printable: false (Editor: Im PDF erscheinen aus).
Felder, deren kc:printableIf nicht zutrifft — Bedingungen wie bei Sichtbarkeit, @Regeln erlaubt.
kc:link, kc:button.

Lange Inhalte im fließenden Druck¶

Reicht der Platz auf einer Seite nicht, beginnt der Renderer automatisch eine Folgeseite („ (Forts. n)") und setzt dort fort. Dabei geht kein Inhalt verloren:

Feldwerte, Textbereiche und Leittext-Absätze (auch HTML-Leittexte) laufen zeilenweise über so viele Seiten wie nötig.
Wörter ohne Leerzeichen, die breiter sind als die Spalte (lange Links, Aktenzeichen), werden an der Spaltenkante getrennt.
Detail-Tabellen: Eine Zeile, die höher ist als eine ganze Seite, wird über Seiten geteilt; der Tabellenkopf steht auf jeder Folgeseite.
Detail-Tabellen im Block-Modus: Ein Block, der höher ist als eine Seite, wird geteilt; der Blocktitel erhält auf der Folgeseite „(Fortsetzung)".
Bilder, SVGs und Unterschriften springen als Ganzes auf die nächste Seite, wenn sie nicht mehr passen. Ein Bild, das höher ist als eine ganze Seite, wird proportional auf die Seitenhöhe verkleinert.

Kürzere Blöcke (ein Absatz, eine Tabellenzeile, ein Block), die auf eine Seite passen, bleiben zusammen und wandern bei Bedarf geschlossen auf die Folgeseite.

Damit der Ausdruck lesbar bleibt:

Überschriften (Abschnitte, Leittext-Überschriften, Gruppenlegenden) stehen nie allein am Seitenende — das erste Feld danach kommt mit auf die Seite.
Läuft ein Feldwert auf die Folgeseite, steht dort „ (Fortsetzung)".
Detail-Tabellen wiederholen auf jeder Folgeseite ihren Titel mit „(Fortsetzung)" und den Tabellenkopf.
Kästen und Rahmen (Feldwerte, Feldgruppen mit Rahmen) werden je Seite gezeichnet und nicht weggelassen, wenn der Inhalt über eine Seite läuft.

Wenn der Text nicht in die Spalte passt¶

Standardmäßig bricht der fließende Druck um: Feldwerte, Beschriftungen, Überschriften, Abschnittstitel, Spalten und Spaltentitel von Detail-Tabellen werden so hoch, wie ihr Inhalt es verlangt. Im 2- und 3-Spalten-Raster wird die ganze Zeile so hoch wie das höchste Feld; die Nachbarfelder bleiben in ihrer Spalte.

Im Formular-Editor stellst du das in den Feld-Eigenschaften im Reiter Format unter „Druck: Wenn der Text nicht passt" ein, für Tabellenspalten direkt in der Spaltenzeile der Detail-Tabelle, und den Formular-Standard in den Formular-Eigenschaften (Text passt nicht in seine Spalte (Druck)). Im Schema lautet der Schlüssel kc:printOverflow:

Wert	Wirkung
(leer)	Formular-Standard `kc:document.printOverflow`, sonst umbrechen
`grow`	umbrechen (auch `continue` wirkt im Fluss so)
`clip`	eine Zeile, am Spaltenende mit „…" abgeschnitten
`shrink`	Schrift bis `kc:printOverflowMinSizePt` (Standard 7 pt) verkleinern, bis der Wert in eine Zeile passt; reicht das nicht, gilt `kc:printOverflowThen` (`grow` = umbrechen, `clip`, `annex`)
`annex`	erste Zeile mit „… Fortsetzung siehe Anlage n", der volle Text als Anlage am Dokumentende

Für Spalten von Detail-Tabellen bleibt der ältere Schalter kc:pdfWrap gültig: true bricht um, false schneidet ab. kc:printOverflow hat Vorrang.

Positionierte Felder (Absolut- und Hybrid-Modus) werden unter Absolute Druckpositionen beschrieben; dort ist der Standard das bisherige Überdrucken.

Ausprobieren

Das Beispielformular Umbruchtest – fließender Druck (Katalog Service, Ordner Druck-Beispiele) enthält zehn Fälle mit langen Texten und zeigt, wie der Druck damit umgeht.

Sammel-Druck¶

Mit Sammel-Druck-Button anbieten (Formular-Eigenschaften, oben) erscheint neben dem Drucker ein zweiter Knopf: Er fasst den Ausdruck und alle PDF-Anlagen des Datensatzes zu einem PDF zusammen — praktisch, wenn jemand das Gesamtdokument prüfen soll (z. B. Reisekostenabrechnung + Belege). Der Datensatz muss dafür gespeichert sein.

Beispiel: Bestellung mit Übersicht und Anlagen¶

Formular-Eigenschaften → Druck: Titel „Bestellung", Autor „Beschaffung", Stichwörter „bestellung, b2b".
Formular-Eigenschaften → Seiten: zwei Seiten anlegen — uebersicht (A4 hoch, Standardränder) und anlagen (A4 quer, 15 mm ringsum).
Auf dem Tab Übersicht die Kopf-Felder anlegen, auf dem Tab Anlagen die Detail-Tabelle anlage_tabelle.
Kopf- und Fußzeilen: eine Druckvorlage wählen oder eine Fußzeile Seite ${document:page} von ${document:pages} anlegen.
Speichern → Seite 1 des PDFs zeigt die Bestell-Übersicht hochkant, Seite 2 die Anlagen-Tabelle quer.