Zum Inhalt springen
  • Vorlagen als Code

Was ein Import mit Ihrem Template macht

Wir haben die 19 apitemplate.io-Templates eines Kunden importiert und jedes auf beiden Diensten gerendert. Was der Importer von selbst geändert hat, was er gemeldet hat, wo die PDFs sich noch unterscheiden (Schriften), ein Seitenumbruch und ein Rand, die wir auf unserer Seite beheben mussten, und was ein Mensch entscheiden muss.

Philipp Staudt

8 Min. Lesezeit

Derselbe Briefkopf, Fennlor Studio GmbH, Musterstraße 1 · 12345 Musterstadt, zweimal von Chromium gedruckt: wie der Import ihn hält, um 4/3 auf die Größe skaliert, die sein Autor sah, und unverändert, ein Viertel kleiner. Darüber: Den Briefkopf gestalteten Sie nach Augenmaß. Unverändert umgezogen, druckt er in ¾ Größe.

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.

Heute mit dem Rendern beginnen

Der kostenlose Plan enthält 100 Einheiten im Monat und kostenlose Testrenderings. Wechseln Sie den Plan, wenn Sie mehr brauchen.