Skip to content
  • Templates as code

What an import does to your template

We imported a customer's 19 apitemplate.io templates and rendered each one on both services. What the importer changed by itself, what it reported, where the PDFs still differ (fonts), a page break and a margin we had to fix on our side, and what is left for a person to decide.

Philipp Staudt

7 min read

The same letterhead, Fennlor Studio GmbH, Musterstraße 1 · 12345 Musterstadt, printed twice by Chromium: as the import keeps it, scaled by 4/3 to the size its author saw, and as it is, a quarter smaller. Above it: You designed this letterhead by eye. Moved as it is, it prints at ¾ size.

Moving document templates is the part of a migration people put off. The API call is easy to change; the templates are years of small decisions in HTML and CSS, and nobody wants to find out in front of a customer which of them did not survive the move.

So instead of a demo template, we took a real account: a customer’s 19 apitemplate.io templates, the documents behind a solar installer’s offers — an overview with the customer’s system, cost statements, material lists, string plans, an economics section with charts, two brands with their own letterheads. We imported all of them with Formfeed’s importer, rendered each one with its own sample data on both services, and compared the PDFs page by page. The documents are the customer’s, so this post shows numbers, not pages.

What an apitemplate.io template is

An apitemplate.io PDF template written in its HTML editor has four parts, and the importer reads all four through apitemplate.io’s API:

  • the body, HTML with Jinja2 tags;
  • the CSS field, which in practice also carries <link> and <script> tags — web fonts, a chart library;
  • the settings: paper, margins as bare numbers (pixels), and a header and footer as either custom HTML or three text slots (left, center, right) with {{pageNumber}} and {{totalPages}};
  • the sample JSON the template was designed against.

Templates edited in apitemplate.io’s visual editor are HTML too and come over the same way; the wrappers that editor puts around loop tags are hidden (the 12 in the table below). Image templates are the exception: they are layer designs without HTML, which apitemplate.io’s API does not return, so the importer lists them as not importable instead of guessing. An image template can be rebuilt on the canvas instead. This account had none.

What the importer changed by itself

All 19 came in without an error. Each template got a short list of what the importer did to it:

Change Templates
Header and footer moved to their own tabs 19
Header and footer scaled by 4/3, the size apitemplate.io draws them in 19
<link> and <script> tags moved from the CSS field to the Head tab 19
Header or footer runs edge to edge (padding 0), as it did there 18
Body keeps the 8px margin browsers give it, as it had there (since November, below) 18
apitemplate.io’s editor-only elements hidden by a CSS rule 12
Script blocks with template tags moved to the end of the body, where they are filled 2
A three-slot text header rebuilt as HTML, page numbers kept 1

The 4/3 is worth a sentence: apitemplate.io draws header and footer templates the way older Chromium versions did, laid out at 75 % of the page width and scaled up by 4/3, so a length in pixels comes out a third larger there than in current Chromium. A letterhead is designed by eye for what the author saw. Left alone, every one of them would have come out at three quarters of its size.

What it reported

32 warnings, of two kinds.

16 × Jinja2 macros run with Nunjucks semantics. The templates define their own formatting macro (format_de, German numbers with a currency) and call it throughout. Our Jinja2 is Nunjucks, which runs macros the same way for everything these templates do, but not for every corner of Python’s Jinja2 — so the importer asks you to look at the output once. The output was right.

16 × a field the template reads is not in the sample data, in three templates. A loop over the strings of an inverter’s MPPT input read string.voltages.at25C and friends, and the sample data had no strings at all; the two cost statements, one per brand, asked offer.is_indication, which their samples never set. None of that is an import problem: the sample data never exercised that part of the template, on apitemplate.io either. The analyzer just says it out loud.

Side by side

We rendered every template with its sample data through apitemplate.io’s API and through our render worker, then compared each pair of PDFs.

Page count: 17 of 19 equal at first. The two economics templates — the ones with charts — came out at 4 pages there and 5 here.

Pixels: we rasterised every page and counted pixels that differ visibly: between 1 % and 16 % per page, with the two fixes below in place. Looking at the worst pages, margins, letterhead, footer, tables, charts and icons matched. What differed was fonts.

Fonts: the template got what it asked for

The templates set most of their text in Chivo from Google Fonts, their headings in a brand typeface from a second web font service, and some text in Arial, header and footer among it. The fonts embedded in the two PDFs:

apitemplate.io Formfeed
Text in Chivo Chivo Chivo
Headings Arial the brand typeface the CSS names
Text in Arial Arial Liberation Sans

apitemplate.io’s PDFs never carried the brand face, so their headings fell back to Arial; ours load it, because the render worker waits for every web font before it prints. That is the template doing what its CSS says, but it is a visible change: headings in a different typeface, and a line box a few pixels taller. In one material list that was enough to move the third component card onto page 2; on apitemplate.io it had fitted on page 1 with almost nothing to spare. Same page count, different break. Text that asks for Arial is Liberation Sans here because our Linux servers have no Arial; it has Arial’s widths, so it takes the same room. Why that happens and how to check it is its own post: fonts in headless Chromium.

The extra page: ours to fix

The charts are drawn by a JavaScript library that sizes each chart from the width of its container when the page loads. Our render worker loaded every PDF in a window 1240 pixels wide — wider than an A4 page, which is 794 — and printing then laid the page out again at the paper’s width. The charts had been sized for the wide window, took more room than they should, and the last one moved to a fifth page.

That was a bug on our side, not in the template, and the import found it. The worker now lays out a PDF in a window as wide and as tall as its paper, so scripts measure the page they are printed on. Both economics templates now come out at 4 pages, like on apitemplate.io, and all 19 page counts match.

The width: ours to fix as well

When we checked this post again in November, before publishing it, the same pictures showed one more difference: in 18 of the 19 templates the text ran 4 mm wider here. The browser gives a page’s body a margin of 8 pixels unless the CSS says otherwise. apitemplate.io keeps it; Formfeed’s print reset set it to 0, so the paper’s margin alone decided where the text started. Only the circuit diagram sets a margin on its body; in the other 18 the text started 2 mm further left and ended 2 mm further right, and in a material list a product name finished its line one word later.

The importer now adds body { margin: 8px; } to a template whose CSS gives the body no margin of its own, and lists it with its other changes; the compatibility endpoint does the same for the HTML sent to it. The text now starts and ends where it did on apitemplate.io, and the product name breaks where it broke there.

What is left for a person

  • Decide on the fonts. Keep the brand typeface the templates always named, or match the look customers got until now by naming Arial for the headings. Either is one line of CSS; it should be a decision, not an accident.
  • Look once at anything that uses macros, as the warning says.
  • Fill the sample data where the analyzer found gaps, so the preview, the completion and the inferred schema see the whole template — and consider storing a schema for the documents that go to customers.
  • Replace placeholder image URLs in the sample data. The long overview showed three project photos from example.com addresses in its sample; both services print a broken image for them.

Then publish, and point the integration at the compatibility endpoint: templates imported in the app keep answering to their apitemplate.io template_id, so the request can stay as it is.

The import is Templates → Import → apitemplate.io in the app, or formfeed import apitemplate --key … for a template project; the migration guide lists every setting and filter the importer maps.

Keep reading

All posts →

Start rendering today

The free plan includes 100 units a month and free test renders. Change plans when you need more.