Skip to content
Documentation menu

Templates

Documents and labels as versioned templates: codes, structure, expressions, drafts, published versions and rollback.

A template describes a document: its page, its data and its layout. You design it in the Designer, publish it as an immutable version, and your applications render it by its code through the API.

What a template is

A template has a few properties of its own and a list of versions, each with a complete definition:

codestringrequired
How applications refer to it: DELIVERY_NOTE, INVOICE. Unique in the workspace, it never changes.
formatPDF document · ZPL label
Chosen at creation; the editor never changes it.
descriptionstring
The name shown in Prynt (up to 400 characters).
document typeenum
Delivery note, Invoice, Order, Order confirmation, Quote, Packing list, Product sheet, Label, Report, Component or Other: for filtering and organizing.
statusActive · Disabled
A disabled template cannot be rendered.
current versioninteger
The published version the API renders when a request names none.

The definition of a version holds the page setup, the parameters, the datasets and their relations, the translations and the layout (or, for a label, the label).

PDF documents and ZPL labels

  • PDF document: banded documents such as delivery notes, invoices, orders, certificates and reports, rendered as PDF on A4, A5, A3, Letter, Legal or a custom size.
  • ZPL label: labels for Zebra thermal printers, rendered as ZPL code that the printer runs, at 203, 300 or 600 dpi. They have their own editor; see ZPL labels.

Everything else is shared by both formats: parameters, datasets, expressions, versions, publishing and the API. To turn a PDF label into a ZPL label, create a new template.

Components

A template of type Component is a reusable block, for example the company header, embedded in other templates with the Subreport element. It receives the parameters of the template that includes it by name. When a template is published, the component's current version is pinned in it, so later changes to the component do not alter published documents. Up to 3 levels of components can be nested.

The template code

  • Upper-case letters, digits, _, . and -, starting with a letter or digit, at most 100 characters (spaces become _ as you type). Names reserved by Windows (CON, NUL, COM1…) are refused.
  • It is unique in the workspace and cannot be changed: it is the stable contract with your applications. To get a template under another code, clone it.
  • Keep it short and meaningful: INVOICE, DDT_STANDARD, LABEL_SSCC.

Structure of a document

A PDF document is laid out in bands, horizontal strips measured in millimetres:

Page headerband
On every page (or only some: first, all but first, last, all but last).
Report headerband
Once, at the start of the document.
Bodysections
Static bands, printed once, and data regions, which repeat for every record of a dataset.
Report footerband
Once, at the end (totals, signatures).
Page footerband
On every page: page numbers, legal notes.
  • A data region iterates a dataset, with optional filter and sort, its own header and footer, a band for no data, groups (a key expression, group header and footer) and nested regions linked by a relation.
  • Elements sit in bands: text, field, image, line, rectangle, table, barcode (Code 128, Code 39, EAN-13, EAN-8, UPC-A, ITF, Data Matrix, PDF417), QR code, page number, total pages and subreport.
  • Bands can grow and shrink with their content, avoid splitting across pages and force page breaks; tables break between rows and repeat their header.

Bindings, expressions and formats

Elements are bound to data with a small, safe expression language (no code execution, no loops). Fields and conditions take a bare expression; texts embed expressions between double braces.

CUSTOMER.NAMEfield
A field of a dataset.
Params.DOCUMENT_IDparameter
A parameter of the template.
LINES.QTY * LINES.PRICEcalculation
Arithmetic with exact decimals.
sum(LINES.AMOUNT)aggregate
sum, count, avg, min, max, first, last, with an optional scope: report, region, group, page.
Page {{PageNumber}} of {{TotalPages}}text
A text with embedded expressions.
if(H.PAID, "Paid", "Due")function
Text, number, date and conditional functions; t("KEY") for translations.

A format on a field uses .NET format strings: #,##0.00, dd/MM/yyyy, d MMMM yyyy. Numbers and dates follow the language of the render (IT, EN, DE, FR, ES): 1.234,50 in Italian, 1,234.50 in English. Visible if hides an element or band with a condition, and conditional formats change color, background, bold or italic. The Designer guide has more examples.

Drafts and versions

  • You always edit the draft; a template has at most one. Saving is explicit (Ctrl+S) and the draft is never seen by your applications.
  • Publish checks the draft with the engine: errors block publishing, warnings do not. You add a note, and the draft becomes a published version with the next number (1, 2, 3…) and the current version. A template.published webhook is sent.
  • A published version is immutable and self-contained: shared queries are copied into it, components and images are pinned to their content at that moment. Nothing that changes later alters a published document.
  • To change a published template, create a new draft from a version (or tick Create a new draft from the published version right away when publishing), edit it and publish again.

From the next render on

A new current version is used by the API from the next request: there is nothing to deploy. Requests that name a version keep rendering that version while it is published.

Version history and rollback

Versions in the Designer lists every version with its status (Draft, Published, Archived), note and dates; the star marks the current version. For each version you can open it read-only, start a new draft from it, export it, or:

  • Make current (rollback): the API goes back to rendering that published version at once. Rollback only moves the pointer; no version is modified.
  • Archive / Restore from archive: an archived version cannot become current until it is restored, and the API stops rendering it at once, also for requests that name it; the current version cannot be archived. You can still open an archived version read-only and preview it.
  • Compare two versions side by side.

Publishing, rolling back and archiving need the templates.publish permission (developers, admins, owner); editing drafts needs templates.write (designers and above). Published versions are never deleted.

Clone, disable, delete, export

  • Clone: a new template with another code, starting from the draft or a published version, with a copy of the template's own assets.
  • Disable: the API refuses to render the template (409 TEMPLATE_DISABLED) until you enable it again.
  • Delete: removes the template from the workspace; its code becomes available again. A component used by other templates cannot be deleted.
  • Export .prynt / Import: a package with the definition and its images, to move a template to another workspace or installation, as a new template or as a new draft of an existing one.

Templates in the API

Applications render a template by its code; the version is the current one unless the request names another, and the environment only decides which databases are read:

Render the current version
curl -X POST https://api.prynt.it/api/v1/render \  -H "Authorization: Bearer prynt_live_..." \  -H "Content-Type: application/json" \  -d '{ "template": "DELIVERY_NOTE", "parameters": { "DOCUMENT_ID": 18425 } }' \  -o delivery-note-18425.pdf
  • X-Template-Version in the response tells which version was rendered.
  • GET /v1/templates lists the published, active templates; GET /v1/templates/{code} returns one with its parameters (and their JSON Schema) and datasets.
  • A template without a published version answers 404 TEMPLATE_NOT_PUBLISHED; an unknown code 404 TEMPLATE_NOT_FOUND; a format that does not match the template (pdf for a label) 422 FORMAT_MISMATCH.
  • A request that names a version renders only a published one: an archived version answers 409 VERSION_ARCHIVED; a draft or a number that does not exist 404 VERSION_NOT_FOUND.

See the API reference.