A table that carries on from page to page
Rows and columns flowing over as many pages as needed, with a repeated header, rules, coloured backgrounds and merged cells.
Summary
The table you already know, with a piece of text, a price or a picture in each cell. You choose how wide the columns are: a fixed size, a share of what is left, or just enough for the content. Somebody who lands in the middle of a long one always knows what they are reading, because the heading row prints again at the top of every page. The lines, the grey or coloured backgrounds and the cells joined into one are asked for in a single phrase, for the whole table at once.
Technically
Asked for with
"type": "table"
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. A table may also be told to cut a body row too tall for its box at a line of its text rather than move the whole row on; where it is, a cell says with keep_lines how many lines of one of its paragraphs have to stay on each side of that cut, so that the cut never strands an orphan line or a widow line inside a box of a table.
Request schema
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; row_headers, an integer at 0, how many leading columns are the heading of their row, so that a figure read aloud is announced under the entry it stands against; header_links, one of deduced, always or never, whether the cells name the headings they sit under — absent behaves as deduced, which names them only where the standard's own reading of a table cannot say which heading reaches which cell, a heading merged across columns or rows, a heading outside the leading rows and columns, or a row shorter than the table is wide, while always has every cell a heading applies to name it and never has none name any; branch, the label the structure tree holds the table by; fill_frame (default false), whether the body rows share out the room the box leaves under them so that the last of them ends on the box's floor, the header and the footer keeping the height they need; corners, a number, the radius in points the four corners of the table's frame are rounded to, the frame then being drawn as one closed outline, so that a table whose rules draw no frame, or whose rules take one of the four outer lines by its number, is refused, a radius of zero drawing the frame as it is drawn without this key; split_rows (default false), whether a body row too tall for its box is cut at a line of its text instead of being refused; 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), heading (row, column or both: the cell is the heading of the rest of its row, of the rest of its column, or of both; read where the table carries branch), keep_lines (a whole number above zero; absent, the count the engine keeps, the one a text block names apart as orphans and widows). keep_lines is read only where the table cuts a body row at a line of its text, and a cell holding anything but text is unchanged by it; a count no box on the way can honour is dropped and the row is cut where it would have been cut without it. A keep_lines of zero is refused.
A whole request that creates a PDF
{
"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,
"header_links": "deduced",
"branch": "lines",
"split_rows": true,
"fills": [{ "area": "header", "color": [0.93, 0.94, 0.97] }],
"rules": [{"rule": "frame", "stroke": {"width": 0.8}}],
"rows": [
{"cells": [
{
"content": ["Description"],
"font": "sans",
"font_size": 10,
"valign": "middle"
},
{"content": ["Amount"], "font": "sans", "font_size": 10, "align": "right"}
]},
{"cells": [
{"content": ["Rendering engine"], "font": "sans", "font_size": 10,
"keep_lines": 3, "heading": "row"},
{"content": ["4 250.00"], "font": "sans", "font_size": 10, "align": "right"}
]}
]
}
],
"structure": {
"lang": "en-GB",
"children": [{"tag": "Document", "children": [{"branch": "lines"}]}]
}
}Where to go next
Every JSON key of a request, in one page The other twenty-two things you can draw