Skip to content

The PDF designer element ​

<datum-pdf-designer> is the builder's PDF workspace on its own: the layout list, the page designer, template mode and the preview, without the form editor around them. Use it on a page where someone designs a form's PDF layouts and nothing else.

html
<link rel="stylesheet" href="datum-builder.css">
<script type="module" src="datum-builder.js"></script>

<datum-pdf-designer layout="contained" style="height: 720px"
  src="/forms/intake.json"
  values='{"fullName":"Ada Lovelace"}'></datum-pdf-designer>

<script type="module">
  const designer = document.querySelector("datum-pdf-designer");
  designer.addEventListener("datum-pdf-layout-change", (event) => {
    save(event.detail.definition);
  });
</script>

It is defined by datum-builder.js, beside the builder, and it loads the same PDF files from the bundle folder. values gives the preview sample answers to draw.

What differs from the builder ​

  • It shows the PDF workspace alone. There is no workspace switch, and the form's components, rules and journeys pass through untouched.
  • Its bar does not carry New, Open and Download unless the page names them in file-actions, such as file-actions="download".
  • The PDF side is always on, whatever a features list says.

Attributes ​

Every attribute and property of the builder element applies, including src, definition, save, pdf-theme and layout. One is its own:

Attribute and propertyWhat it does
layout-id
layoutId
Which of the definition's PDF layouts is on the page.
Takes layout id. Default the definition's default layout, else the first.

Events ​

EventWhen
datum-pdf-designer-readyA layout is up and the methods can be called. detail.layout is that layout.
datum-pdf-layout-changeA layout changed. detail.definition is the form with its layouts as they stand; detail also has layout, pdf (the layouts block) and reason.
datum-pdf-layout-selectAnother layout was put on the page. detail has layoutId and layout.

The builder's own events, such as datum-builder-save and datum-error, fire here too.

Properties ​

PropertyWhat it is
layoutIdWhich layout is on the page, as the layout-id attribute. Setting it selects that layout once the designer is up.
layoutsThe layouts, in the definition's order.
pdfLayoutThe layout on the page as designed so far. Assigning a layout replaces the one with that id, or adds it, and puts it on the page.
readyWhether the layout on the page is up.
designerThe PDF designer behind the panels, when one is up.
controllerThe builder controller over the layout's tree.

Methods ​

A page with its own layout list drives the designer from script.

The designer is loaded in a chunk of its own, so for a moment after the element connects its methods throw an error ("The PDF side is not set up yet"), and they keep throwing if pdf="off" is set or the chunk fails to load. Wait for datum-pdf-designer-ready before calling one. previewPdf() and renderPdf() do not throw: they return a promise that rejects in the same cases.

MethodDoes
selectLayout(id)Puts a layout on the page.
newLayout(options)Makes a layout and returns it. options is { name, from, select }: from is "form" (derived from the form), "blank" or "copy" of the layout on the page; select defaults to true.
addLayout(layout, { select })Adds a layout the page made or loaded.
addTemplateLayout(source, name)Adds an existing PDF as a template layout, ready for its fields to be mapped. source is { storage, name, type, size, data } for a file held in the layout as base64, or { storage, name, type, size, ref } for a file your own store holds (see Offering your own PDFs).
replaceLayout(id, layout)Swaps a layout for another under the same id.
duplicateLayout(id, options)Copies a layout and returns the copy. options may carry id, name and select.
renameLayout(id, name)Renames a layout.
moveLayout(id, toIndex)Moves a layout in the order they are tried in.
setDefaultLayout(id)Makes a layout the one drawn when no condition holds.
removeLayout(id)Removes a layout.
openAdd(anchor)Opens the designer's own Add menu, beside an element of the page's.
previewPdf()Draws the preview now.
renderPdf({ layoutId })Draws the PDF and resolves with a result whose bytes are the file, with pageCount, warnings, layoutId and fileName.

Layouts, templates and what a PDF can carry are described in PDFs.

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