A block of text placed on the page

In plain words

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

You pick a frame on the sheet, as if you drew a rectangle in pencil, and you say what goes inside it. You give the handwriting, its size and its colour, and the text arranges itself inside, line after line. In the middle of a sentence, one word can take a style of its own: bigger, bold, underlined, or another colour. This is the piece used everywhere, from the heading of an invoice to the small print at the foot of the page.

For a developer

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

A text item lays a block of text inside a rectangle given in points, in page coordinates: the origin sits at the bottom left and the vertical axis goes up. The content is a list of runs: a plain string takes the block's style, while an object overrides, for itself alone, the font, the size, the leading, the colour or the rules (underline, strikethrough, overline). A run can also ask the server for the moment of rendering, formatted with a strftime pattern in the named time zone. The text accepts the pagination placeholders, which gives a footer reading "page 3 of 12" written once for the whole document.

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: rect, an object of four coordinates llx, lly, urx, ury, each a number or a quoted expression (+ - * / ( ), variables {page_width}, {page_height}, {current_page}, {total_pages}, {llx}, {lly}, {urx}, {ury}, maximum depth 100); content, an array of runs; font, a string naming a font the request declared (standard_fonts, fonts, type1_fonts, type3_fonts, font_chains, font_variants); font_size, a number of points. A run takes three shapes: a bare string; an object {"text": …} with optional font, font_size, leading, underline, strikethrough, overline and color, each holding for that run alone; an object {"date": "strftime pattern"} with an optional zone (an IANA name, otherwise the rendering host's zone). Optional keys on the block: align (left by default, right, center, justify); overlong (overflow by default, an over-wide word runs past the edge; break cuts it); leading (default 1.2 × font_size); break_after, the characters a line may break after (by default breaks happen at spaces and soft hyphens); underline, strikethrough, overline, booleans at false; color (default black); shadow, an object whose dx, dy and color are all required; pages, an array of one-based integers, default empty, meaning every page; id, a string another item refers to; relative_to, an object of id, edge (top or bottom), offset and an optional part (default: the last part laid); transform, six numbers; rotate, degrees counter-clockwise about the centre of the box; layer, the name of a declared layer. Cross refusal: transform together with rotate.

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": "text",
      "rect": {"llx": 72, "lly": 740, "urx": 523, "ury": 780},
      "content": ["Invoice 1964413", {"text": " — paid", "color": [0.1, 0.45, 0.25]}],
      "font": "sans",
      "font_size": 16
    }
  ]
}

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.

request

One call to the service: you send what the document should say, and get the document back. Your bill counts these calls, one for each document. The number of pages inside a document is never counted.

server

A machine that waits for calls and answers them, running day and night with nobody sitting at it. The one that draws documents here holds the engine and hands back the finished pages; the one your website runs on is a different machine doing the same kind of job.

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