Arranging boxes, rulers, guides, the page overlay and page stamps
Most of a Frontforge Report Server template flows: boxes follow one another down the page, and you move them by reordering. Some content is positioned instead. You place it at a set distance from an edge:
- the children of a frame, for slips, labels and forms;
- a page template's background, drawn behind everything (a letterhead);
- a page template's overlay, drawn above everything (a "Draft" or "Copy" stamp);
- the children of a page stamp, drawn on the page where a row or item lands (a "Paid" stamp on the page of a paid invoice).
These boxes have move and resize handles on the canvas. They snap to the margins, their frame, other boxes, a grid and your guides. Hold Alt (Option on a Mac) while you drag to place a box freely, without snapping. The arrow keys nudge them, by one step of the document's unit (a millimetre or a point), or by ten with Shift. The tools on this page work on them.
An image keeps its proportions as you resize it: drag a corner or an edge, and its other side follows. Hold Alt (Option on a Mac) to change its width and height separately. You can press or let go of Alt during the drag.
Align, distribute and match size
Select the boxes in the outline or on the canvas (Shift adds to the selection). Then use the arrange buttons in the toolbar over the selection, or the Arrange submenu of the canvas's or outline's menu. A tool that doesn't apply to the selection says why in its tooltip and in the menu.
| Tool | Does |
|---|---|
| Align left edges, centres, right edges | Lines the boxes up horizontally on the selection's bounds. With one box selected, it aligns to its frame (or to the page, in a background, overlay or page stamp). |
| Align top edges, middles, bottom edges | The same, vertically. |
| Distribute horizontally, vertically | Three or more boxes: the first and the last stay, and the others move so the gaps between them are equal. |
| Match width, height | Two or more boxes take the size of the box you picked last. |
Each tool is one undo step, however many boxes it moves. It writes what a drag would: a box placed from the right keeps right, and lengths keep their unit, so 12mm stays in millimetres. The boxes have to be on the same page.
Rulers
Press Ctrl+R (⌘R on macOS), or Rulers in the View group of the top strip's More menu, to show rulers along every page. They count from the page's top-left corner in the document's unit. While you move or resize a box, they count from its frame instead, and show where the box is. The browser remembers whether the rulers are on.
Guides
Guides are lines you place to line things up with.
- Add one: drag out of the top ruler for a horizontal guide, or out of the left ruler for a vertical one, and let go on the page. While you drag, it shows where it is (
45mm), rounded to the unit's step. - Move one: drag it.
- Remove one: drag it off the page, or right-click it and choose Delete the guide. Delete every guide of the page template, in a guide's menu or a page's menu, removes all of a template's guides.
Positioned boxes snap to guides as you drag them.
Guides belong to a page template, so every page that uses the template shows them. They are saved with the draft, versioned with it, and everyone who edits the template sees the same guides. Each guide change is one undo step. In the document, they are kept in meta.designer.guides, which engines ignore (RFML §19.1):
"meta": { "title": "Invoice", "designer": { "guides": { "a4": [{ "x": "20mm" }, { "y": "45mm" }] } } }The page overlay
A page template's overlay is drawn on every page, above the content, the header and the footer (RFML §9.1). Use it for stamps such as "Draft", "Copy" or "Void", or for a page number that sits over the content.
- Click a page in its margin to select it (pages.md). In the Inspector, the Overlay section works like the Background section: + Text adds a text at the corner of the margins, in the overlay's own scope, and you type its text there. A page's menu has Edit the overlay too.
- Select the text and move it on the canvas, or set its position and style in the inspector.
- To show a stamp only sometimes, give it a Show if condition in the inspector. A stamp that shows outside production could depend on a parameter:
params.environment != 'prod'. Page values such aspage.numberwork in its text, but not in its condition.
A variant (first, left, right, last or blank pages) can have an overlay of its own instead of the template's, or none: Own copy gives the variant a copy to change.
How each output draws it:
| Output | The overlay |
|---|---|
| Drawn last and tagged as an artifact (Pagination, Watermark), so screen readers skip it. PDF/A and PDF/UA documents stay valid. | |
| HTML (paged), the viewer, the canvas | A layer above the page. |
| Word | A drawing in front of the text, anchored in the page's header, as Word does watermarks. Word repeats a header unchanged, so the overlay is the same on every page the header serves (page fields still count). |
| Excel, HTML (flow) | Left out, since they have no pages. A warning says so when the overlay has something to show. |
Locking the background or overlay
A big stamp in the overlay, or a full-page letterhead in the background, covers what you want to click. Lock the layer and clicks go through it to what is under it. Locking changes nothing the report prints: it only changes what the designer selects.
- To lock it: select a page, and in the Inspector press the lock button in the Background or Overlay section, beside Edit. The section then shows Locked. The button shows when the layer holds something. The page's menu (right-click a page in its margin) and the command palette have Lock the overlay, Unlock the overlay, Lock the background and Unlock the background too. They act on the selected page, the page of the selected header, footer, background or overlay node, or a document's only page template.
- One lock per layer and template: it covers the template's own overlay and every variant's (first, left, right, last and blank pages).
- What a locked layer does:
- A click, a double-click, a drag and the hover outline go to what is under it, as if it weren't there.
- Alt+click, the Select submenu and the canvas's arrow keys leave it out.
- It is drawn as it prints. With the pointer over one of its boxes, a dashed outline and an "Overlay · locked" tag show on that box, so you can see why the click went past it.
- In the outline, its nodes are still listed, shown muted. A click on one doesn't select it, and a line under the outline says why. The slot tag of each top-level node (
overlaywith a lock) unlocks the layer. - In its own scope, it is what you are editing: Edit in the Inspector opens it, and its boxes can be selected there. In the background's scope a locked overlay stays locked, so you can work on a letterhead under a "Draft" stamp.
- When a layer is locked while one of its nodes is selected, the page is selected instead.
Anyone who may edit the template may lock and unlock it. It isn't a developer's lock on content (locks): a locked layer can still be changed in its scope, and a developer's lock still applies inside an unlocked one. Locking is one undo step, and it is saved with the template, in its meta.designer.lockedLayers (RFML §19.2, designer state that engines ignore). So everyone who edits the template sees it locked, and it stays when the template is renamed or duplicated.
The same works in a library's page template. A report that copies the template from the library keeps its lock, and you can unlock it in the report. When a linked template takes the library's next release, the lock is merged like any other setting: the report keeps its own choice if it changed the lock.
RFML 0.2
Overlays, guides and a page template's meta (where a layer's lock is kept) are new in RFML 0.2. A template that uses none of them stays "rfml": "0.1". The edit that adds the first overlay text, the first guide or the first lock sets "rfml": "0.2" in the same undo step, and undoing it takes the version back. The same goes for anything else a later RFML version added (RFML §24.1), however the edit is made: text-fit or a logical side written in the code view, a style property set in the Style panel, a pasted node with orphans. The edit declares the lowest version that has everything it uses, so default formats (RFML 0.3) in a 0.1 report set "rfml": "0.3". The engine's own checks decide which version an edit needs, so the studio keeps no list of its own. An edit that sets rfml itself keeps the version it sets. An engine that reads only RFML 0.1 refuses a template that uses them. A library's page template has no version of its own: it is checked at the engine's version (libraries.md).
Page stamps
The overlay is the same on every page: its Show if can read parameters and the data, but not the row a page holds. A page stamp can. It sits in the flow, in a table's cell or a region's item, and draws its children at a fixed place on the page where that row or item lands (RFML §6.13). Use it for a "Paid" stamp on the page of a paid invoice, or a "Fragile" mark on a parcel's label.
- Insert a Page stamp where the row is: in a column's cell, a region's item, a group's header, or a component. It holds positioned children, as a frame does.
- Give the stamp a Show if that reads the row, such as
row.status == 'paid'. - Select its text on the canvas and move it, or set its position in the inspector. Positions count from the page's corner. Moving one instance moves them all, since they are one node.
How it behaves:
- It takes no space and never moves anything in the flow. A stamp at the top of a row goes with the row, so it lands on the page where the row starts.
- On each page only the first instance of a stamp draws, so ten paid invoices on a page give one "Paid" stamp. Two different stamps both draw, ordered by their
z-index. - It is drawn above the content and the footer, and below the overlay.
- In a repeated table header, it draws again on every page the header repeats on.
- Screen readers read it with the row it belongs to. Tick Decorative for a stamp that only decorates: it is then left out of the structure of a tagged PDF, and hidden in HTML.
- A click on a stamp's text selects it, even over content. Alt+click or the canvas menu's Select submenu reaches what is underneath. In the outline, the stamp sits under the cell or item that holds it.
- When the sample data never shows the stamp, the inspector says so. You can still type its position, and when another page shows it, the inspector takes you there.
A page stamp can't be in a page template's header, footer, background or overlay, in a frame, or in another stamp, and it can't hold footnotes. The checker says so.
How each output draws it:
| Output | A page stamp |
|---|---|
| PDF, PNG, HTML (paged), the viewer, the canvas | On the page where it lands, as content, or as an artifact when decorative. |
| Word | A drawing in front of the text, in a paragraph of its own where the stamp sits, so Word draws it on the page where it puts the row. Word breaks pages its own way, and draws every instance it finds, so only the instances the PDF draws are written. In a table cell, Word places the drawing from the cell's corner, so there it is placed from the cell (an info diagnostic says so). |
| HTML (flow) | Shown where it sits, without its position, with an info diagnostic. |
| Excel | Left out, with an info diagnostic. |
Page stamps are new in RFML 0.2, so a template that uses one declares "rfml": "0.2".
Selecting a box behind another
A click on the canvas selects the topmost box under the pointer. Sometimes that box covers the one you want: an overlay's stamp over the logo, a page stamp over a table, a frame child over a text, or a large image. Two ways get past it:
- Alt+click (⌥-click on macOS) selects the box under the selected one, where you click. Click again with Alt to go further down. After the bottom box, it wraps round to the top. When none of the boxes there is selected, Alt+click selects the one under the top box, since a plain click gives you the top one. On a table, Alt+click steps past the cells like any box, rather than picking a cell.
- The Select submenu of the canvas's menu lists every box under the pointer, top first, and checks the selected one. Pick one to select it. Right-click to open it. From the keyboard, Shift+F10 or the Menu key lists the boxes under the middle of the box with the keyboard. It shows only when more than one box is there.
Select the box behind in the command palette does what Alt+click does, where you last clicked on the canvas, or else in the middle of the selection. The outline, and the canvas's arrow keys, reach every box too, covered or not.
A locked background or overlay is left out of all of these, and of a plain click (Locking the background or overlay).
A page's header, footer, background and overlay are not boxes to select themselves, only what they hold. A click where they hold nothing, such as the margin beside the footer, selects the page, and the Inspector shows its template (pages.md). Neither Alt+click nor the arrow keys stop on them.
Empty elements show their id
An element with nothing to show takes no space in a report: not in the PDF, the exports or the viewer (RFML §16.1). Its margins, padding, border and list marker go with it. Leaving it out of the layout on the canvas as well would make it impossible to see or click, so there the designer shows the element's id in its place, in grey italic, in its own font and size:
- A new text or heading starts empty and shows its id until you type. So does one whose content you delete, or one whose field is empty in the sample data.
- A new box, list or item shows its id until it has a child. An item keeps its bullet.
- A new table shows its id until it has a row. A row whose cells are all empty shows its own id in its first cell.
- A repeat shows its id while it draws nothing: it has no child yet, or its data has no items and it has no Empty content.
Click the id to select the element, as you would click its content, or drag something onto it. Double-click a text's id to type into it: the editor starts empty, because the id isn't part of the text. The id goes as soon as the element has something to show.
Some empty elements keep their place in a report, so they keep it on the canvas too:
- one with a set height, width, minimum height or minimum width, such as a spacer;
- a positioned one, such as a border drawn round a page in its background;
- a flex or grid item;
- one that sets a running value.
A positioned element that has a size of its own (a border round the page, say) draws as it is, with no id over it.