Report Packs Developer Guide

Report Packs — Developer Guide

Changelog #2085–#2088 · For using it, see Report Packs

Report Packs is a Word-like designer for multi-page reports that export to PDF. This page explains the one idea everything rests on, the files, the design document, how a block gets its data, and the traps that were hit building it.

Requested by Enrique Cabrera, whose own monthly Reporte de disponibilidad de Servicios e Incidencias was the model: a repeating header with logo and dates, a summary, two software charts, per-service uptime with daily bars, and a multi-page incident log.

📚 This page is the overview. The deep dive is a three-part series:

1. The designer - the HTML, CSS and JavaScript: state and undo, why it feels fluid, the SVG-plus-overlay canvas, drag and drop, column-snapped resizing, the ribbon, editing text in place, live toolbox previews
2. The layout engine - measuring with the PDF's own fonts, rich text and line breaking, block measurement, splitters, pagination, the SVG and PDF renderers, charts at two resolutions, the runtime
3. PHP and SQL - the tables, the API, sharing and roles, the design check, optimistic concurrency, the block registry, timezone-correct periods, the data functions, security, adding a block end to end

---

The one idea: a single layout engine

Every report designer has to answer where does this line break, and where does this page end? — and answer it identically on screen and in the PDF. If the browser lays out the screen and a PDF library lays out the file, they disagree: a table that ends on page 2 on screen spills onto page 3 in the PDF.

So there is exactly one place that decides layout: assets/js/report-packs/engine.js. It turns the design (plus each block's data) into pages of primitives — text runs, rectangles, lines, dot leaders, images — each at an exact position in millimetres. Two renderers draw those primitives and decide nothing:

                     design + block data
                             │
                             ▼
                 engine.js  paginate()          ← every line break, every page break
                             │
              pages: [{items: [{draw: [prim…], chart, rich}], headerRich, footerRich, …}]
                 ┌───────────┴────────────┐
                 ▼                        ▼
         render-svg.js              render-pdf.js
       (the designer's pages)       (jsPDF: the file)

Text is measured with the PDF's own font metrics

The engine measures text with jsPDF's metrics for the PDF standard fonts (Helvetica, Times, Courier) — getStringUnitWidth, cached per character — and does its own line breaking. The screen then draws each run at the x the engine chose, with SVG textLength pinning it to the measured width. A browser whose Arial is a hair wider than Helvetica nudges the glyphs; it never wraps differently.

The standard fonts are WinAnsi: English and Western European text, including Spanish accents and ñ. RPEngine.hasUnsupported() detects anything else, the designer warns in its status bar, and render-pdf.js writes ? rather than garbage. Embedding Unicode fonts (Noto) is the way to lift this, at a cost of several hundred KB per face per pack.

Charts: one layout, two resolutions

Chart.js draws each chart on a canvas whose CSS size is fixed in millimetres (PX_PER_MM = 4). Only devicePixelRatio changes — the zoom on screen, 3 (≈300 dpi) for the PDF. Because Chart.js lays out in CSS pixels, the legend and labels land in the same place at every resolution.

---

📁 The files

🗄️ schema · 🔒 access · 🧱 blocks/data · 📐 layout · 🖊️ designer · 🔌 API · 🖥️ pages · 🧪 tests · 📄 docs

🎨	File	What it does
🗄️	includes/db_verify_schema.php, database/freeitsm.sql, api/system/db_verify.php	report_packs (the design as one JSON document) and report_pack_shares; FKs
🔒	includes/report_packs/access.php	Roles (owner / edit / view), share matching, the list query, saving shares
🧱	includes/report_packs/blocks.php	The registry: handlers (module, kind, option schema, data function) and toolbox items
🧱	includes/report_packs/blocks_tickets.php · blocks_status.php · blocks_software.php · blocks_assets.php	The data functions, one file per area
🧱	includes/report_packs/criteria.php	Date presets resolved in the viewer's timezone; the company clause
🧱	includes/services/service_uptime.php	incidentsBetween / summaryBetween / dailyStripBetween — fixed ranges beside the board's own window methods
📐	includes/report_packs/design.php	The design's shape, the starter design, and rpCleanDesign() — the check every save goes through
📐	assets/js/report-packs/engine.js	Measurement, rich-text layout, block layout, splitting, pagination
📐	assets/js/report-packs/charts.js	Chart.js to canvas at a fixed mm size
📐	assets/js/report-packs/render-svg.js · render-pdf.js	The two renderers
📐	assets/js/report-packs/runtime.js	Block data (cached, 4 at a time), header fields, logo, chart images, export
🖊️	assets/js/report-packs/designer.js	Ribbon, toolbox, canvas, drag and drop, handles, properties, undo, save
🖊️	assets/js/report-packs/editor.js	In-place rich text: contentEditable ⇄ the paragraph model
🔌	api/reporting/packs/	list, get, create, save, delete, shares, catalogue, block_data, context
🖥️	reporting/packs/index.php, designer.php, assets/js/report-packs/list.js, assets/css/report-packs*.css	The list and the designer
🧪	tests/report-packs-blocks.php	Every block × every option on real data; module refusal; ranges; the design check
🧪	tests/report-packs-designer-live.html	Drives the real designer in a browser (30 checks)
📄	lang/en/reporting.php (packs.*), reporting/help.php §2, includes/feature_bingo/cards/reporting.php	Strings, in-app help, two Bingo cards

What you do not touch to add a block: the engine, the renderers and the designer. They draw by the data's kind, not by block.

---

The design document

One JSON document per pack, in report_packs.design, read and written whole:

{
  v: 1,
  page:     { size: 'A4', orient: 'portrait', margin: { t: 18, r: 16, b: 18, l: 16 } },   // mm
  theme:    { font: 'helvetica', size: 10, heading: '#1f3864', accent: '#1f3864',
              palette: 'default', th_bg: '#1f3864', th_fg: '#ffffff', stripe: true },
  criteria: { range: { preset: 'last_month' }, tenant: 'active' },   // or {preset:'custom', from, to}; 'all' | id
  header:   { on, rule, first, doc: [...] },
  footer:   { on, rule, doc: [...] },
  cover:    { on, doc: [...] },
  toc:      { on, title },
  blocks: [
    { id, type: 'heading', text, level: 1-3, newPage, toc },
    { id, type: 'text', span: 1-12, doc: [...], box, newRow },
    { id, type: 'data', span, handler: 'tickets.breakdown', opts: {...}, title, showTitle, height, legend, newRow },
    { id, type: 'spacer', span, height } | { id, type: 'divider' } | { id, type: 'pagebreak' },
  ],
}

Rich text is not HTML

Text boxes, the header, footer and cover are paragraphs of runs:

{ t: 'p' | 'h1' | 'h2' | 'h3' | 'li' | 'img', a: 'left' | 'center' | 'right' | 'justify',
  l: 'ul' | 'ol', lv: 0-4,                  // lists
  r: [ { x: 'text' } | { fld: 'page' | 'pages' | 'date_from' | 'date_to' | 'today' | 'title' | 'company' },
       + b, i, u, s, c: '#rrggbb', hl: '#rrggbb', sz: points ] }

Two reasons it is not HTML. The engine needs exactly this to break lines, so HTML would only be parsed into it anyway. And there is nothing to sanitise: rpCleanDesign() checks every field for type and range, the renderers write text with textContent, and there is nowhere to put a script, an event handler or a remote image. The only picture is the install's own logo ({t:'img', src:'logo'}).

editor.js converts both ways — docToHtml() builds the editor's HTML from the model (everything escaped), htmlToDoc() reads it back.

Blocks flow in a 12-column grid

Blocks are a flat list. The engine packs them into rows left to right until 12 columns are used. newRow: true starts a new row even when this one has room — that is how dropped below survives a flow layout.

---

Blocks and their data

The registry

includes/report_packs/blocks.php has two levels:

• Handlers — what a block is: module, kind (chart | kpi | table | uptime), an option schema, and its data function. A pack stores the handler key and options.
• Toolbox items — what the designer offers: a searchable, previewable entry dropping in a handler with options already chosen. Tickets by status and by priority are two items over tickets.breakdown, so one becomes the other by changing Group by.

Adding a block

1. Write the data function in the area's file. It receives ($conn, $analystId, $opts, $range, $tenant) and returns one of the four kinds:

['kind' => 'chart', 'chart' => 'bar', 'labels' => [...], 'series' => [['name' => '…', 'values' => [...]]], 'colours' => null]
['kind' => 'kpi',   'tiles' => [['label' => '…', 'value' => '42', 'hint' => '…']]]
['kind' => 'table', 'columns' => [['key', 'label', 'w', 'align']], 'rows' => [...], 'empty' => '…']
     // a cell may be a string, ['pill' => text, 'colour' => hex] or ['chips' => [['text','colour']…]]
     // a row may carry '_detail' - a full-width line under it (the incident log's comments)
['kind' => 'uptime', 'services' => [...]]

2. Add a handler entry (module, kind, fn, opts) and one or more toolbox entries.
3. Add packs.tool.<key>.title / .desc (and any option labels) to lang/en/reporting.php.
4. Run php tests/report-packs-blocks.php — it runs every option value of every handler and fails on a missing label.

$opts has already been through rpCleanOpts(): a function never sees a value its schema did not declare.

Module access and companies

api/reporting/packs/block_data.php is not tied to a pack. rpBlockData() checks the viewer's access to the handler's module, then the data function scopes to the viewer's companies through rpTenantClause() (active / all / one id the viewer can access — otherwise it refuses). So a pack shared with somebody who lacks Contracts shows them a placeholder; sharing never widens what anyone sees.

Service Status and Intune have no company column — they are the install's — so their blocks ignore the company criterion. Software is scoped through the machine each install is on (software_inventory_detail.host_id = assets.id); note the Software dashboard itself is not company-scoped, so the two can differ on a multi-company install.

Dates

rpResolveRange() resolves a preset in the viewer's timezone and converts the bounds to UTC: last month for Santo Domingo starts at 04:00:00 UTC. The end is exclusive; a custom range includes both days the reader picked. Time series bucket UTC timestamps into local days in PHP rather than GROUP BY DATE(), which would bucket in UTC.

Uptime matches the status board

service_uptime.php gained *Between methods for fixed ranges, beside the board's *For window methods, which were left untouched — so a pack can never disagree with the board about how uptime is worked out, only about the period.

---

Layout and pagination

paginate(design, dataMap, ctx):

1. Measures the header and footer with wide page numbers (888 of 888), so they never grow later.
2. Measures every block at its width. Tables, uptime lists and long text return a splitter: start() and take(state, room).
3. Flows blocks into rows; places rows. A row that does not fit goes to the next page; a lone splittable block puts what fits here and the rest overleaf, repeating table headers. A heading is kept with the next row.
4. Adds the cover and contents pages in front, then lays out every page's header and footer with the real page numbers.

Page numbers count every physical page; the contents' numbers are the physical page each heading starts on.

---

The designer

Every change goes through commit(fn, opts): snapshot for undo, mark unsaved, re-render. Rendering asks the engine for pages, draws them as SVG, and lays an HTML overlay on top for frames, handles, drop guides and header/footer hit areas.

• Drag and drop is pointer events, not HTML5 DnD. dropTarget() maps the pointer to before/after a row (horizontal guide) or beside a block (vertical guide, when within its outer 28%). A side drop that overflows the row shrinks the new block, or halves the target.
• Save sends the stamp it loaded; the server refuses a stale save with conflict and the editor's name, and the designer offers Reload or Save mine. After a save the designer adopts the server's cleaned design, so the screen and the stored pack cannot drift.
• View-only gets the Data tab and Export; criteria changes are local ({viewer: true}) and never mark the pack unsaved. The server refuses the save regardless.

---

How it was tested

• php tests/report-packs-blocks.php — 32 checks on real data: every block and option value, labels, per-block module refusal (as a restricted analyst), timezone ranges, the design check.
• The packs API driven over HTTP as four real analysts — 35 checks: private until shared, each share type (department matching case- and space-insensitive), View cannot save/share/delete, Edit cannot share/delete, the stale-save conflict, copying.
• tests/report-packs-designer-live.html — 30 checks in a real browser: toolbox search, insert, a real pointer drag onto a chart's edge, resize, move, delete, undo/redo, keyboard copy/paste, typing and bold in place, header fields, period change, save and read back, PDF page count, and no null on any tab or pane. tests/ is closed to HTTP, so copy it to the web root to run it (instructions in the file).
• The actual PDF was looked at, not just its page count: Enrique's report rebuilt on real data, exported, and rasterised with pdf.js in headless Chrome. (pdf.js's worker does not run under headless virtual time — load pdf.worker.min.js into the page itself.)

---

Traps for the next person

• Chart.js with responsive: false reads canvas.width as its CSS size. Hand it the backing size and every chart lays out scale times bigger with the same fonts — legible on screen, a third the size in the 3× PDF. Give it the layout size and let devicePixelRatio scale.
• replaceChildren() and append() write a missing element as the text "null". It appeared under the ribbon, in the status bar, and beside every colour picker. Filter before appending.
• An editor's zero-width space is a real character. The one editor.js puts after a field (so the caret has somewhere to sit) is not in the PDF fonts and printed as ?. Both sides strip it now.
• Size an overlay from what is drawn, not from the zoom setting. The text editor took the requested zoom while the page on screen was still the previous one, and sat a line below the text. It now measures the page element.
• selectionchange is asynchronous. A ribbon command that restored the saved selection applied bold to the caret instead of the words just selected. Restore only when focus has really taken the selection out of the editor.
• Keep the board's figures out of reach. New needs got new methods (*Between) rather than new parameters on methods the status board uses.

Related

• Report Packs — for users
• Reporting
• Groups of People — Developer Guide — why "department" here means analysts.department