Templates and rendering
The template
A template is a JSON document (format erd-report-template, templateVersion 1) with pages in points. A page holds elements with a fixed frame and optional bands. Values and formulas are expression strings, and templates never contain code. A JSON Schema of the format ships with the designer for validation and editor completion.
Images are embedded as data URIs; URLs and file paths in a template are never fetched. Fonts are named by family from the ERD Report Cloud font set.
Output formats of the render API
| Format | Result |
|---|---|
| A PDF with every page. | |
| docx | A Word document. |
| xlsx | An Excel workbook with typed cells and native charts. Options in options.xlsx; an optional password encrypts it. |
| html | A complete, self-contained web page: real text, charts as inline SVG, images and fonts embedded, no script. Options in options.html (mode paged or flat); show it in a sandboxed frame. |
| png, jpeg, webp | One page rasterised, with page, dpi and quality options. |
| zpl, tspl, epl2, dymo | Label bytes for label templates. |
A render request
POST /v1/render
Authorization: Bearer erd_live_...
Content-Type: application/json
Idempotency-Key: invoice-1042-v1
{
"template": { "...": "the parsed documentJson()" },
"data": { "rows": [ { "sku": "A-100", "qty": 2, "total": 19.90 } ] },
"format": "pdf"
}An XLSX request
POST /v1/render
Authorization: Bearer erd_live_...
Content-Type: application/json
Idempotency-Key: invoice-1042-xlsx-v1
{
"template": { "...": "the parsed documentJson()" },
"data": { "rows": [ { "sku": "A-100", "qty": 2, "total": 19.90 } ] },
"format": "xlsx",
"options": {
"xlsx": {
"exportMode": "singleFilePageByPage",
"sheetName": "Invoice",
"author": "Accounts"
}
}
}A password-protected workbook
// Node, on your server. The password comes from the environment, never from the page.
const response = await fetch(`${process.env.ERD_REPORT_BASE_URL}/v1/render`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.ERD_REPORT_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': 'invoice-1042-xlsx-v2',
},
body: JSON.stringify({
template,
data,
format: 'xlsx',
options: {
password: process.env.WORKBOOK_PASSWORD,
encryptionType: 'strong',
},
}),
});
const workbook = Buffer.from(await response.arrayBuffer());An HTML request
POST /v1/render
Authorization: Bearer erd_live_...
Content-Type: application/json
Idempotency-Key: invoice-1042-html-v1
{
"template": { "...": "the parsed documentJson()" },
"data": { "rows": [ { "sku": "A-100", "qty": 2, "total": 19.90 } ] },
"format": "html",
"options": {
"html": {
"mode": "flat",
"pageRange": "1,3-5",
"classPrefix": "inv",
"title": "Invoice 1042"
}
}
}Showing an HTML report safely
// Node, on your server. The document is data from outside your site: serve it as a resource of its own,
// under the policy the service sent, and show it in a sandboxed frame.
const response = await fetch(`${process.env.ERD_REPORT_BASE_URL}/v1/render`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.ERD_REPORT_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': 'invoice-1042-html-v2',
},
body: JSON.stringify({ template, data, format: 'html', options: { html: { mode: 'flat' } } }),
});
const policy = response.headers.get('Content-Security-Policy');
if (!response.ok || !policy) throw new Error('no document, or no policy to serve it under');
res.writeHead(200, {
'Content-Type': 'text/html; charset=utf-8',
'Content-Security-Policy': policy,
'X-Content-Type-Options': 'nosniff',
'Referrer-Policy': 'no-referrer',
});
res.end(await response.text());
// In your page (not in the document itself):
// <iframe sandbox src="/reports/invoice-1042" title="Invoice 1042"></iframe>Rendering needs an ERD Report Cloud API key, and that key is a server secret. Never call the render API from the browser or ship the key in a page. The browser talks to your server, and your server talks to ERD Report Cloud.
Print through ERD-Hub
Pages that embed the designer can also print to the printers on the visitor's own computer through ERD-Hub. ERD-Hub is free to use with the designer, and its client ships with the designer package.
Frequently asked questions
Does the designer render PDFs in the browser?
No. The browser script designs templates. Rendering happens on your server through the ERD Report Cloud render API.
What does the designer cost?
The designer is for embedding in your website and is not charged for separately. Rendering uses ERD Report Cloud, which needs an API key: contact ERDesigns for a plan and a key.
Do I get the renderer?
For trials and small-scale use, the renderer is hosted by ERDesigns and is not distributed. Your server sends templates and data to ERD-Report Cloud and receives the finished document. On-premise and private cloud deployments may be available for selected use cases. Contact ERDesigns to discuss your requirements.
Can i get a free trial for ERD-Report Cloud?
Yes! Contact ERDesigns to request a free trial and explore what ERD-Report Cloud can do for your application.
Do I need a framework or a bundler?
No. The designer is one classic script and one stylesheet with no dependencies. Applications with a bundler or written in TypeScript can use the package build instead.
Can I restyle the designer?
Yes. The chrome is restyled through CSS variables, the canvas through colour tokens for light and dark mode, and the composition option hides the tools you do not want to offer.
Where are templates stored?
In your application. The designer returns the template as JSON and imposes no storage backend.
Which browsers are supported?
Evergreen Chromium, Firefox and Safari.
Can the designer design labels?
Yes. A template carries a target of paper or label. A label targets ZPL, TSPL, EPL2 or DYMO with the label stock and print head density, and the same embedding mounts as a label designer.