Skip to main content

Understanding Report Templates

Report templates let you design printable documents and PDFs from data records in Raytio. This page explains what report templates are, how the template builder works, and the design decisions behind the system.

For the full configuration specification and API reference, see the Report Template Reference.

What report templates do​

Report templates solve a common need: turning structured data (stored as ProfileObjects or database records) into formatted, printable documents. Rather than hard-coding PDF layouts, the system uses a configurable template that maps schema fields onto a page layout.

A report template allows you to:

  • Design custom layouts — arrange fields across header, body, and footer sections
  • Include line items — display child records (e.g. invoice lines) in configurable tables
  • Apply styling — control font size, weight, alignment, and emphasis per field
  • Generate PDFs — download formatted documents for sharing or printing
  • Preview reports — see live previews before printing or downloading

How the template builder works​

The template builder is a drag-and-drop interface with three areas:

┌──────────────────────────────────────────────────────────────┐
│                         Header Bar                            │
│  [Template Name Input]  [Line Items Schema ▼]  [Cancel] [Save]│
├────────────┬─────────────────────────────────┬───────────────┤
│            │                                 │               │
│   Field    │         Canvas                  │    Field      │
│   Palette  │                                 │  Properties   │
│            │  ┌───────────────────────┐      │               │
│            │  │      Header Section    │      │               │
│  Schema    │  └───────────────────────┘      │  Label        │
│  Fields    │  ┌───────────────────────┐      │  Font Size    │
│            │  │       Body Section      │      │  Font Weight  │
│  • Field 1 │  └───────────────────────┘      │  Text Align   │
│  • Field 2 │  ┌───────────────────────┐      │               │
│  • Field 3 │  │      Footer Section     │      │               │
│            │  └───────────────────────┘      │               │
│  Line Items│                                 │               │
│  [Table]   │                                 │               │
└────────────┴─────────────────────────────────┴───────────────┘

Field Palette (left) shows the available fields from the selected schema. You drag fields from here onto the canvas.

Canvas (center) represents the page with three drop zones — header, body, and footer. These sections map directly to the final PDF layout.

Field Properties (right) lets you configure the appearance of the currently selected field — label text, font size, weight, style, and alignment.

The three-section model​

The canvas uses a fixed three-section layout rather than a freeform design surface. This is an intentional constraint:

SectionPurposeTypical content
HeaderTop of each pageLogo, title, date, customer info
BodyMain content areaLine items table, details
FooterBottom of each pageTotals, notes, terms and conditions

This structure mirrors how most business documents are organised (invoices, statements, reports) and simplifies the layout process — you do not need to manually position every element on the page.

Line items and parent-child relationships​

Report templates support a parent-child data model. The primary schema provides the header-level data (e.g. invoice header), while a child schema provides the repeating line items (e.g. invoice lines).

The relationship between parent and child is established through a foreign_key_of field in the child schema. The system automatically detects this relationship and fetches the matching child records when generating the report.

This design mirrors the relational database pattern — a parent record has many child records — and allows a single template to handle variable numbers of line items without any special configuration.

Column aggregations​

Line item tables can include a totals row with aggregated values. Each column can independently specify its aggregation method (Sum, Average, Count, Min, Max, or None). This allows invoices to show subtotals, counts, or averages at the bottom of each column as appropriate.

Template visibility​

Templates have two visibility levels:

VisibilityWho can see it
PERSONALOnly the template creator
ORGANIZATIONAll users in the same organisation

This distinction exists because some templates are personal working documents (a draft layout, a one-off report format) while others are shared standards that the whole organisation should use (the official invoice template, the standard customer statement).

Design decisions​

Why JSON configuration instead of a visual designer only? Templates are stored as JSON configuration objects. While the template builder provides a visual interface, the underlying JSON format means templates can be programmatically created, versioned, and migrated. It also allows templates to be included in onboarding schemas or created via API.

Why not a full page layout editor? The three-section model (header/body/footer) with drag-and-drop field placement is deliberately simpler than a full desktop-publishing layout. This keeps the learning curve low and prevents layout issues in generated PDFs — the system handles pagination, margins, and field spacing automatically.

Why separate schemas for parent and child data? Using the existing schema and foreign key system means report templates do not need their own data model. Any schema with a database.table property can serve as a report data source, and any schema with a foreign_key_of field can provide line items.