How-to
Website
Slides
Render a template with data
A template is a .wf file with a page, rendered once with the data you hand it: an invoice, an email, a block of a page your server already draws. wf render turns it into HTML, a fragment, a PDF or slides. You need the wf command installed (Getting started).
type Customer { name: String }
type Item { name: String, qty: Number, price: Number }
page Invoice(path: "/", title: "Invoice", description: "An invoice.",
number: String, customer: Customer, items: [Item], total: Number, paid: Bool) {
Heading("Invoice #{number}").h1
Text("Bill to: {customer.name}")
Table {
Table.Head { Table.Row { Table.Cell("Item") Table.Cell("Qty") Table.Cell("Amount") } }
Table.Body {
for item in items {
Table.Row {
Table.Cell(item.name)
Table.Cell("{item.qty}")
Table.Cell(format(item.price * item.qty, .currency))
}
}
}
}
if paid { Badge("Paid").success } else { Badge("Due").warning }
Text("Total: {format(total, .currency)}").bold.lg
}
The data is a JSON object, saved here as invoice.json beside the template, invoice.wf:
{
"number": "INV-001",
"customer": { "name": "Acme Corp" },
"items": [{ "name": "Widget", "qty": 5, "price": 9.99 }],
"total": 49.95,
"paid": false,
"locale": "en"
}
This command renders the template with the data and prints the markup to standard output:
$ wf render invoice.wf --data invoice.json --format html-fragment
How it works
Rendered, the page reads Invoice #INV-001, Bill to: Acme Corp, one table row (Widget, 5, $49.95), the badge Due and Total: $49.95.
The page says what data it takes, as its parameters: number, customer, items, total and paid, each of its type. Every render holds the data to them first, and data that does not fit is refused with the place it goes wrong — T33: the data is not what Invoice takes: $.items[0].price is missing — rather than drawn as an empty cell. A name the page reads that is neither a parameter nor declared is T13, found when the template is loaded. Keys the page does not take, such as locale, are passed through. A template uses the static subset of the language: no handlers, stores, resource or motion (see What a template may use).
wf render takes these options:
| Option | What it does |
|---|---|
|
|
The JSON data. When it is omitted, the data is read from standard input |
|
|
|
|
|
Writes to a file instead of printing |
|
|
Picks one of several |
|
|
Sets a design token over the theme's; repeat it for more |
|
|
Sets the document's language, |
|
|
Chooses the page to render when the template has several |
A template that names a component nothing declares, or a flag a component does not take, is refused, as a build would refuse it.
What a template may use
A template uses the static subset of the language, because there is no browser to run the rest:
| Supported | Not supported |
|---|---|
| Every layout, typography and data-display element |
|
|
|
Handlers ( |
|
|
Navigation |
|
|
Stores |
|
|
Animations |
|
|
A |
A state is its first value, and a derived value is what that works out to. So a page may work out its totals once, in order, and show them anywhere. A value the data hands over wins over either.
A resource sends no request at render time, so it draws its .loading arm, unless the data gives it a value by its name: { "users": { "loaded": [ … ] } } draws .loaded, and { "users": { "failed": { … } } } draws .failed. What loaded holds is held to the read's type (T33).
A template may declare types and a theme like any file. data files are read relative to the template. format and ago speak the data's locale key when it has one, and English otherwise.
A template may read private env names (Environments and secrets): it runs on your server, where a secret stays secret.
Pick an output for the job
| Job | Output |
|---|---|
| An email |
|
| Invoices and reports |
|
| A piece of an existing page — an HTMX response, a CMS block |
|
Troubleshooting
| What you see | What to do |
|---|---|
| The render fails with "no page called …" |
Pass one of the page names the message lists to |
| A render refuses a component or a flag |
Declare the component in the template's files, or use a flag the component takes — the same checks as |
|
|
Install |
|
The render fails with |
The data is not what the page's parameters say; the message names the place, |
|
A |
A page that declares no parameters reads whatever it is given: the data has no top-level key |
|
|
Add a |
|
The render fails with |
The template nests too deeply, or the render does too much; see Limits of one render |
Variations
The template may also be a directory. Every .wf and .wfx file under it renders as one template, with components shared, and --page Name chooses the page. This command renders the Invoice page of templates/ to a PDF, in Arabic:
$ wf render templates/ --page Invoice --lang ar --data invoice.json --format pdf -o invoice.pdf
To render from a program instead of the command line, use the Rust crate (Render templates from Rust) or the Node binding (Render templates from Node).