Skip to content

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 Frontforge Report Server: documents of three made-up organisations (Larkmere Water, a water utility; Quillmont Software, which makes an inspection app; and Ostrand & Pell, an engineering consultancy), 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).

The examples are free to use: they are dedicated to the public domain (CC0 1.0), so a copy is yours to change and use for anything, with no credit needed.

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 ​

ExampleWhat it shows
Water billA 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 accountA 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 invoiceA 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 customersA 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 dashboardOne landscape page: KPI tiles that turn red when a target is missed, column, line and donut charts, and a matrix with totals.
Meter readings reportA 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 certificateOne 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 labelA 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.
Fieldbook user guideCustomer documentation for a made-up app: a cover with an illustration, a table of contents, numbered chapters with footnotes, note, warning and tip boxes, left and right pages with mirrored margins and the chapter in the header, and a two-column glossary.
Fieldbook release notesRelease notes for a software product, newest version first: a coloured badge on each change (New, Improved, Fixed, Security, Deprecated), links to each issue, a contents list that links to each version, and a known issues box only when there are any.
Fieldbook quick-start cardAn A5 card in English or German from one template: every word comes from the translations, and dates, numbers and prices follow the language. Numbered steps, drawings, a support hours table and a QR code.
Certificate of completionOne landscape certificate per participant who finished a course: border art behind the page, the name set large, a distinction line for high scores, signatures either side of a centred seal, and a QR code to verify it.
Monthly management packFour A4 pages for a month and a region you pick: KPI tiles that turn red when a target is missed, revenue against budget, utilisation and pipeline charts, a matrix of fees by region and service line, active projects, and each region's commentary. In the HTML viewer, a region opens to its projects and a project to its note.
Expense claimA simple starter: a table of expenses with GST, a receipt thumbnail on each line chosen from the data, totals, and the manager's approval.
Purchase orderParameters that choose the copy and hide prices, supplier and delivery blocks, totals with GST, a barcode of the PO number, an "Approved" stamp, and terms and conditions on the last page.
Staff roster and timesheetOne landscape page: a matrix of staff by day with totals, overtime, leave and weekends in colour, and a legend.

Their first pages, laid out in your browser from the gallery's own files and sample data:

Water billLaying out…
Statement of accountLaying out…
Works invoiceLaying out…
Letter to customersLaying out…
Operations dashboardLaying out…
Meter readings reportLaying out…
Backflow test certificateLaying out…
Parts dispatch labelLaying out…
Fieldbook user guideLaying out…
Fieldbook release notesLaying out…
Fieldbook quick-start cardLaying out…
Certificate of completionLaying out…
Monthly management packLaying out…
Expense claimLaying out…
Purchase orderLaying out…
Staff roster and timesheetLaying out…

Your organisation's templates ​

With more than one source, the templates are grouped by source, each under its name: Example gallery, 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.

Categories and levels. When the templates have categories, such as Billing, Documentation or Internal business in the example gallery, chips beside the Source list show one category at a time, each with how many templates it has. A card also shows its level: Starter for a short document that uses a few features, Intermediate, or Advanced for one that uses many. Your organisation's sources can give their templates categories and levels too (operations/template-sources.md).

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 Report Server 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, the catalog says so above the reports, with Open trash and (for whoever manages the licence) Licence…; New report, Import and the copies wait until one is moved to the trash (the trash doesn't count), or a licence allows more, and their tooltips say why. At 4 a quiet line says how many are left. The API answers 409 licence-limit.

Templates that can't be copied ​

A template made for a newer RFML version than this Report Server writes is listed, but greyed, with its reason under its description: "Needs Report Server 0.10.0 or later (RFML 0.3)", or "Needs a newer Report Server (RFML 0.3)" when this Report Server 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 Report Server 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 Report Server reads, or an administrator to upgrade Frontforge Report Server. 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 Report Server, with its files at the top or in one folder;
  • a template.rfml.json on 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.

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):

ValueMeaning
unsetThe published gallery: https://raw.githubusercontent.com/frontforge-corporation/report-server-releases/main/gallery/
another https:// addressA 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 folderA downloaded copy of the gallery, for a machine without internet access
offNo gallery: the first run offers a blank page and import only

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 ​

RouteDoes
GET /v1/examplesThe 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}/copyCopies 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.