DesignerController

Framework-neutral designer logic: the template being edited, selection, move/resize/snap, band and data management, clipboard and undo/redo. Every change produces a new template object, so views can compare by reference.

Constructors

Constructor

new DesignerController(options?): DesignerController;

Parameters

Parameter	Type
options	DesignerControllerOptions

Returns

DesignerController

Accessors

redoLabel

Get Signature

get redoLabel(): string | null;

Returns

string | null

---

template

Get Signature

get template(): ReportTemplate;

Returns

ReportTemplate

---

undoLabel

Get Signature

get undoLabel(): string | null;

Label of the change that undo would revert.

Returns

string | null

Methods

addChildRegion()

addChildRegion(parentRegionId, source): string;

Adds a nested (master-detail) region. Pass { relation: 'items' } or { dataSource: 'notes' }.

Parameters

Parameter	Type
parentRegionId	string
source	| { relation: string; } | { dataSource: string; }

Returns

string

---

addComponent()

addComponent<T>(
   bandId,
   type,
   overrides?
): string;

Adds a component to a band and selects it. Returns its id.

Type Parameters

Type Parameter
T extends "text" | "image" | "line" | "rectangle"

Parameters

Parameter	Type
bandId	string
type	T
overrides	Partial< | Extract<TextComponent, { type: T; }> | Extract<ImageComponent, { type: T; }> | Extract<LineComponent, { type: T; }> | Extract<RectangleComponent, { type: T; }>>

Returns

string

---

addDataRegion()

addDataRegion(dataSource, index?): string;

Inserts a data region bound to a data source. Returns the region id.

Parameters

Parameter	Type
dataSource	string
index?	number

Returns

string

---

addDataSource()

addDataSource(def): void;

Parameters

Parameter	Type
def	DataSourceDefinition

Returns

void

---

addGroup()

addGroup(regionId, expression): string;

Adds a group to a region (as the innermost group). Returns the group id.

Parameters

Parameter	Type
regionId	string
expression	string

Returns

string

---

addParameter()

addParameter(def): void;

Parameters

Parameter	Type
def	ParameterDefinition

Returns

void

---

addStaticBand()

addStaticBand(index?): string;

Inserts a static band into the body at index (end by default). Returns its id.

Parameters

Parameter	Type
index?	number

Returns

string

---

align()

align(alignment): void;

Parameters

Parameter	Type
alignment	Alignment

Returns

void

---

beginInteraction()

beginInteraction(label): void;

Starts a drag or resize. Changes until endInteraction() become one undo step.

Parameters

Parameter	Type
label	string

Returns

void

---

bodyWidth()

bodyWidth(): number;

Width of the printable body in template units: components should stay within it.

Returns

number

---

cancelInteraction()

cancelInteraction(): void;

Returns

void

---

checkExpression()

checkExpression(source): string | null;

Checks expression syntax; null when valid.

Parameters

Parameter	Type
source	string

Returns

string | null

---

clearSelection()

clearSelection(): void;

Returns

void

---

completions()

completions(bandId?): string[];

Names available in expressions inside a band, for autocompletion: scope variables, data sources, parameters and row fields.

Parameters

Parameter	Type
bandId?	string

Returns

string[]

---

copy()

copy(): number;

Returns

number

---

cut()

cut(): number;

Returns

number

---

distribute()

distribute(axis): void;

Parameters

Parameter	Type
axis	"horizontal" | "vertical"

Returns

void

---

duplicate()

duplicate(): string[];

Returns

string[]

---

endInteraction()

endInteraction(): void;

Returns

void

---

getSampleData()

getSampleData(): unknown;

Returns

unknown

---

getState()

getState(): DesignerState;

Returns

DesignerState

---

handleKey()

handleKey(e): boolean;

Handles designer shortcuts. Returns true when the key was handled, so the view can call preventDefault(). Views should not forward keys typed into inputs.

Parameters

Parameter	Type
e	KeyInput

Returns

boolean

---

inferDataSourceFields()

inferDataSourceFields(name): number;

Infers a data source’s fields from the sample data. Returns the field count.

Parameters

Parameter	Type
name	string

Returns

number

---

insertField()

insertField(
   bandId,
   path,
   at?,
   root?
): string;

Inserts a text bound to a data field, e.g. path [“customer”, “name”] becomes {{ row.customer.name }}. root defaults to “row”.

Parameters

Parameter	Type	Default value
bandId	string	undefined
path	string[]	undefined
at	{ x: number; y: number; }	...
at.x	number	undefined
at.y	number	undefined
root	string	'row'

Returns

string

---

load()

load(template): void;

Replaces the template (e.g. after opening a file). Clears history. Throws for invalid templates.

Parameters

Parameter	Type
template	string | ReportTemplate

Returns

void

---

markSaved()

markSaved(): void;

Marks the current template as saved (clears dirty).

Returns

void

---

matchSize()

matchSize(dimension): void;

Gives the selected components the same width and/or height as the first one.

Parameters

Parameter	Type
dimension	"height" | "width" | "both"

Returns

void

---

moveBodyItem()

moveBodyItem(fromIndex, toIndex): void;

Moves a top-level body item (static band or region) to another position.

Parameters

Parameter	Type
fromIndex	number
toIndex	number

Returns

void

---

moveComponents()

moveComponents(
   ids,
   dx,
   dy,
   snap?
): void;

Moves components by a delta. Inside an interaction the delta is measured from the drag start. Snaps the primary (first) component and moves the others by the same amount. Positions stay non-negative.

Parameters

Parameter	Type	Default value
ids	string[]	undefined
dx	number	undefined
dy	number	undefined
snap	boolean	true

Returns

void

---

moveComponentsToBand()

moveComponentsToBand(
   ids,
   bandId,
   dx,
   dy,
   snap?
): void;

Moves components (all from one band) into another band while dragging. dx/dy are measured from the components’ original positions, in the target band’s coordinates: when the target band starts 30 units below the source band, a pointer movement of 35 units down is dy = 5. Inside an interaction the change is applied to the drag start state, so the drag can move back and forth between bands. Moving to the components’ own band is the same as moveComponents.

Parameters

Parameter	Type	Default value
ids	string[]	undefined
bandId	string	undefined
dx	number	undefined
dy	number	undefined
snap	boolean	true

Returns

void

---

moveComponentToBand()

moveComponentToBand(
   id,
   bandId,
   x,
   y
): void;

Moves a component to another band at the given position (band coordinates).

Parameters

Parameter	Type
id	string
bandId	string
x	number
y	number

Returns

void

---

moveGroup()

moveGroup(groupId, direction): void;

Moves a group one level out (-1) or in (+1).

Parameters

Parameter	Type
groupId	string
direction	-1 | 1

Returns

void

---

nudge()

nudge(
   dxSteps,
   dySteps,
   fine?
): void;

Moves the selection by a small step (arrow keys). Uses the grid unless fine is true.

Parameters

Parameter	Type	Default value
dxSteps	number	undefined
dySteps	number	undefined
fine	boolean	false

Returns

void

---

pageSize()

pageSize(): object;

Page size in template units, with the orientation applied.

Returns

object

Name	Type
height	number
width	number

---

paste()

paste(bandId?): string[];

Pastes into the selected band (or bandId), offset when pasting into the same place. Returns new ids.

Parameters

Parameter	Type
bandId	string | null

Returns

string[]

---

preview()

preview(options?): object;

Generates the report with the sample data. Errors are returned, not thrown.

Parameters

Parameter	Type
options	GenerateOptions

Returns

object

Name	Type
document	LayoutDocument | null
error	Error | null

---

redo()

redo(): void;

Returns

void

---

regionFields()

regionFields(region): FieldDefinition[] | undefined;

Field schema of the rows a region iterates (from the data source or the parent’s relation).

Parameters

Parameter	Type
region	DataRegion

Returns

FieldDefinition[] | undefined

---

removeBand()

removeBand(bandId): boolean;

Removes a band. Detail bands cannot be removed on their own: remove the region instead. Returns false when nothing was removed.

Parameters

Parameter	Type
bandId	string

Returns

boolean

---

removeComponents()

removeComponents(ids?): void;

Removes the selected (or given) components.

Parameters

Parameter	Type
ids	string[]

Returns

void

---

removeDataSource()

removeDataSource(name): void;

Parameters

Parameter	Type
name	string

Returns

void

---

removeGroup()

removeGroup(groupId): void;

Parameters

Parameter	Type
groupId	string

Returns

void

---

removeParameter()

removeParameter(name): void;

Parameters

Parameter	Type
name	string

Returns

void

---

removeRegion()

removeRegion(regionId): void;

Removes a data region with all its bands and children.

Parameters

Parameter	Type
regionId	string

Returns

void

---

removeStyle()

removeStyle(name): void;

Removes a named style and detaches components that used it.

Parameters

Parameter	Type
name	string

Returns

void

---

renameStyle()

renameStyle(from, to): void;

Renames a named style and updates components that use it.

Parameters

Parameter	Type
from	string
to	string

Returns

void

---

reorder()

reorder(where): void;

Changes paint order: components later in the band list are drawn on top.

Parameters

Parameter	Type
where	"front" | "back" | "forward" | "backward"

Returns

void

---

resizeBand()

resizeBand(bandId, height): void;

Resizes a band by dragging its bottom edge; height is in template units.

Parameters

Parameter	Type
bandId	string
height	number

Returns

void

---

resizeComponent()

resizeComponent(
   id,
   handle,
   dx,
   dy
): void;

Resizes a component with a handle; inside an interaction the delta is measured from the drag start.

Parameters

Parameter	Type
id	string
handle	ResizeHandle
dx	number
dy	number

Returns

void

---

resizeComponents()

resizeComponents(
   ids,
   handle,
   dx,
   dy
): void;

Resizes several components with the same handle and delta, e.g. to make every cell of a table row taller at once. Each component keeps its own opposite edge fixed.

Parameters

Parameter	Type
ids	string[]
handle	ResizeHandle
dx	number
dy	number

Returns

void

---

sections()

sections(labels?): DesignSection[];

Bands in design order. Pass translated labels for localized captions.

Parameters

Parameter	Type
labels?	SectionLabels

Returns

DesignSection[]

---

select()

select(ids, mode?): void;

Selects components. Components must share a band; selecting a component from another band replaces the selection.

Parameters

Parameter	Type	Default value
ids	string[]	undefined
mode	"replace" | "add" | "toggle"	'replace'

Returns

void

---

selectAll()

selectAll(bandId?): void;

Selects every component in a band (the selected band by default).

Parameters

Parameter	Type
bandId	string | null

Returns

void

---

selectBand()

selectBand(bandId): void;

Parameters

Parameter	Type
bandId	string | null

Returns

void

---

selectedComponents()

selectedComponents(): ReportComponent[];

Selected components, in selection order.

Returns

ReportComponent[]

---

selectInBands()

selectInBands(rects, additive?): void;

Rubber-band selection that may cover several bands, e.g. started in the page margin. Selections are limited to one band, so the band with the most hits wins (the first one on a tie). rects are in each band’s coordinates. With no hits the selection is cleared (unless additive).

Parameters

Parameter	Type	Default value
rects	object[]	undefined
additive	boolean	false

Returns

void

---

selectInRect()

selectInRect(
   bandId,
   rect,
   additive?
): void;

Rubber-band selection inside one band; rect is in band coordinates.

Parameters

Parameter	Type	Default value
bandId	string	undefined
rect	Rect	undefined
additive	boolean	false

Returns

void

---

setGroupBand()

setGroupBand(
   groupId,
   which,
   enabled
): void;

Parameters

Parameter	Type
groupId	string
which	"header" | "footer"
enabled	boolean

Returns

void

---

setPageBand()

setPageBand(slot, enabled): string | null;

Adds or removes a report/page header or footer.

Parameters

Parameter	Type
slot	PageBandSlot
enabled	boolean

Returns

string | null

---

setRegionBand()

setRegionBand(
   regionId,
   which,
   enabled
): void;

Adds or removes a region’s header or footer band.

Parameters

Parameter	Type
regionId	string
which	"header" | "footer"
enabled	boolean

Returns

void

---

setSampleData()

setSampleData(data): void;

Parameters

Parameter	Type
data	unknown

Returns

void

---

setStyle()

setStyle(name, style): void;

Creates or replaces a named style.

Parameters

Parameter	Type
name	string
style	StyleProps

Returns

void

---

setTextAlign()

setTextAlign(textAlign, ids?): void;

Sets the horizontal text alignment of the selected text components.

Parameters

Parameter	Type
textAlign	"left" | "center" | "right" | "justify"
ids	string[]

Returns

void

---

setVerticalAlign()

setVerticalAlign(verticalAlign, ids?): void;

Sets the vertical text alignment of the selected text components.

Parameters

Parameter	Type
verticalAlign	"top" | "middle" | "bottom"
ids	string[]

Returns

void

---

subscribe()

subscribe(listener): () => void;

Parameters

Parameter	Type
listener	Listener

Returns

() => void

---

textAlignment()

textAlignment(ids?): object;

Effective content alignment of the selected text components (named style and inline style applied). A value is null when the components differ or no text component is selected.

Parameters

Parameter	Type
ids	string[]

Returns

object

Name	Type
textAlign	"left" | "center" | "right" | "justify" | null
verticalAlign	"top" | "middle" | "bottom" | null

---

toJSON()

toJSON(pretty?): string;

Template as JSON text.

Parameters

Parameter	Type	Default value
pretty	boolean	true

Returns

string

---

undo()

undo(): void;

Returns

void

---

updateBand()

updateBand(bandId, patch): void;

Parameters

Parameter	Type
bandId	string
patch	Partial<Omit<Band, "id" | "components">>

Returns

void

---

updateComponent()

updateComponent(id, patch): void;

Replaces properties of a component. Use updateComponentStyle for style changes.

Parameters

Parameter	Type
id	string
patch	Partial<ReportComponent>

Returns

void

---

updateComponentStyle()

updateComponentStyle(patch, ids?): void;

Merges style properties into the selected (or given) components. undefined removes a property.

Parameters

Parameter	Type
patch	Partial<Record<keyof StyleProps, unknown>>
ids	string[]

Returns

void

---

updateDataSource()

updateDataSource(name, patch): void;

Updates a data source. Renaming also updates regions that use it.

Parameters

Parameter	Type
name	string
patch	Partial<DataSourceDefinition>

Returns

void

---

updateGroup()

updateGroup(groupId, patch): void;

Parameters

Parameter	Type
groupId	string
patch	Partial<Pick<Group, "expression" | "sortDirection" | "pageBreakBefore">>

Returns

void

---

updateParameter()

updateParameter(name, patch): void;

Parameters

Parameter	Type
name	string
patch	Partial<ParameterDefinition>

Returns

void

---

updateRegion()

updateRegion(regionId, patch): void;

Parameters

Parameter	Type
regionId	string
patch	Partial<Omit<DataRegion, "kind" | "id" | "detail" | "header" | "footer" | "groups" | "children">>

Returns

void

---

updateSettings()

updateSettings(patch): void;

Parameters

Parameter	Type
patch	Partial<DesignerSettings>

Returns

void

---

updateTemplate()

updateTemplate(patch): void;

Updates top-level template fields. Changing unit converts every length.

Parameters

Parameter	Type
patch	Partial<Pick<ReportTemplate, "name" | "description" | "locale" | "page" | "unit">>

Returns

void