Appearance
Starting from a template
A new report can start from a template: a finished report you copy and make your own. Templates come from template sources:
- The example gallery, which comes with Reportforge: documents of Larkmere Water, a made-up water utility, each with sample data and tests, so it previews, renders and passes its checks as soon as it is copied.
- Your organisation's own templates: its letterhead, its invoice, its statement, kept in a git repository, a folder on the server or a published gallery, and maintained by its own people. An administrator adds these sources on Admin's Template sources page; they need a licence with template sources (operations/template-sources.md).
Nothing from a source is in your catalog until you pick it. Everyone who can make reports sees the templates of every source that is on.
The examples
| Example | What it shows |
|---|---|
| Water bill | A two-page A4 bill: values worked out from the data, a usage chart against the regional average, charges grouped by service with subtotals, and a tear-off payment slip with a barcode on the last page. |
| Statement of account | A long transaction table that breaks across pages, with a running balance, "carried forward" and "brought forward" rows, an ageing summary and "Page n of N". |
| Works invoice | A tax invoice: line items with GST, a discount, totals kept together, a QR code to pay, and a header that repeats when the invoice runs over. |
| Letter to customers | A letter: a letterhead on the first page, the address placed for a window envelope, fields merged into the text, a schedule table and a signature. |
| Operations dashboard | One landscape page: KPI tiles that turn red when a target is missed, column, line and donut charts, and a matrix with totals. |
| Meter readings report | A table-heavy report: readings grouped by zone with subtotals and a grand total, unusual readings flagged, a repeated header and a table of contents. |
| Backflow test certificate | One landscape certificate per test, a border drawn in the page background, a result that changes the wording, signature lines and a QR code to verify it. |
| Parts dispatch label | A 4 × 6 in label per parcel, large type, a Code 128 barcode and a DataMatrix, and a "Fragile" stamp only on the parcels that need it. |
Their first pages, laid out in your browser from the gallery's own files and sample data:
Your organisation's templates
With more than one source, the templates are grouped by source, each under its name: Larkmere Water examples, then your organisation's, such as Finance templates, in the order the administrator added them. A Source list above them shows one source at a time.
Each card shows the template's first page, drawn from the source's copy with its sample data, its title and what it is for. A source that can't be reached right now, a repository whose server is down, say, is one line in its place: "Brand letters can't be reached right now." The others still list, and an administrator sees why on the Template sources page.
Copying one
- The first time. A catalog with no reports shows the example gallery under Start from an example. Pick one: it is copied into the catalog and opens in the designer with a short tour. When the administrator has turned the example gallery off, the same place shows Start from a template, with your organisation's sources instead. Start from a blank page opens the New report wizard (new-report.md), and Import a report takes a file.
- Later. In the catalog, New report, then From a template. Pick one, and change the title, the id and the folder if you like. Create and open copies it. The command palette's New report from a template opens the same.
The copy is a new draft in the environment you are in, as a blank report would be. It takes the template document's own id, or the next free one (water-bill-2) when that id is taken or in the trash. Its edit history says where it came from:
- an example: "from example water-bill";
- one of your organisation's templates: its source, its folder in the source and the commit it was read at, "from Finance templates: invoices/standard @ 1a2b3c4".
A copy isn't linked to its source: later changes there don't reach it, and removing the source leaves it as it is.
Versions. A template is copied in the RFML version this Reportforge writes. One made for an older version the engine migrates is stored as the engine migrated it, and the history says so ("from example water-bill, RFML 0.1 → 0.2"). The same goes for a report you import (operations/template-sources.md).
A copy counts as a report. Community allows 5 reports (licence). The templates themselves don't count: only the copies you make. When there are 5, New report and the copies wait until one is deleted, or a licence allows more; the API answers 409 licence-limit.
Templates that can't be copied
A template made for a newer RFML version than this Reportforge writes is listed, but greyed, with its reason under its description: "Needs Reportforge 0.10.0 or later (RFML 0.3)", or "Needs a newer Reportforge (RFML 0.3)" when this Reportforge doesn't know which release writes it. One made for a version older than anything the engine reads says "Made for an RFML version this Reportforge can't read". The engine can't draw either, so the card shows No preview and the version instead of the first page.
Such a card can't be picked: a screen reader announces it as unavailable, with its reason, and the arrow keys pass over it. Ask whoever maintains the source to save the template in a version this Reportforge reads, or an administrator to upgrade Reportforge. Through the API the copy is refused with 409 rfml-too-new or 422 rfml-unsupported.
The tour
A report opened from the first run's gallery starts a tour of three stops: the canvas, the Inspector and the preview. Each stop is a small panel beside the part it is about, which is outlined.
- Next and Back move between the stops, and Done ends it. Skip tour, or Escape, ends it at once.
- The keyboard works throughout: focus moves to each stop, so a screen reader reads it, and Tab stays in the panel until it closes. Focus then goes back where it was.
- Show the tour in the command palette starts it again, on any report.
Importing a report
Import in the catalog (or Import a report in an empty one) takes a file:
- a report's
.zip: an example downloaded from the gallery, or a report from another Reportforge, with its files at the top or in one folder; - a
template.rfml.jsonon its own.
It becomes a new draft in the current environment, under the document's id or the next free one, with the same checks as any new report, and the same version check as a copy: a newer RFML version is refused (409 rfml-too-new), and an older one upgraded. API users send the file to POST /v1/templates/import.
Where the gallery comes from
reportd reads the gallery from the public repository, frontforge-corporation/report-server-releases, in its gallery/ folder. It asks at most once an hour, through the same network guard as data sources, and on a machine without internet access it fails quietly: the studio then says the gallery can't be reached, with a link to the downloads.
The setting is examples.gallery (REPORTD_EXAMPLES_GALLERY):
| Value | Meaning |
|---|---|
| unset | The published gallery: https://raw.githubusercontent.com/frontforge-corporation/report-server-releases/main/gallery/ |
another https:// address | A copy of the gallery on your own public server: a folder with index.json and a .zip per example. The guard refuses an address inside your network; use a folder for that |
| a folder | A downloaded copy of the gallery, for a machine without internet access; or the repository's examples/, for development |
off | No gallery: the first run offers a blank page and import only |
reportd init-config --kind developer sets it to examples, the repository's folder, so a developer's reportd shows the examples as they are being written.
The gallery is one template source, the preset examples, which an administrator can also turn off on Admin's Template sources page. With a licence that has the template-sources feature, an organisation adds its own: git repositories, folders and galleries of its templates. Setting them up is in operations/template-sources.md.
The API
| Route | Does |
|---|---|
GET /v1/examples | The templates of every source that is on, the example gallery first, each with its source, rfml and status (available, too-new or unsupported, with a reason), and a sources list saying whether each could be read. ?source= lists one source. |
GET /v1/examples/{source}/{id} | A template's document and its JSON files, for its thumbnail, whatever its status |
POST /v1/examples/{source}/{id}/copy | Copies it as a new report's first draft |
The one-segment paths, GET /v1/examples/{id} and POST /v1/examples/{id}/copy, are the example gallery's (examples), as they always were. The API reference has the details.
For contributors
The examples live in the repository's examples/ folder, one bundle each, listed in examples/gallery.json in the order the gallery shows them. Its README.md says what each holds and how they are checked. cargo xtask gallery <folder> builds the published gallery from them.