Dokument-Templates umzuziehen ist der Teil einer Migration, den man gern aufschiebt. Den API-Aufruf zu ändern ist leicht; die Templates sind Jahre kleiner Entscheidungen in HTML und CSS, und niemand möchte vor einem Kunden herausfinden, welche davon den Umzug nicht überlebt haben.
Statt eines Demo-Templates haben wir deshalb ein echtes Konto genommen: die 19 apitemplate.io-Templates eines Kunden, die Dokumente hinter den Angeboten eines Solarinstallateurs — eine Übersicht mit der Anlage des Endkunden, Kostenaufstellungen, Materiallisten, Stringpläne, ein Wirtschaftlichkeitsteil mit Diagrammen, zwei Marken mit eigenem Briefkopf. Wir haben alle mit dem Importer von Formfeed importiert, jedes mit seinen eigenen Beispieldaten auf beiden Diensten gerendert und die PDFs Seite für Seite verglichen. Die Dokumente gehören dem Kunden, deshalb zeigt dieser Beitrag Zahlen, keine Seiten.
Was ein apitemplate.io-Template ist
Ein PDF-Template, das im HTML-Editor von apitemplate.io geschrieben wurde, hat vier Teile, und der Importer liest alle vier über die API von apitemplate.io:
- den Body, HTML mit Jinja2-Tags;
- das CSS-Feld, das in der Praxis auch
<link>- und<script>-Tags trägt — Webschriften, eine Diagrammbibliothek; - die Einstellungen: Papier, Ränder als bloße Zahlen (Pixel) und Kopf- und Fußzeile entweder als
eigenes HTML oder als drei Textfelder (links, Mitte, rechts) mit
{{pageNumber}}und{{totalPages}}; - das Beispiel-JSON, gegen das das Template entworfen wurde.
Templates, die im visuellen Editor von apitemplate.io bearbeitet wurden, sind ebenfalls HTML und kommen genauso herüber; die Hüllen, die dieser Editor um Schleifen-Tags legt, werden ausgeblendet (die 12 in der Tabelle unten). Die Ausnahme sind Bild-Templates: Sie sind Ebenen-Designs ohne HTML, die die API von apitemplate.io nicht herausgibt, also führt der Importer sie als nicht importierbar auf, statt zu raten. Ein Bild-Template lässt sich stattdessen auf der Arbeitsfläche nachbauen. Dieses Konto hatte keine.
Was der Importer von selbst geändert hat
Alle 19 kamen ohne Fehler herein. Jedes Template bekam eine kurze Liste dessen, was der Importer daran getan hat:
| Änderung | Templates |
|---|---|
| Kopf- und Fußzeile in eigene Tabs verschoben | 19 |
| Kopf- und Fußzeile um 4/3 skaliert, die Größe, in der apitemplate.io sie zeichnet | 19 |
<link>- und <script>-Tags aus dem CSS-Feld in den Head-Tab verschoben |
19 |
| Kopf- oder Fußzeile läuft randlos (Padding 0), wie dort | 18 |
| Body behält den Rand von 8px, den Browser ihm geben, wie dort (seit November, unten) | 18 |
| Nur für den Editor von apitemplate.io gedachte Elemente per CSS-Regel ausgeblendet | 12 |
| Script-Blöcke mit Template-Tags ans Ende des Body verschoben, wo sie befüllt werden | 2 |
| Eine Kopfzeile aus drei Textfeldern als HTML nachgebaut, Seitenzahlen erhalten | 1 |
Die 4/3 verdienen einen Satz: apitemplate.io zeichnet Kopf- und Fußzeilen so, wie es ältere Chromium-Versionen taten, in 75 % der Seitenbreite angelegt und um 4/3 vergrößert; eine Länge in Pixeln fällt dort also ein Drittel größer aus als im aktuellen Chromium. Einen Briefkopf gestaltet man nach Augenmaß für das, was man sieht. Unverändert wäre jeder davon in drei Vierteln seiner Größe erschienen.
Was er gemeldet hat
32 Warnungen, von zwei Arten.
16 × Jinja2-Makros laufen mit Nunjucks-Semantik. Die Templates definieren ein eigenes
Formatierungsmakro (format_de, deutsche Zahlen mit Währung) und rufen es überall auf. Unser Jinja2
ist Nunjucks, das Makros für alles, was diese Templates tun, genauso ausführt, aber nicht für jeden
Winkel des Python-Jinja2 — also bittet der Importer, einmal auf die Ausgabe zu schauen. Die Ausgabe
stimmte.
16 × ein Feld, das das Template liest, fehlt in den Beispieldaten, in drei Templates. Eine
Schleife über die Strings eines MPPT-Eingangs las string.voltages.at25C und Verwandte, und die
Beispieldaten hatten überhaupt keine Strings; die beiden Kostenaufstellungen, eine je Marke, fragten
offer.is_indication ab, das in ihren Beispielen nie gesetzt war. Nichts davon ist ein
Importproblem: Die Beispieldaten haben diesen Teil des Templates nie durchlaufen, auch bei
apitemplate.io nicht. Der Analyzer spricht es nur aus.
Nebeneinander
Wir haben jedes Template mit seinen Beispieldaten über die API von apitemplate.io und über unseren Render-Worker gerendert und dann jedes PDF-Paar verglichen.
Seitenzahl: Zunächst bei 17 von 19 gleich. Die beiden Wirtschaftlichkeits-Templates — die mit Diagrammen — hatten dort 4 Seiten und hier 5.
Pixel: Wir haben jede Seite gerastert und die Pixel gezählt, die sich sichtbar unterscheiden: zwischen 1 % und 16 % pro Seite, mit den beiden Korrekturen weiter unten. Auf den schlechtesten Seiten stimmten Ränder, Briefkopf, Fußzeile, Tabellen, Diagramme und Icons überein. Was sich unterschied, waren Schriften.
Schriften: Das Template bekam, was es verlangte
Die Templates setzen den Großteil ihres Textes in Chivo von Google Fonts, ihre Überschriften in einer Markenschrift von einem zweiten Webfont-Dienst und manchen Text in Arial, darunter Kopf- und Fußzeile. Die in den beiden PDFs eingebetteten Schriften:
| apitemplate.io | Formfeed | |
|---|---|---|
| Text in Chivo | Chivo | Chivo |
| Überschriften | Arial | die Markenschrift, die das CSS nennt |
| Text in Arial | Arial | Liberation Sans |
Die PDFs von apitemplate.io enthielten die Markenschrift nie, ihre Überschriften fielen also auf Arial zurück; unsere laden sie, weil der Render-Worker vor dem Drucken auf jede Webschrift wartet. Das Template tut damit, was sein CSS sagt, aber es ist eine sichtbare Änderung: Überschriften in einer anderen Schrift und eine Zeilenbox, die ein paar Pixel höher ist. In einer Materialliste reichte das, um die dritte Komponentenkarte auf Seite 2 zu schieben; bei apitemplate.io hatte sie mit fast keinem Platz übrig auf Seite 1 gepasst. Gleiche Seitenzahl, anderer Umbruch. Text, der Arial verlangt, ist hier Liberation Sans, weil unsere Linux-Server kein Arial haben; sie hat die Breiten von Arial und braucht denselben Platz. Warum das so ist und wie man es prüft, ist ein eigener Beitrag: Schriften in Headless Chromium.
Die zusätzliche Seite: unser Fehler
Die Diagramme zeichnet eine JavaScript-Bibliothek, die jedes Diagramm beim Laden der Seite nach der Breite seines Containers bemisst. Unser Render-Worker lud jedes PDF in einem 1240 Pixel breiten Fenster — breiter als eine A4-Seite mit 794 — und der Druck legte die Seite danach in Papierbreite neu an. Die Diagramme waren für das breite Fenster bemessen, nahmen mehr Platz ein als vorgesehen, und das letzte rutschte auf eine fünfte Seite.
Das war ein Fehler auf unserer Seite, nicht im Template, und der Import hat ihn gefunden. Der Worker legt ein PDF jetzt in einem Fenster an, das so breit und so hoch ist wie sein Papier, damit Skripte die Seite vermessen, auf die gedruckt wird. Beide Wirtschaftlichkeits-Templates haben jetzt 4 Seiten, wie bei apitemplate.io, und alle 19 Seitenzahlen stimmen überein.
Die Breite: ebenfalls unser Fehler
Als wir diesen Beitrag im November vor dem Veröffentlichen noch einmal prüften, zeigten dieselben Bilder einen weiteren Unterschied: In 18 der 19 Templates lief der Text hier 4 mm breiter. Der Browser gibt dem Body einer Seite einen Rand von 8 Pixeln, solange das CSS nichts anderes sagt. apitemplate.io behält ihn; der Print-Reset von Formfeed setzte ihn auf 0, sodass allein der Papierrand bestimmte, wo der Text beginnt. Nur der Schaltplan setzt einen Rand an seinem Body; in den anderen 18 begann der Text 2 mm weiter links und endete 2 mm weiter rechts, und in einer Materialliste beendete ein Produktname seine Zeile ein Wort später.
Der Importer fügt jetzt body { margin: 8px; } in ein Template ein, dessen CSS dem Body keinen eigenen
Rand gibt, und führt das bei seinen übrigen Änderungen auf; der Kompatibilitäts-Endpunkt tut dasselbe
für das HTML, das er bekommt. Der Text beginnt und endet jetzt, wo er bei apitemplate.io begann und
endete, und der Produktname bricht um, wo er dort umbrach.
Was für einen Menschen bleibt
- Über die Schriften entscheiden. Die Markenschrift behalten, die die Templates immer genannt haben, oder den Eindruck treffen, den Kunden bisher bekamen, indem man für die Überschriften Arial nennt. Beides ist eine Zeile CSS; es sollte eine Entscheidung sein, kein Zufall.
- Einmal auf alles schauen, was Makros verwendet, wie die Warnung sagt.
- Die Beispieldaten ergänzen, wo der Analyzer Lücken fand, damit Vorschau, Autovervollständigung und abgeleitetes Schema das ganze Template sehen — und für Dokumente, die an Kunden gehen, ein Schema hinterlegen.
- Platzhalter-Bild-URLs ersetzen in den Beispieldaten. Die lange Übersicht zeigte drei Projektfotos
von
example.com-Adressen in ihrem Beispiel; beide Dienste drucken dafür ein kaputtes Bild.
Danach veröffentlichen und die Integration auf den
Kompatibilitäts-Endpunkt umstellen: In der App
importierte Templates antworten weiter auf ihre template_id von apitemplate.io, der Request kann also
bleiben, wie er ist.
Der Import ist Vorlagen → Importieren → apitemplate.io in der App, oder
formfeed import apitemplate --key … für ein Template-Projekt; der
Migrationsleitfaden führt jede Einstellung und
jeden Filter auf, die der Importer abbildet.


