A Field the Reader Types Into

Add a field to fill in: a name, an address, a comment over several lines, a hidden password, or a number one square per digit.

See It in a Real PDF

A Two-Page Services Contract

A services agreement over two pages where no clause is ever cut in half by a page turn, ending in signature, name and date fields filled in on screen.

Open the PDF The Whole Example

Also shown in: An Archivable PDF/A-3 Form · An Interactive Form

Summary

The empty field of a form, the one the reader types an answer into directly on screen, with nothing printed. You choose where it sits, which font it uses, and whether the text settles left, centre or right. A comments field takes several lines; a password shows dots instead of letters; and a reference number can be cut into little squares, one per character, the way official forms do.

Technically

Asked for with "type": "text_field"

A text field is a /Widget annotation and an /FT /Tx field in the AcroForm, 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, /V, and the value a reset restores, /DV, are said separately, so a form can start filled and empty itself on a reset. The /Ff bits carry multiline, password and comb, and the comb mode implies the /MaxLen that divides the box. The field's name is what a filled form reports, and it is also what the submit and reset actions target.

Request Schema

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; character_spacing, the points added after each glyph, 0 by default. 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"; tooltip, a string, what the field is for and the name a screen reader announces it under; mapping_name, a string, the name a submitted form reports the answer under when that is not the field's own name; flags, an object stating what a reader does with the widget besides drawing it, spelled exactly as a review mark laid over a page spells its own, absent printing the field and saying nothing else; description, a string, what the widget says to that same screen reader; triggers, an object naming one action per moment; 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. The ten moments are enter, the pointer arriving over the field; exit, the pointer leaving it; down, the pointer's button pressed over it; up, that button released over it; focused and blurred, the field taking the input focus and losing it; page_opened and page_closed, the page the field sits on being opened and closed; page_shown and page_hidden, that page coming into and going out of view. A moment left out is one the file leaves out too, and a field that also carries an action follows that one rather than up. A document claiming pdfua2 wants every field to carry a tooltip or a description; one claiming a part of PDF/A other than the fourth carries no field that acts at all, and the render is refused, pdfa4 and pdfa4f letting one through. A document claiming any part of PDF/A carries no field whose flags hide it, make it invisible, or keep it off the screen or off the paper, and the render is refused: every annotation of an archival file is printed and shown. Three more keys are shared by every field: highlight, one of none, invert, outline and push, what reading software shows while the field is held down; layer, the name of a declared layer the field is shown and hidden with; tab_rank, an integer, the field's place in the order the tab key walks, lowest first, a field stating none coming after every ranked one. A text field, a choice field and a push button also take text_color, a colour given in light, black by default; and rotation, one of upright (default), quarter, half and three_quarters, how far the contents are turned inside the box, anticlockwise. Every field also takes mark, the label the structure tree claims it by through a node's annotations. A field that draws text of its own also takes text_stroke, a stroke drawn round every letter on top of its fill, {"width": 0.5, "color": [0, 0.2, 0.6]}, black where the colour is absent. A text field also takes file_select, do_not_spell_check and do_not_scroll, booleans at false: what is typed is the path of a file the form sends in its place; reading software leaves it unchecked for spelling; reading software stops taking characters once the box is full. A font_size of 0 asks reading software to fit the text to the box. Further cross refusals: comb beside multiline, password or file_select. A text field also takes password_mask, one character the starting value is shown as, once for each of its characters, on one line; stating it makes the field a password field whatever password says, and a password field without it shows none of its value.

A Whole Request That Creates a PDF

{
  "standard_fonts": [{"name": "sans", "face": "helvetica"}],
  "items": [
    {
      "type": "text_field",
      "name": "customer",
      "align": "left",
      "rect": {"llx": 72, "lly": 700, "urx": 300, "ury": 718},
      "font": "sans",
      "font_size": 11,
      "border": {"width": 0.75, "style": "underline"}
    },
    {
      "type": "text_field",
      "name": "office",
      "value": "For office use",
      "rotation": "quarter",
      "rect": {"llx": 540, "lly": 500, "urx": 556, "ury": 760},
      "font": "sans",
      "font_size": 11,
      "border": {"width": 0.75}
    }
  ]
}

The line that sends it, in three languages

Form fields

A Box the Reader Ticks A List the Reader Picks From Several Buttons, One Answer The Place Kept for a Signature A Button the Reader Presses

Where to Go Next

Every JSON key of a request, in one page The other twenty-two things you can draw

See the Prices See the Examples