A box the reader types into

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 empty box of a form, the one the reader types an answer into directly on screen, with nothing printed. You choose where it sits, which handwriting it uses, and whether the text settles left, centre or right. It fits on one line or on several, like a comments box. It can also hide what is typed, password style, or divide the box into little squares, one per character, the way official forms do.

For a developer

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

A text field is an annotation laid over what the other items drew: it makes do with the pages already there, and an empty field leaves the page as it is, the border giving it its outline. The starting value and the reset value are said separately, so a form can start filled and empty itself on a reset. The comb mode implies a maximum length, since that is what divides the box. The field's name is what a filled form reports, and it is also what the submit and reset actions target.

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: name, a string; rect; font; font_size. Optional keys of the field itself: value, the starting value; default_value, the value a reset restores; multiline, password and comb, booleans at false; max_length, an integer; align, one of left (default), center or right. Optional keys shared by every field: read_only, required, no_export, booleans at false; background, the colour behind the field; border, an object with a required width, a color (default black, given in light: grey or RGB) and a style of "solid" (default), {"dashed": {"lengths": …}}, "beveled", "inset" or "underline"; pages, an array of one-based integers, default empty; relative_to, an object of id, edge, offset and an optional part. Cross refusals: comb without max_length; a CMYK or named-space colour in border.color.

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_field",
      "name": "customer",
      "rect": {"llx": 72, "lly": 700, "urx": 300, "ury": 718},
      "font": "sans",
      "font_size": 11,
      "border": {"width": 0.75}
    }
  ]
}

The line that sends it, in three languages

Glossary

CMYK

The four inks a printing press lays down: cyan, magenta, yellow and black. A screen mixes light instead, so a document going to a press states its colours in inks, not in screen colours.

RGB

The three lights a screen mixes a colour from: red, green and blue. All three at full is white, all three off is black. It is how a colour is said for anything lit from behind, and the wrong way to say one for a press, which lays ink on white paper instead.

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.

annotation

Something laid over a page rather than drawn into it: a clickable rectangle, a box to type in, a button. It sits at its own place on the sheet and is what makes a PDF answer to a click at all.

Every word the site explains