How-to
Website
Slides
Render templates from Node
The Node binding is a small wrapper around wf render: it renders a template with your data as HTML, a fragment, a PDF or slides. This Express server answers with an invoice in either form. You need Node.js, npm and the wf command, and a template like the one in Render a template with data. This one is templates/invoice.wf:
type Customer { name: String }
type Item { name: String, qty: Number, price: Number }
page Invoice(path: "/", title: "Invoice {number}", 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
}
Install the binding and Express. The binding is not on the npm registry yet, so it comes from a clone of the repository; wf must be installed too, since the binding runs it:
$ git clone --depth 1 https://github.com/monzeromer-lab/WebFluent.git
$ npm install ./WebFluent/bindings/node express
This is the server, server.js:
// server.js
const path = require("node:path");
const express = require("express");
const { Template } = require("webfluent");
// Every .wf and .wfx under templates/, as one template; its Invoice page.
const invoice = Template.fromDir(path.join(__dirname, "templates")).page("Invoice");
// Your own data source; one invoice, kept in memory here.
const invoices = {
"INV-001": {
number: "INV-001",
customer: { name: "Acme Corp" },
items: [{ name: "Widget", qty: 5, price: 9.99 }],
total: 49.95,
paid: false,
},
};
const app = express();
// The PDF route comes first, so `/invoices/INV-001.pdf` is not read as an id.
app.get("/invoices/:id.pdf", async (req, res) => {
const data = invoices[req.params.id];
if (!data) return res.sendStatus(404);
res.type("application/pdf").send(await invoice.renderPdfAsync(data));
});
app.get("/invoices/:id", async (req, res) => {
const data = invoices[req.params.id];
if (!data) return res.sendStatus(404);
res.send(await invoice.renderHtmlAsync(data));
});
app.listen(3000, () => console.log("http://localhost:3000/invoices/INV-001"));
How it works
Run node server.js and open /invoices/INV-001 for the page, or /invoices/INV-001.pdf for the PDF.
Template.fromDirreads every template under the directory, with components shared, andpage("Invoice")picks the page to render.Template.fromFileandTemplate.fromStringload one template instead. The server loads it once, at start-up.- Every render has a synchronous form (
renderHtml,renderHtmlFragment,renderPdf,renderSlides) and an…Asyncform that does not block the event loop. Use the…Asyncforms in a server, as this one does. withTheme,withTokensandwithLangset what the Rust API sets (Render templates from Rust), and each returns the template, so they chain before a render.- The data is held to the page's parameters before anything is drawn: a field missing or of the wrong type throws, its message naming the place (
T33 … $.items[1].price is missing). - A render runs
wfonce and takes a few milliseconds. The data goes over standard input, so it is never written to disk; a template given as a string is written to a temporary file once, the first time it renders.
The binding needs wf itself installed. It looks for it at WF_BIN, then on PATH, then in ~/.webfluent/bin and ~/.cargo/bin (and, outside Windows, /usr/local/bin and /usr/bin). Its version is the compiler's.
Troubleshooting
| What you see | What to do |
|---|---|
|
|
Install |
| The render fails with "no page called …" |
Pass |
|
A render throws |
The data is not what the page's parameters say; the message names the place |
|
A |
The page declares no parameters, and the data has no top-level key |