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.
See It in a Real PDF
Twelve invoice lines is one page and thirty is two, the second taking up the first's header and layout.
Open the PDF The Whole Example
Also shown in: A Cell's Margin, Border, Inner Room and Fill · Coloured Cell Borders and Fills · A Self-Paginating Table
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, the rows a cell spans down being cut between two boxes the same way, the cell going on into the next; threads, an array of {"name": …, "content": […], "font": …, "font_size": n}, texts that run through several cells; 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), thread (the name of a thread: the cells naming one take its text in the order they come, each but the last the lines its row's height holds without it, the last the rest), 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), repeated_when_cut (default false; true draws the text of a cell whose rows are cut between two boxes whole again at the head of the next), 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 table also takes caption, an object: content, required, its words, a newline ending a paragraph; side, above (default) or below, the side of the table it is set on, as wide as the table; gap, the points kept between it and the table, none by default; first_box_only, a boolean at false, true setting it on the first box the table goes into rather than on every box it is continued into; and the keys that style a flow block, font, font_size, align, color and the rest, for how it is set. Its room comes off the box before a row is placed. draw_damaged, a boolean at false, lays the table out even where it would be refused, so that what went wrong can be seen on the page: a row covering another number of columns than the table has is placed as far as the columns go, and a row taller than an empty box runs past the box's bottom. A row also takes fixed_height, an object of height and floor, both numbers of points and both required: the row takes height whatever its text needs, text that does not fit at its own size is set at the largest size down to floor at which it does, and text that does not fit even at floor runs past the bottom of its cell; it outranks min_height, and the row is never cut across two boxes. A cell also takes character_spacing and horizontal_scaling, read as on a text block. A cell's leader also takes the object a flow block's leader takes, its font and font_size falling back to the cell's; a cell holding a picture repeats no string. columns also takes groups, columns kept one width, each group {"name": …, "columns": [0, 2]} counted from the left, every column of it as wide as the widest wants; a column named in two groups belongs to the last.
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}}],
"caption": {
"content": "Amounts in euros",
"side": "below",
"gap": 4,
"font": "sans",
"font_size": 9
},
"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