Designer guide
Authoring tasks for report authors.
A task guide for report authors using the WPF, WinForms or Blazor designer. All three show the same report and the same commands; the desktop hosts add native dialogs and the web host runs in the browser.
1. Open, save and recover
- Open a
.beeprptfile or a stored report. The same file opens and saves identically in every host; the canonical JSON is in REPORT_DEFINITION_SCHEMA.md. - Save writes the canonical file/store version; a newer stored version refuses the write instead of overwriting it.
- Autosave keeps recoverable work after a crash; the Recovery pane lists autosaves and restores one as a tab.
- Undo/redo is one history for items, bands, styles, totals and text. The Design analyzer lists the undo history and lets you jump back.
2. Bands
- Bands are ordered: top margin, report header, page header, group headers, detail, group footers, report footer, page footer, bottom margin.
- Bands pane properties: height, grow/shrink, keep together, repeat, hidden, print-on, page break, group/data source/relation, filter, sort, multi-column, watermark.
- Sub-bands are conditional variants; the first true condition supplies the content and height, and the band itself is the fallback.
- Cross-band lines/boxes span band instances on a page (for example a group header to its footer).
- Nested detail-report bands are listed in the Bands pane and edited with the same band editor.
3. Items
Insert from the toolbox or the context menu: label, field, rich text, check box, CharacterComb, page info, line, shape, panel, picture, table, cross-tab, chart, KPI, map, barcode, subreport, table of contents. Drag to move, use the grips to resize, and use the Arrange menu or the property grid to align, distribute and set z-order.
4. Text, alignment and format
Every text-bearing value (label, field, cell, chart title, map label, KPI) supports horizontal/vertical alignment, padding, wrapping, font, colour and a .NET/named format string. Alignment is direction-aware for right-to-left reports. See DESIGNER_EXPRESSIONS_AND_TOTALS.md.
5. Expressions, fields and parameters
- Fields are written
[dataSource.Field]; parameters are?Name. - Expressions start with
=; the expression pane offers completion, signatures and sample values. - Functions and syntax are listed in EXPRESSIONS.md.
- Parameters have typed values, defaults, prompts, lookups and dependencies; a missing required value stops the run with a typed diagnostic.
6. Totals and carried balances
The Totals pane writes aggregates into labels/fields or table cells: Sum, Count, averages, min/max, RunningSum,
RunningCount, PageTotal, OpeningBalance (balance b/f), ClosingBalance (balance c/f) and RowNumber. The reset scope is the
current group, a named group or the whole report. Accounting reports use opening + page total + closing on group footers.
7. Actions, bookmarks and the document map
- The Actions pane sets hyperlinks, bookmark jumps, toggle regions, sort actions and drill-through targets.
- The Document map pane sets each item's
bookmarkanddocumentMapLabel; the viewer builds the map from them. - The Design analyzer shows validation findings, smart tags, undo history and style application.
- The Versions pane compares two stored versions side by side with highlighted changes and can restore the older one.
- The Presence pane shows collaborators and soft locks; a locked item shows a red lock badge on the canvas.
8. Page setup
The Page pane sets paper size, orientation, custom size, margins, columns/spacing/direction, background, paper source, duplex, default culture and layout direction. The preview and the canvas use the same geometry.
9. Preview, print and export
Preview runs the report with the current parameters and data. Export uses the registered renderers: PDF, PDF/UA, HTML, XLSX, DOCX, RTF, PNG/JPEG, CSV/JSON/XML/TXT and PPTX where enabled by the host. The format matrix and limits are in OUTPUT_FORMATS.md.
10. Localization
Report texts can come from message catalogues (@str:key); the Localization pane edits keys per culture, shows missing and long
texts, and previews a culture or RTL direction. See LOCALIZATION.md.
11. Keyboard and accessibility
Common shortcuts: undo/redo, copy/cut/paste, delete, arrow-key movement, Shift+arrow resize, Ctrl+click multi-select, zoom in/out/ actual size, preview and save. Every pane exposes accessible names and keyboard focus; canvas items carry alt text. Details and the host matrix are in HOST_PARITY.md.
12. Troubleshooting
- A red error in the Error list points to the band/item; double-click selects it.
- “Item type is not rendered” means the host lacks that item plug-in.
- “Band too tall” means the band exceeds the page; reduce its height or let it grow.
- A refused save means a newer stored version exists; reload or save as a new report.