Using the designer

This page is about the authoring surface itself — what the people using your application will do with it. It is worth reading once even if you are only embedding it, because several behaviours are deliberate choices rather than accidents, and knowing them makes the difference between the designer feeling precise and feeling arbitrary.

The five parts of the designer, and what each one is for.

Design and Preview

Design shows structure: data bindings appear as labelled chips rather than values, empty blocks show placeholders, and containers, repeaters, conditionals and page breaks are outlined and named. Preview substitutes the sample data and hides every affordance, so what you see is what the PDF will contain.

Tables show only the first few rows in Design (designRows, three by default) so a hundred-row table does not bury the rest of the layout while you are working on it. Preview shows every row.

Charts become interactive in Preview: point at a bar, slice or line marker and the rest dim while a tooltip names the category, the series and the value. Nothing is redrawn to do it — the shape being pointed at is the one the PDF will contain — and it is off in Design, where a hover belongs to selecting and dragging. interactiveCharts moves or removes it; see Charts.

Placing blocks

There are three ways to add a block, and they all end up in the same place.

Click, then click. A click anywhere on the page puts an insertion caret there — a thin blue line showing exactly where the next block will go. Click a block in the palette and it lands at the caret. This is the fastest route when you know where you want something.

Drag. Drag from the palette onto the page. A drop line shows the target as you move; an outlined box means you are over an empty container. Dropping beside a section rather than inside one puts the block in the section nearest the pointer.

Select, then insert. With nothing clicked on the page, a palette click appends after the current selection, or inside it if the selection is a container.

Whichever route you take, the canvas scrolls to where the block landed and flashes it briefly — which matters most when it landed on a page you were not looking at.

The caret and the drop line ask the same code the same question, so click-to-place and drag-to-place can never disagree about what a position means.

Finding a field

The Data panel is your schemas, as a tree. Searching matches on the whole path, so looking for value finds the one inside Holdings and shows you which parent it belongs to; sources with nothing matching disappear rather than sitting there as empty folders.

Fields inside a list are shown under it but greyed: they are addressed through a table's or repeater's row alias, so there is nothing to insert on its own. Drag the list onto the page instead and you get a table over it.

Searching for “value”. The nested matches keep the path that says where they live.

Typing data into text

Double-click any text or heading block to edit it in place. Inside, typing {{ opens a list of every field in your data sources, ranked so that what you would naturally type comes first — val puts portfolio.value above portfolio.holdings.value. Arrow keys choose, Enter or Tab inserts, Escape dismisses and leaves your text alone.

The result is a token: a single object that carries the expression, not a fragile piece of text someone can half-delete. The Field button in the formatting bar inserts exactly the same thing, for people who would rather browse than type.

To format a value — a currency, a date, a percentage — insert the field first, then use the inspector's format options, or write the pipe by hand: {{ portfolio.value | currency }}. See Dynamic bindings for the full expression language.

Text styles are offered by name — “Heading 1”, “Body text”, “Small print” — rather than by the id the template stores (h1, body, small). The ids are the contract and are visible in the document panel beside each style; the names are what the person choosing one reads.

Finding your way around

The Layers panel is the document as a tree. Clicking a row selects that block and scrolls the canvas to it, including onto pages that were not rendered yet. Each row can be dragged onto the canvas to move the block, and carries move-up, move-down and delete buttons on hover.

The breadcrumb along the bottom of the canvas shows the path to the selection, and each step in it is clickable — the quickest way out of a block nested several containers deep.

Controlling page breaks

Pagination is decided by BroadPaper, not by the browser and not by the PDF engine, and you control it from the Page flow section of the inspector:

• Keep together — never split this block across pages.
• Keep with next — do not leave this block stranded at the foot of a page. Headings do this by default, and a block that draws nothing does not satisfy it, so a heading followed by a conditional that is currently false still travels with its real content.
• Break before / after — force a new page at this block.
• Orphans and widows — the minimum number of lines to leave behind or carry over when a paragraph splits.

The Page break block is the direct route: drop it anywhere and everything after it starts a new page. Unlike keep-together, an explicit break is never traded away to make content fit, and it works at a section boundary as well as in the middle of one.

The one place it does nothing is after the last content in the document, where there is nothing left to move and a report ending on a blank page would look broken. That case is reported in the canvas warnings rather than passed over in silence.

Tables repeat their header row on every page they continue onto, and never leave a single orphaned row behind.

What the canvas is actually showing

By default the canvas measures with the browser, which is instant. If you supply createMeasurer, Preview measures with the same engine that renders the PDF, and then a page break you see there is a page break you get in the file.

Design mode always measures with the browser, because it draws things the PDF never contains — badges, outlines, drop targets, truncated tables. Its page breaks are therefore indicative; Preview is the one to trust. See Browserless PDF.

Keyboard

Key	Action
Enter	Edit the selected block's text
Escape	Stop editing, or clear the selection
↑ ↓	Select the previous or next sibling
Alt ↑ ↓	Move the selected block up or down
← →	Select the parent, or the first child
⌘/Ctrl C X V	Copy, cut, paste
⌘/Ctrl D	Duplicate
⌫	Delete
⌘/Ctrl Z / ⇧Z	Undo, redo
⌘/Ctrl S	Save
⌘/Ctrl + - 0	Zoom in, out, reset

Undo groups a typing burst into one step rather than one step per character, so undo goes back to something a person recognises.