Skip to content

PDF layout reference ​

Every setting a PDF layout has, as the definition stores it. The PDF workspace in the builder writes all of it for you; read this page when you write a layout by hand, generate one, or want to know what a switch in the inspector does. How a layout is chosen, themes, fonts and the options of renderPdf() are on PDFs.

Where layouts live ​

A form definition holds its layouts in a pdf block.

json
{
  "pdf": {
    "defaultLayoutId": "record",
    "layouts": [
      { "id": "record", "kind": "generated", "name": "Applicant copy", "root": { "id": "document", "type": "pdf-document", "configuration": {}, "children": { "body": [] } } },
      { "id": "form-12", "kind": "template", "name": "Form 12", "when": "country = \"CA\"", "template": { "storage": "base64", "name": "form-12.pdf", "type": "application/pdf", "size": 48211, "data": "…" }, "fields": [] }
    ]
  }
}
KeyMeaning
defaultLayoutIdThe layout drawn when none is asked for and no when holds. Left out, the first layout. The builder writes it as soon as a layout has a when.
layoutsThe layouts, in the order their conditions are tried. A layout that fails its checks (no id, no root, a template without a source) is left out of the list.

Every layout has these keys.

KeyMeaning
idRequired. Names the layout in renderPdf({ layoutId }), defaultLayoutId and the translations.
kindgenerated, a tree of PDF blocks that is paginated, or template, an existing PDF that is filled.
nameWhat a picker calls the layout. A string in the form's default language, translated per locale. Left out, the id.
whenA condition over the answers. See how a layout is chosen. Left out, the layout is drawn only when asked for by id, or as the default.

A generated layout also has root, a pdf-document node whose slots body, header and footer hold the blocks below, and the document settings in the next section. A template layout has template, fields, areas and options, described under Template layouts.

Document settings ​

These apply to the whole generated document. Write them on the layout, or on the configuration of its pdf-document root; the builder writes them on the root. A template layout takes accessibility, conformance, attachments and signature from the same keys.

SettingValuesDefault
page.sizeLetter, A4, Legal, or { "width": 600, "height": 800 } in points (each at least 36)The PDF theme's page, else Letter
page.orientationportrait, landscapeportrait
page.marginstop, right, bottom, left, in points, zero or more54 each (three quarters of an inch)
page.header.height, page.footer.heightPoints reserved on every page for the header and footer slotsNone: no band
accessibility.taggedWrite a structure tree. See Accessibility of the PDFThe theme's tagged, else true
accessibility.displayDocTitleAsk the viewer to show the title rather than the file nametrue
accessibility.langA language tag for the documentThe locale the PDF is drawn in
accessibility.titleThe document title (translated)The layout's name, else the form's title
conformance.pdfa2b, 2u, 2a, 3b, 3u, 3a. See PDF/ANone, or the theme's
conformance.outputIntentprofile (an ICC profile), identifier, info, registrysRGB IEC61966-2.1
conformance.attachDataEmbed the answers as a JSON file. Part 3 onlyfalse
conformance.attachmentname, description of that filesubmission.json, "Submission data"
attachments.budgetMbTotal size of uploaded files one document may embed, in megabytes4
attachments.onExceededskip, failskip
signatureHow the document is sealed. See SigningNone
themeThe id of a PDF theme. See themesThe host's, then the form's binding's, then datum-pdf
renditionDefaultsType to rendition id, with * for every type. See RenditionsNone
limits.pages, limits.answerCharsThe most pages a document may run to, and the most characters of one answer drawn200 and 20,000; held to 1,000 and 200,000

limits is read on generated layouts and has no field in the builder. A document that runs past limits.pages is refused with the render_limit failure. An answer past limits.answerChars is cut with a marker and a render.truncated warning, once per component. A larger value than the ceiling is held to it and warns render.limitsCapped.

Output intent ​

PDF/A files declare the colour condition they were made for. The kernel carries three profiles, so a layout can name one without any file being fetched.

Profileref in the envelopeIdentifier it declares
sRGB, the defaultsrgbsRGB IEC61966-2.1
Grey, gamma 2.2grayGray gamma 2.2
CMYK, SWOP-compatiblecmykCGATS TR 001
json
{ "conformance": { "pdfa": "2b", "outputIntent": { "profile": { "storage": "builtin", "ref": "cmyk", "name": "CGATS TR 001 compatible.icc", "type": "application/vnd.iccprofile", "size": 8464 } } } }

Any other profile is an ICC file in the same envelope: inline (storage: "base64" with data), or a storage the host resolves through its pdfTemplates resolver. identifier defaults to the profile's file name without its extension and info to the identifier. A profile the host cannot supply is dropped with pdfa.outputIntent, and the file declares sRGB. A Grey or CMYK profile is declared with an RGB default for what the kernel draws. A template keeps the output intent it already declares.

Blocks ​

A generated layout is a tree. Each node has an id, a type, a configuration and, for containers, children keyed by slot. Twelve types exist; the root is one of them.

pdf-document ​

The root. Slots body (the flow), header and footer (drawn on every page, inside the bands set by page.header.height and page.footer.height). Its settings are the document settings. A pdf-document inside another is skipped with layout.nestedDocument.

pdf-section ​

A heading with blocks under it. Slot content.

SettingMeaningDefault
labelThe heading, translatedNone
hideLabelDraw the content without the headingfalse
keepTogetherMove the whole section to the next page rather than split itfalse
skipWhenEmptyLeave the section out, heading included, when nothing in it printsfalse

pdf-field ​

One of the form's components, placed on the page.

SettingMeaningDefault
componentIdThe component to print. One the form does not have prints nothing and the designer says soNone
renditionHow it is drawn here. See RenditionsThe ladder below
labelA label to draw instead of the component's ownThe component's label
hideLabelDraw no labelfalse
attachFor a file upload: embed its files in the PDF. Set, it decides either way; left out, the component's own pdf.attach doesLeft out
widgetNameThe AcroForm field name, for the field rendition. Left out, the component's value path, prefixed inside a repeat by the collection path and row (items[0].email). A name set here is used as written, so leave it empty inside a repeatLeft out

A checkboxes component drawn as field gets one widget per option, named after the field and the option. Names must be unique across the layout; a repeated signature field name warns layout.duplicateWidgetName.

pdf-text ​

A paragraph or heading of the layout's own.

SettingMeaningDefault
textThe words, translated, with placeholders. See PlaceholdersNone
variantbody, h1, h2, h3, muted, label. Hand-written layouts may also use h4 to h6body
alignstart, center, endstart
expressionA computed value that replaces the text: a sum, a formula, answers joined togetherNone

A text block that comes out empty is not drawn.

pdf-table ​

Rows and columns of blocks. Each cell is a slot named r1c1 for the top left, r1c2 for the cell to its right, and so on.

SettingMeaningDefault
rows1 to 502
columns1 to 122
headerThe first row is a header: bold, and repeated when the table continues on another pagetrue
bordersall, horizontal (between rows), noneall
collectionPathThe id of a repeating section or data grid. The first non-header row is drawn once per entry, with {{row.fieldId}} in its cells; the other rows are ignoredNone: every row is drawn once
widthsColumn widths as fractions of the table, one number per column. Hand-written layouts onlyEqual
skipWhenEmptyLeave the table out when no cell printsfalse

Shrinking a table moves what was in the removed cells into the last cell.

pdf-repeat ​

A block drawn once per entry of a repeating section or data grid. Slot row.

SettingMeaningDefault
collectionPathThe id of the repeating section or data grid. A repeat naming none warns repeat.unboundNone
emptyTextText to draw when there are no entriesNothing
keepRowTogetherKeep each entry on one pagefalse
maxRowsDraw at most this many entriesAll

pdf-box ​

A framed or filled area. Slot content.

SettingMeaningDefault
borderDraw a bordertrue
borderWidthPointsThe theme's box, 0.75
borderColor, fillA colour, such as #1a4480The theme's border colour, and no fill
paddingPoints inside the borderThe theme's box, 6
radiusCorner radius in points. Hand-written layouts onlyThe theme's box
skipWhenEmptyLeave the box out, border and fill included, when nothing in it printsfalse
anchorPins the box instead of flowing it: page (first, last, every, or a page number from 1), x and y in points from the page's left and top edges, width and height in points (both above zero)Flows with the content

A pinned box takes no room in the flow.

pdf-rule and pdf-spacer ​

A rule is a horizontal line: thickness in points (at least 0.25, default 0.75) and color. A spacer is vertical space: height in points (at least 1, default 12).

pdf-image ​

A logo or picture.

SettingMeaningDefault
srcA PNG or JPEG: a data:image/png;base64, or data:image/jpeg;base64, URL, which embeds the bytes in the layout, or an http(s), protocol-relative, / or ./ URL the page fetches. Any other URL is refused with image.unsafeUrlNone: nothing is drawn
altAlternative text, translated. Empty marks the image as decorativeEmpty
width, heightPointsLeft out, the kernel sizes the picture

A picture the page cannot fetch is left out with image.unresolved.

pdf-signature ​

Where the document is signed.

SettingMeaningDefault
fieldNameThe AcroForm signature field this block makes. Unique in the layout. The layout's signature.field names it for the server to sign intoThe node's id
labelA caption printed above the box. {{path}} placeholders work as in a text blockNone
modefield, a real signature field signed by a server or in a viewer, or line, a ruled line to sign by handfield
width, heightPointsThe column's width, 40

pdf-page-break ​

A new page from here. With changePage set, the page setting (size, orientation, and margins as in the document settings) applies from the new page on.

Renditions ​

A rendition is how a component appears on paper. Each component type offers some of the following.

IdWhat it drawsOffered by
textThe label and the answer as text. The filled-record lookText-like fields (text, email, tel, url, number, date, time, textarea), choices, checkboxes, file, html; the default for all of those except the ones below
fieldAn AcroForm widget carrying the answer, fillable in a viewer. A choice becomes a dropdown, list or radio group; a checkboxes component one box per option; a file upload a text widget listing the file namesThe same types, and signature
ruledThe label and blank lines to write on. The print-and-fill-by-hand lookText-like fields and choices
checkmarkA box ticked when truecheckbox, boolean. The default
checklistEvery option as a box or circle, the chosen ones markedselect, multiselect, radio, checkboxes. The default for checkboxes
imageThe picture itselfimage; file and signature when the answer carries PNG or JPEG bytes. The default for image
lineA signature linesignature. The default
noneNothingbutton. The default; not offered in the picker
groupThe children, no headingEvery container. The default for form, container, panel, button-group
sectionA heading, then the childrenfieldset, step (the default), and the other containers
sectionsOne section per tab or entrytabs (the default) and anything bound to a collection
tableOne column per cell or field, one row per entrygrid, row, columns, table and anything bound to a collection (the default). A data grid whose layout is stacked defaults to sections
panelA titled box around the childrencontainer, panel, fieldset, section, step

A type the engine does not know is drawn with the text rendition, or as a group when it has children, so every component prints something. A plugin may add renditions to its own types.

Which rendition a component takes is the first of these that names one the type offers:

  1. The rendition on the pdf-field block.
  2. The component's own configuration.pdf.rendition.
  3. The layout's renditionDefaults entry for the component's type.
  4. The layout's renditionDefaults["*"].
  5. The PDF theme's choice for the type, then for *. The default theme draws a radio as a checklist.
  6. The type's own default, in the table above.

A rendition named for a type that does not offer it is skipped with rendition.unknown. A * that does not fit the type, such as field on a container, is skipped quietly. So "renditionDefaults": { "*": "field" } turns a filled-record layout into a blank fillable one.

A form component carries its own PDF settings in configuration.pdf.

KeyMeaning
renditionThe rendition this component takes unless a layout says otherwise
excludeLeave the component out of every PDF
attachFor a file upload: embed its files in the PDF. See Attachments

Placeholders ​

Text in a layout, a signature caption, a template mapping and a template area can write answers into itself with double braces.

PlaceholderReads
{{fieldId}}The answer of a component, as printed: an option's label rather than its value, the names of uploaded files
{{row.fieldId}}The same inside a repeat or a table bound to a collection
{{ancestor.fieldId}}A field of the enclosing entry, in nested repeats
{{host.key}}A value from the host context the call supplied
{{rowNumber}}, {{rowIndex}}, {{rowCount}}Inside a repeat: the entry's number from 1, its index from 0, the number of entries
{{page}}, {{pages}}The page number and the page count, in a header or footer

A placeholder that finds no answer prints nothing. The Variables panel on the builder's strip lists every placeholder a layout can use.

Template layouts ​

A template layout fills an existing PDF with the form's answers. The PDF can be a fillable form, in which case its fields are mapped, or a flat page, in which case areas draw the answers onto it.

KeyMeaning
templateWhere the PDF is: storage, name, type, size, and for base64 storage the file as data. Any other storage names a kind the host resolves through its pdfTemplates resolver, with ref for whatever the host needs to find it
fieldsOne mapping per AcroForm field. Empty when the PDF has none
areasRectangles on the pages that answers are drawn into
optionsFill options
accessibility, conformance, attachments, signature, when, nameAs for a generated layout

Mappings ​

json
{
  "pdfField": "topmostSubform[0].Page1[0].Province[0]",
  "source": { "kind": "component", "componentId": "province" },
  "values": { "ON": "1", "BC": "2" }
}

pdfField is the field's fully qualified name. Every mapping has a source and may have checkedValue, values and format.

Source kindReads
component, with componentIdThe answer of one component, as the PDF field expects it: text for a text field, the stored option value for a choice, a tick for a checkbox. A component hidden by a rule fills blank. A repeating section or data grid has no single value: it fills blank with mapping.collection, so map each cell with a path source
path, with pathA value by its path in the submitted values, such as items[0].sku
template, with textText with placeholders, translated per locale
expression, with expressionA formula. One that cannot be read fills blank with formula.invalid
literal, with valueA fixed string, number, boolean or null

A source of any other kind is skipped with mapping.unknownSource, a component the form lacks with mapping.unresolved. One bad mapping never stops the others.

checkedValue is the value that means on, for a checkbox or a radio group. When the answer is on, the field takes the checked value itself: a checkbox is ticked, the radio option of that name is selected. A ticked checkbox answer is on; any other answer is on when it is or contains the checked value. When off, the box is unticked or the group cleared.

values turns answers into what the PDF stores. Many forms store radio options as 1, 2, 3 while the page shows words. Keys are answers as text; a boolean is keyed true or false. The map applies first, before checkedValue compares and before format shapes. An answer with no key passes through unchanged and warns mapping.unmappedValue. A checkboxes answer is translated key by key.

format shapes the value after that.

FormatpatternResult
textNoneThe value as it is
dateNoneThe value as it is: dates are written in ISO form, 2026-11-14
numberThe number of decimals, 0 to 201250 with pattern 2 is 1250.00. A value that is not a number is left as it is
booleanTwo words joined with a vertical bar, such as Oui and NonThe first when the answer is on, the second when it is off. Left out, the PDF theme's yes and no

Areas ​

An area draws an answer into a rectangle on a page, for a PDF with no form fields: a scanned or hand-laid form. An area has the same source, checkedValue, values and format as a mapping.

KeyMeaningDefault
idUnique among the layout's areasRequired
labelWhat the designer calls the areaThe id
pageA page number from 1Required
rectx, y, width, height in points from the page's left and top edges. Width and height above zeroRequired
draw.kindtext for wrapped text, check for a tick when the value means checkedtext
draw.fontSizePoints, at least 110
draw.alignstart, center, endstart
draw.valigntop, middle, bottomtop
draw.paddingPoints between the box and the text2
draw.wrapWrap long text. Off, one line clipped at the box's edgetrue
draw.boldBold textfalse
draw.color#rrggbbThe theme's text colour
fieldMakes the area a transparent AcroForm widget instead of page content, so the PDF becomes fillable where the paper had a blank. name, required, readOnly, tooltipNot a field

A field's name is kept as typed, and two areas that type one name share one field. Without a name it is the area's label made usable (periods become spaces, because a period would start a path of fields), else its id, made unique among the areas (Date, Date_2). The tooltip defaults to the label. A widget carries size, alignment, bold, colour and wrapping from draw; valign and padding do not carry over, since viewers place a field's text themselves.

Each area is reported as filled, empty (nothing to draw), overflow (the text was clipped; warns area.overflow), missing (the PDF has no such page; warns area.page) or unsupported.

Fill options ​

OptionMeaningDefault
flattenBurn the values into the page and drop the fieldsfalse
readOnlyKeep the fields, and lock the ones the layout fills. A fillable area locks only when it has an answerfalse
appearancesregenerate: the kernel draws each field's appearance so every viewer shows the same. viewer: leave it to the viewer, which keeps the template's own look for scripts and fonts the kernel cannot reproduceregenerate

Under PDF/A the appearances are always regenerated, and viewer warns pdfa.appearances. A form that cannot be flattened warns template.flatten.

A value longer than a field's maximum length is clamped to it and warns field.overflow.

What a template can be ​

  • Encrypted templates. A PDF encrypted only with an owner password, which needs no password to open, is read decrypted and the filled file is written unencrypted, with template.decrypted. The owner's restrictions are not carried over. When the owner's permissions forbid filling, the fill is refused with the template failure. When they forbid modifying and the fill flattens or draws areas, it goes ahead and warns template.permissions. A PDF that needs a password to open, or uses another security handler, is refused with the template failure: supply an unencrypted copy. An encrypted template under PDF/A is refused with the conformance failure.
  • XFA forms. The XFA part is removed and the AcroForm fields fill, with template.xfa_removed. A form that has only XFA content has no fields to fill.
  • PDF/A templates. A template that declares a PDF/A level stays PDF/A through the fill. Asking a template that declares none for a PDF/A level warns pdfa.template and the file claims none.
  • Widgets. Duplicate widgets and widgets with no page, as some PDF re-savers leave behind, are re-linked to their page with template.widgets_relinked, or reported with template.widgets_detached when they cannot be placed.

The designer lists at most 500 pages and 5,000 fields of a template and warns template.truncated past that.

MIT licence. Your forms, your data, your keys.