Building a Report

This page walks you through building a paginated report from a blank document sheet to an exported PDF.

Step 1: Create a document sheet

Open the dashboard where you want the report to live, click New Sheet, and choose Document. The sheet opens with a blank page canvas, an outline panel on the left, and a side panel on the right. The side panel follows what you select: the document, the header or footer, or a section.

Document sheets sit alongside regular dashboard sheets. Switch between them with the sheet tabs at the top.

Step 2: Configure the page

Click an empty area of the page to show the document settings in the side panel, then open the Page group.

Size — Letter (8.5" × 11") or A4 (210 × 297mm)
Orientation — Portrait or Landscape
Margins — set top, right, bottom, and left independently in inches or millimeters

The canvas updates as you change values, so you can see the printable area before you start adding content.

Step 3: Add a header and footer

Headers and footers are optional. Click the header or footer on the page to open its settings in the side panel, where you can turn it on or off and edit its content. You can also use Edit header and Edit footer in the document's Header and footer group. Use the back arrow at the top of the side panel to return to the document settings.

Common things to put there:

A logo (upload an image)
A report title
Page numbers ({{page.number}} of {{page.total}})
A date stamp or filter summary

Header and footer content repeats on every page.

Step 4: Add sections

A report is a vertical stack of sections. Add one from any of these places. Each opens the same picker:

Between sections: hover the boundary between two sections on the canvas and click the + that appears.
Outline panel: click Add at the top of the outline to add a section at the end.
Empty page: click Add section on a blank document.

The picker groups sections by what they hold:

Data: Table (paginated rows), Matrix (grouped rows with subtotals, and optional column levels), and KPIs (headline numbers, each with its own dataset and filters).
Content: Text (rich text with variables).
Layout: Spacer (a fixed vertical gap) and Page break (start the next section on a new page).

Copy from this dashboard

The picker also lists the tables, pivot tables, Matrix tables, and KPIs already on your dashboard, including ones in other document sheets. Choose one to add a copy as a new section. The copy brings along any sheet calculated fields it uses, and it's independent of the original: changing one never changes the other.

Arrange sections

Select a section on the canvas to show its toolbar:

Full editor: open the visual editor for a table, Matrix, or KPI section.
Move up and Move down: change its position.
Duplicate: add a copy right after it.
Delete: remove it. The next section is selected so you can keep going.

You can also drag sections in the outline, or on the canvas, to reorder them. The outline shows the page each section starts on, so you can see where content lands as you build.

Sections render in order, top to bottom. Tables, Matrix tables, and pivots paginate automatically when they overflow the page, and a KPI section always stays on one page.

The canvas shows the printed pages

The canvas lays out your report exactly as the PDF prints it: the same page breaks and the same rows on each page. Semaphor measures every row of every table once, at the page's width, so a page on the canvas matches the same page in the PDF, whatever zoom you're working at. When you change the page size, orientation, or a table's style, the pages settle again in a moment.

Use the page switcher at the bottom of the canvas to move between pages. To jump to a page, click the page number, type the page you want, and press Enter.

A long table loads its first rows on the canvas and shows Previewing x of y rows, with Load more to bring in the next rows. The canvas paginates the rows it has loaded, so its pages are the PDF's first pages, row for row. The PDF always includes every row.

Step 5: Configure a table section

When you add a Table section, the visual editor opens full screen. You can also open it later with Full editor on the section's toolbar, or Edit in the side panel.

Choose a dataset, then add fields to the shelves, or switch to SQL editor and write a query. The editor's preview shows the results as you go.
Card filters, formatting, and display options are in the editor's toolbar.
Click Accept to keep your changes, or Close to discard them. Either one takes you back to the page with the section selected.
With the section selected, use the side panel to set column widths, formatting, alignment, and totals.

Nothing reaches the rest of your dashboard until you click Accept, including new calculated fields. If a change can't be kept, the editor stays open and tells you why.

The table paginates across pages as rows overflow. Headers repeat on every page by default.

Step 6: Add document inputs

Reports often need values supplied at export time — a date range, a facility, an account. Open the Document Input Bar at the top of the report and click Filter or Control to add one.

Document inputs are scoped to the report. They power both query filtering and variable substitution in text.

For the full reference on input types, default values, and required inputs, see Inputs and Variables.

Step 7: Use variables in text

Add a Text section and reference any document input with handlebar syntax:

Statement for {{facilityName}}
Period: {{period.range}}

Variables work in text sections, headers, and footers. They resolve at export time using the values supplied for each input.

See Inputs and Variables for the full variable accessor reference.

Step 8: Preview your report

Click Preview in the toolbar to switch the canvas into a chrome-free view. The outline and side panel stay open so you can keep editing. Preview only hides authoring affordances (selection outlines, the section toolbar, insert buttons, placeholder hints) so you can check the visual output.

Toggle Preview off to keep authoring.

Step 9: Export to PDF

Click Export PDF. If the report has required inputs, you'll be prompted to supply values. Semaphor renders the report and downloads the PDF.

For batch exports, scheduled delivery, and download formats, see Exporting Reports.

On this page