Making a new report

New report in the catalog (or N in its list, or the command palette's New report) opens a wizard. Its first step asks what the old dialog asked: a title, an id and a folder. Create and open works from there, so a report you want to set up yourself is still one screen. Or go on: each later step sets up part of the report's first draft, and a preview beside it shows the first page as it will be.

To copy a finished report instead, choose From a template on the first step (examples.md).

The steps

The rail on the left lists them. Click one, or move along it with the arrow keys, to go there in any order; Next and Back walk them in turn. A step you passed over is marked skipped and keeps its defaults, and one with something to fix is marked needs attention.

Step	What it sets
Basics	The title, the id (which follows the title until you change it, and can't be changed later) and the folder.
Look	A library's theme, imported, or none. Then the body font, the headings' colour and the chart colours, over the theme's or the report's own.
Page	A library's page template to start from, copied in (never imported), or a plain page. Then the size, orientation and margins; a header with the title and the date it runs; a footer with "Page X of Y"; and a first page without the header, for a cover or a letter. A library's template keeps its own header and footer.
Data	Where the data comes from. Sample JSON, pasted or uploaded: one record as the report gets it, whose fields and types are worked out from it; a guess can be wrong (an account number that looks like a number, a date kept as text), so each field's type can be changed. JSON Schema, pasted: a sample is made from it. Data source: one from the catalogue, its sample copied in and each of its parameters filled from an expression, by default the report parameter of the same name, added when the source needs it. Or No data yet. The dataset is data.main unless you name it.
Parameters	The values the report is run with: Date range (from and to), Id, Copy type (original or copy), or Another, each with a type, a label, a default expression and whether it is required.
Layout	The kind of report to start from, filled in from the data: Blank (just the title); List or table (a list's items, the columns you tick, sorted, with sums of the amounts); Grouped with subtotals (the same, grouped by a field, each group with its heading and subtotals); Dashboard (a chart of a value by category over the table); Invoice or statement (the customer's name and address and the document's number and dates at the top, then the lines and their total); Letter (the recipient, the date, a subject and a body to write); Labels (one label per item, on pages the size of the label, with an optional barcode). The wizard guesses each pick from the fields' names and types; change any of them. Starters that repeat over a list need data with one.
Extras	A stamp across each page (Draft, Copy, Paid, Void or Confidential), always or when a parameter has a value, such as the copy type's Copy; it is in the page's overlay, so the report is RFML 0.2. The PDF standard (PDF/A, PDF/UA). The locale and currency, and further languages it will be translated into, each an empty set of messages to fill in. A test of the sample data, which checks the report renders it with no errors, for the Tests panel.
Review	What each step chose, with a way back to each, anything that still keeps the report from being made, and its first page.

What a report starts with

What you don't set up has a default that makes a usable page:

• The page: A4 with 20mm margins, or Letter with 0.75in margins where Letter is the paper (the United States, Canada and a few others, from the browser's language and region).
• A header and a footer: the title at the left and the date at the right along the top, and "Page X of Y" at the right along the bottom, in small grey type.
• Type: Noto Sans at 10pt (one of the engine's bundled fonts, so it needs no font file), with headings in one accent colour. With a theme, the theme decides these.
• The locale and currency of the browser's language and region, such as en-ZA and ZAR.
• The title as the first heading.
• No data and no parameters, until you add them here or in the designer's Data panel.

A sample or a schema goes into the report's bundle as samples/<name>.json and schemas/<name>.json, which the dataset names, as the gallery's examples do; a data source's sample is copied as samples/<name>.json.

Everything here is ordinary RFML in the report's draft, so the designer changes any of it later.

For developers

• @report-forge/starters (web/packages/starters, framework-free) holds the layout starters (STARTERS: each guesses its picks from the data and builds its nodes with the region and chart wizards' generators, regionNode and chartNode), the answers (StarterAnswers), their defaults (defaultAnswers) and buildReport, which turns them into the document and the bundle files, and problems, which says what keeps a report from being made, by step. It writes RFML 0.1 unless an answer needs 0.2 (needs02, from the designer's uses02). withPageSetup in @report-forge/pages sets up a page template as JSON.
• The wizard is NewReportDialog.vue in web/apps/designer/src/catalog, with a component per step in catalog/new/ and the step rail RfSteps from the kit. The preview is previewFirstPage (firstPages.ts), which resolves the theme's library before the engine lays the page out.
• The report is made with one POST /v1/templates (the document and its sample and schema files), then filed with PUT /v1/templates/{id}/folder, as before.
• Tests: build.test.ts and engine.test.ts in the package (every starter laid out by the real engine), and web/e2e/tests/new-report-wizard.spec.ts.