A list the reader picks from
Offer a list of answers: an open list, a drop-down menu, or a menu the reader may also type an answer into.
Asked for with
"type": "choice_field"
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 list of ready-made answers: the country, a garment size, the reason for a request. The reader picks from what you offer, which spares typing mistakes and fanciful answers. You show the whole list, or a menu that opens on a click, or a menu the reader may also type an answer into when theirs is missing. What the reader reads and what the form keeps can be two different things: they see "France", the form keeps "FR".
For a developer
Written for somebody who writes the calling program: the model, the units, and the settings that carry the weight.
Each option is written as a single string, value and label alike, or as a pair that separates the reported value from the shown label. The presentation picks between the list you scroll, the drop-down menu and the menu open to typing. The starting selection and the one a reset restores are given by reported value, and are said separately. Multi-select lets the reader hold several options at once. The sorted flag declares the list to be in alphabetical order, while a reader shows the options in the order the request gives them: sorting is therefore the request's to do.
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; options, an array whose entries are each a bare string, or an object with a required value and a required label. Optional keys of the field itself: selected, the reported value of the option chosen to start with; default_selected, the reported value of the option a reset restores; presentation, one of list (default), dropdown or editable; multi_select and sorted, booleans at false; align, one of left (default), center or right. Optional keys shared by every field: read_only, required, no_export, booleans at false; background; border (a required width, a color in light, a style); pages, default empty; relative_to. Cross refusal: 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": "choice_field",
"name": "country",
"rect": {"llx": 72, "lly": 700, "urx": 260, "ury": 718},
"font": "sans",
"font_size": 11,
"options": [
{"value": "FR", "label": "France"},
{"value": "GB", "label": "United Kingdom"}
],
"presentation": "dropdown",
"border": {"width": 0.75}
}
]
}Form fields
A box the reader types into A box the reader ticks Several buttons, one answer The place kept for a signature A button the reader presses
Where to go next
Every key of a request, in one page The other twenty things you can draw
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.
- 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.