Everything that can be drawn on a page

In plain words

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

Everything else settles the document; this one fills it. It is the list of what appears on the pages: text, a table, a photograph, a barcode, a line, a tick box. Each thing in the list says what it is and where it goes, and they are drawn in the order they are written — the last one passes over the ones before, like sheets stacked on a desk.

For a developer

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

items is the one key a request must carry. It is an array, in drawing order, where each entry carries a type key saying which of the twenty-one kinds it is. Most kinds share a common base of settings: the rectangle they live in, the pages they appear on, the layer they belong to, a rotation or a transform. Each kind has a detail page of its own.

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.

• items — array, required. The one key a request must carry.
• Each entry is an object carrying type, or an array whose first element is the label. An object with no type is refused; two type keys in one object are refused too.
• Twenty-one type values, each with a page of its own, listed below.
• Settings most kinds share: pages (array of integers, empty by default, meaning every page), layer (the name of a declared layer), id and relative_to (placement relative to another item), transform (six numbers) or rotate (degrees) — both together are refused.

The twenty-one things an item can be

Each has a page of its own: what it is, what a developer needs to know about it, every key it takes with its default, and a whole request showing it.

Text

• A block of text placed on the page text Set text inside a chosen rectangle, with its font, size and colour, and give one word in the middle of a sentence a style of its own.
• Text in paragraphs, with indents and tab stops flow Lay several paragraphs in a frame, with a first-line indent, space between them, bulleted lists and neat columns of figures.
• A stamp laid across the page stamp Lay one word across an area, at the size that fills the box: draft, paid, copy, cancelled, on the diagonal or flat.

Tables

• A table that carries on from page to page table Rows and columns flowing over as many pages as needed, with a repeated header, rules, coloured backgrounds and merged cells.

Pictures and imported pages

• A picture placed in a rectangle image Place a photo or a logo supplied with the request in a chosen frame, stretched to the edges or kept at its own proportions.
• A page of a supplied PDF, placed on the page pdf_page Take one page of a PDF sent with the request and place it in a frame, at its own proportions, among the other items.

Barcodes and square codes

• A barcode of vertical bars barcode Draw a barcode a scanner reads: Code 128 for text, and EAN-13, UPC-A or EAN-8 for a retail article number.
• A square QR code, read with a phone qr Draw a QR code carrying a web address or a piece of text, read by any phone, with its white margin all around.
• An Aztec code, with no white margin around it aztec Draw an Aztec code, the one on train tickets: square, needing no margin, with the share of safety you choose.
• A Data Matrix code, very small and very sturdy data_matrix Draw a Data Matrix code, the one on parcels and small parts: as much content as a QR code in far less room.
• A PDF417 code, carrying a whole form pdf417 Draw a PDF417 code of stacked bars, the one on boarding passes: it carries a whole form, not merely a number.

Shapes

• A free path: lines, curves and filled shapes path Draw a shape point by point, with straight segments and curves, filled with a colour or a gradient, and outlined with a stroke.
• A rectangle, filled or outlined rect Place a rectangle: a coloured band behind a heading, a frame around an area, or both, with the stroke you choose.
• A straight line between two points line Pull a line from one point to another, at the thickness, colour and dash you want: a divider, an underline, a ruled row.

Form fields

• A box the reader types into text_field Add a box to fill in: a name, an address, a comment over several lines, a hidden password, or a number one box per digit.
• A box the reader ticks check_box Add a tick box: accepting terms, choosing an option, with the mark you pick and the value the form reports.
• A list the reader picks from choice_field Offer a list of answers: an open list, a drop-down menu, or a menu the reader may also type an answer into.
• Several buttons, one answer radio_group Place buttons of which only one stays chosen at a time, each in its own spot, all belonging to the same question.
• The place kept for a signature signature_field Keep a spot on the page where an electronic signature will settle, with its name and its frame.
• A button the reader presses push_button Place a button that acts instead of answering: open an address, go to a page, send the form or reset it.

Navigation

• A patch of page a reader clicks link Make a patch of page clickable: it opens a web address, or takes the reader to another page of the same document.

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": "rect",
      "rect": { "llx": 60, "lly": 700, "urx": 535, "ury": 780 },
      "fill": [0.93, 0.95, 0.98]
    },
    {
      "type": "text",
      "rect": { "llx": 72, "lly": 730, "urx": 523, "ury": 760 },
      "content": ["Drawn second, so it sits on top"],
      "font": "sans",
      "font_size": 16
    }
  ]
}

The line that sends it, in three languages

Glossary

barcode

Black bars and white gaps of different widths, standing for a number a scanner reads back in one pass. The bars carry the number and nothing else: the price, the article and the delivery are looked up from it. A code fetched as a picture and then resized, or trimmed too close, stops being read at all.

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.

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