A table that carries on from page to page

In plain words

Written for anybody. It says what this puts on a sheet of paper, and asks nothing of you beyond that.

This is the table you already know: rows, columns, and in each box a piece of text, a price or a picture. When there are too many rows for one page, the rest carries on by itself on the next page, and the heading row prints again at the top so you always know what you are reading. You choose how wide the columns are: a fixed size, a share of what is left, or just enough for the content. The lines, the grey or coloured backgrounds and the boxes joined into one are asked for in a single phrase, for the whole table at once.

For a developer

Written for somebody who writes the calling program: the model, the units, and the settings that carry the weight.

A table item states its columns, its rows, and the two boxes it flows into: the one on the first page and the one on every page after. Widths are given in points, as a fraction of the remaining space, or measured from the cells' own content. A number of leading and trailing rows repeats on each page. Rules are declared by pattern — the frame, one given line, every other horizontal, a column counted from the end — and fills by area, with a clear order of precedence: a named row or column beats the header and footer, which beat even or odd rows, which beat the whole table; on a tie the last declaration wins, and a fill set on a cell or on a row comes in front of all of it. A cell holds text, an image, a declared drawing or a page of a supplied PDF, and spans several columns or several rows.

Every key, with its default

The reference: which keys are required, which are optional, what each one defaults to and which combinations the server declines.

Required keys: columns, an object of widths (an array of {"points": n}, {"fraction": n}, "content" or "longest_word") and total (a number); rows, an array of rows; first and next, two rect objects. Optional: header and footer, integers at 0; rules, an array of {"rule": …, "stroke": …} where the pattern is "frame", {"horizontal": n}, {"horizontal_from_end": n}, "horizontal_other", {"vertical": n}, {"vertical_from_end": n} or "vertical_other"; fills, an array of {"area": …, "color": …} where the area is "whole", "header", "footer", "even_rows", "odd_rows", {"row": n}, {"row_from_end": n}, {"column": n} or {"column_from_end": n}; id; start, one of {"page": n}, "on_new_page" or {"relative_to": …} (default: the first page); layer. A row: cells required; min_height, space (before, after, default 0), keep_with_next (default false) and fill optional. A cell holds exactly one content among text (content, an array of strings, with font and font_size), image, drawing and pdf (with page, an integer, default 1); two contents, or none, are refused. Other cell keys, all optional: align, overlong, border (top, bottom, left, right, each a stroke), fill, color, padding and margin (left, right, top, bottom, default 0), span and row_span (default 1), valign (top by default, middle, bottom), leading (default 1.2 × the size), leader and align_on (one character).

A whole request that draws it

Post this as it stands and a PDF comes back. Nothing has been left out of it.

{
  "standard_fonts": [{"name": "sans", "face": "helvetica"}],
  "items": [
    {
      "type": "table",
      "columns": {"widths": [{"fraction": 1.0}, {"points": 80}], "total": 451},
      "first": {"llx": 72, "lly": 600, "urx": 523, "ury": 780},
      "next": {"llx": 72, "lly": 72, "urx": 523, "ury": 780},
      "header": 1,
      "rules": [{"rule": "frame", "stroke": {"width": 0.8}}],
      "rows": [
        {"cells": [
          {"content": ["Description"], "font": "sans", "font_size": 10},
          {"content": ["Amount"], "font": "sans", "font_size": 10, "align": "right"}
        ]},
        {"cells": [
          {"content": ["Rendering engine"], "font": "sans", "font_size": 10},
          {"content": ["4 250.00"], "font": "sans", "font_size": 10, "align": "right"}
        ]}
      ]
    }
  ]
}

The line that sends it, in three languages

Glossary

font

The drawing of every letter, digit and mark a document writes, held in a file of its own. A PDF carries the fonts it is set in inside itself, which is why it opens looking the same on a machine that has never had them. Leave them out and a reader puts another font in their place, and the layout moves.

layer

A named group of things drawn on a page that a reader can switch on and off, like tracing paper laid over a plan. A drawing can hold its measurements on one and its notes on another, and a layer can be set to show on screen and stay off the printer.

Every word the site explains