Documents

A document is something your app renders for people to keep, such as an invoice as a PDF. The documents capability renders a typed template to HTML or PDF, exactly as email renders a message. A document is a type X = Document { ... } whose fields are the values its template uses. It lives in its domain's documents/ folder, beside its .html template. The template follows the strict template rules, reads translations. in the locale it is given, and is wrapped in the optional shared/documents/layout.html.

Not built yet: documents: is toolchain.not_built_yet where it is written, so this is the design. Here an invoice is rendered to a PDF by a subscriber, through Gotenberg, and kept as a file:

// domains/billing/documents/invoice_document.jadpo/// An invoice as the customer receives it.type InvoiceDocument = Document {    number: InvoiceNumber    customer_name: PersonName    total: PresentationText}// app.jadpoapplication {    connections: {        pdfs: {            package: Gotenberg.v8            domains: [billing]        }    }    documents: {        connection: pdfs    }}// domains/billing/actions/render_invoice.jadpovar pdf: Bytes = attempt documents.pdf(InvoiceDocument { ... }, locale: customer.locale)var file: File = attempt invoices.put(pdf, FileType.pdf)

• documents.pdf(document, locale:) returns the PDF's Bytes. documents.html(document, locale:) returns the rendered HTML, for previews.
• documents: { layout: ... } names the shared document layout file. Leave it out and shared/documents/layout.html is used if it exists, and Jadpo's plain layout otherwise.
• The connection turns HTML into a PDF. It is Gotenberg as a container package, which jadpo dev starts in development (Services), or a hosted API's package, such as DocRaptor or PDFShift. documents: with no connection that provides documents is a compile error.
• Rendering is heavy work, so it runs in subscribers, never in a route, and no more renders run at once than the provider's max_concurrent: allows (How polls and max_concurrent: run). A documents.pdf call reached from a route is a compile error naming the subscriber shape.
• In tests the fake returns a placeholder PDF, and a test can read the rendered HTML (Provider calls and capabilities in tests).

An app that must make a PDF today describes a rendering service as a package (Call an outside API), calls it from an action, and keeps the bytes it answers with put (Files).