Build a canvas

A canvas is the dashboard surface where widgets live. Most widgets read from a data object, so a canvas always reflects your current records rather than a static snapshot. This page covers creating a canvas, the edit mode, adding and configuring widgets, and the actions every widget shares. Each widget type then has its own page.

Create a canvas

1. Open the Ecosystem tab (⌘⇧E) and choose Canvas.
2. Click New at the top right.

There is no dialog: SPARK creates a canvas called Canvas (or Canvas (2) and so on, if the name is taken) and opens it in edit mode, ready for its first widget, with the widget library open beside it. A new canvas starts at the Document width and keeps its proportions; see Layout.

To name it, click its title in the app header, or choose Rename from the canvas's ⋯. The Rename canvas dialog edits the title, an optional description and, when the workspace has canvas groups, its Group.

The dialog also shows who created and last updated the canvas.

The canvas page

The canvas's controls sit at the right of the app header:

• Switch canvas, an icon that lists the workspace's canvases with a search box, to open another one in this one's place.
• The canvas's ⋯, which holds Switch canvas, Edit canvas & context, Rename, Width, Keep proportions, Move to group (when the workspace has groups), Duplicate, Export PDF (marked Beta) and Archive.

When the canvas has context variables, a bar under the header holds their filters. Without any, the widgets start right under the header.

Edit mode

To change a canvas, open its ⋯ and choose Edit canvas & context, or press ⌘E (Ctrl+E on Windows). The same item is on a canvas card's ⋯ on the Canvas page. One edit mode covers the widgets, their layout and the canvas's context variables together. The widget library opens beside the canvas when edit mode starts.

The edit bar under the header has two rows:

• The first holds Width on the left, and on the right Discard changes, Add widget and Save and close.
• The second holds the canvas's context variables and Add context variable. See Context variables.

Save and close keeps your changes and returns to view mode. ⌘S saves and stays in edit mode. Discard changes leaves edit mode without them, asking first when there are any. ⌘E also leaves edit mode; unsaved changes are then caught when you try to leave the canvas. Until you save, nobody else sees your changes, so a shared canvas stays stable for everyone reading it while you reshape it.

Add a widget

Widgets are made once and shared: every canvas that shows a widget shows the same one, from the workspace's widget library.

In edit mode, click Add widget. The library opens beside the canvas:

• Click a widget in it to add it to the canvas, or drag it onto the grid to a place of its own.
• Click New widget to make one. Pick its type from Chart, KPI, Default table, Lookthrough table, Tasks or Files, then configure it. See Create a widget.
• Click Add text for a text box.

You can also right-click empty space on the canvas in edit mode and choose Add new item, then Chart, KPI, Table, Tasks, Files or Text.

The widget catalog

Configure a widget

A new widget opens in the New widget dialog; an existing one opens in Edit widget. In edit mode, click a widget's header, or choose Edit widget at the top of its ⋯ or right-click menu. A click on a KPI's number opens it too.

The dialog is a split view: a live preview and a configuration panel. When the widget is on other canvases too, the dialog says so (Used in 3 canvases; changes show everywhere), because editing it changes it everywhere.

Name the widget from the bar above the panel: click the title to rename it, and add an optional description. Until you name it, a widget is named after what it shows: a chart after its source, its first series and its function (for example Orders Amount Sum), a table after its source, a lookthrough after its source with (Lookthrough), and Tasks and Files after themselves. A title you type is kept.

The configuration panel is organized into collapsible sections. Which appear depends on the type:

• Data holds the Data source and the type's fields.
• Filters & sorting (on a table, Filters, sorting & selection) reuses the builder from data views: Filters, including advanced boolean logic, and Sort by. See Manage data views.
• Appearance holds the visual options of charts and KPIs.
• Display holds a table's, task list's or file list's layout options.

A type selector at the top of the panel converts a widget between types without rebuilding it.

Let a widget size itself

Table, tasks and files widgets have an Auto-fit height of canvas switch under Display, on for a new widget. While it is on, the card takes the height its content needs instead of the number of grid rows you drew, up to a Maximum height (48, or 12rem, to start), past which the content scrolls. The panel puts it plainly: it grows and shrinks the widget so its content always fits, instead of sizing it for the largest thing anyone might open. Text boxes always fit their text.

It is the setting for anything that grows: a task list people keep adding to, or a table whose rows arrive later. Resize an auto-fit card by hand and it goes back to its content's height, with a note pointing at the switch.

Actions every widget shares

Each widget card has a ⋯ in its header. It names the widget's data object at the top, then lists the controls the header shows (such as Filter, Sort and Expand), then the exports. A narrow card shows only the ⋯, so it always holds everything. Exactly which actions appear depends on the type:

• Expand opens the widget in a large modal so you can read it at full size. Tables page through more rows there.
• Export chart downloads the widget's displayed data as a CSV: the aggregated values you see, or the visible rows. Table, tasks and files widgets use this label too.
• Export data downloads the underlying records behind a chart, KPI or lookthrough as a CSV, with the widget's filters and sort applied. Tables, tasks and files don't have it.
• Export card saves the whole widget as a PNG image.

A widget whose filter or sort is set shows it as a small pill in its header; hover it for a summary such as 2 filters or Sorted by Price.

To export the whole canvas, see Export a canvas to PDF.

Arrange and edit widgets

In edit mode, a widget's ⋯ and its right-click menu name the data object, then Edit widget and the widget's controls (such as Filter), then its edit actions: Cut (⌘X), Copy (⌘C), Paste (⌘V), Duplicate (⌘D) and Remove from canvas. Chart widgets also get a Chart options submenu. Removing a widget takes it off this canvas only; it stays in the library. To move or resize widgets, see Layout.

A widget that couldn't be loaded can still be removed.

Let an agent build or edit a canvas

An agent with the canvas tools can build a canvas for you, or change one: add, move and edit widgets, including lookthroughs, filters, sorts, chart options, text boxes and context variables. It lays widgets out in full rows: KPIs share a row, charts go two to a row unless one is crowded, and tables take the full width. Ask in a thread, with the canvas in the thread's context. See Start a thread and Tools.

In Settings › Agent Studio › Tools, these tools are listed under Canvas: Spark Manage Canvases, Spark List Canvases, Spark Read Canvas, Spark Read Widget, Spark Create Widget, Spark Update Widget, Spark Update Canvas and Spark Export Canvas Pdf.

Where to go next

• Make a widget from scratch: Create a widget
• Configure each widget type, starting with the Chart
• Find, reuse and clean up widgets: Widget library
• Focus a canvas on different slices: Context variables
• Arrange, size and group canvases: Layout
• Print it: Export a canvas to PDF