Widgets
Charts, tables, KPIs, custom visualizations, files, and the prose that gives a dashboard structure.
Contents
What is a widget?
A widget is one tile on a dashboard. A data widget has two halves. Its pipeline gets the data, and its configuration draws the data as a chart or table. A dashboard holds up to 100 live widgets, and removed widgets do not count (Limits).
Where does a widget's data come from?
From its pipeline, the recipe for its data. Each stage in it is one call to a tool on a connected data source. The transform is a short piece of code that takes what the stages returned and shapes it into the rows the chart draws. A widget that combines several calls has one stage for each.
Take a chart of the US unemployment rate by year:
| Part | In this chart |
|---|---|
| Stage | Calls economy__series_observations for the series UNRATE |
| What comes back | One row per month, such as { date: "2024-01-01", UNRATE: 3.7 } |
| Transform | Averages the months of each year into one row, such as { year: 2024, rate: 4.0 } |
| Configuration | Draws year along the bottom and rate as a line |
A refresh runs the stages and the transform again. A restyle changes only the configuration, so recoloring a chart never fetches anything.
What are the different types of widgets?
| Type | What it shows |
|---|---|
| Chart | Line, bar, area, scatter, pie and the other Apache ECharts types |
| KPI | A single headline number |
| Table | Rows and columns |
| Pivot | Values summarised by row groups and column groups |
| Progress | A value measured against a target |
| Library visualization | A custom chart, such as a marimekko or a circle pack, drawn by code saved in the workspace |
| Markdown | Text, headings and images, with no data behind it |
| File | One uploaded image or PDF, with an optional caption |
The chart type lives in the widget's configuration. Turning a line chart into a bar chart is a restyle of the same widget.
A library visualization points at an entry on the workspace's Widgets page and never carries the code itself. The code draws SVG and runs sealed off in a sandbox.
How do you put an image or PDF on a dashboard?
Attach it to a chat and ask the built-in assistant to put it on the dashboard. There is no add button
for a file, and the assistant only places files attached to the conversation you are in. Your agent
uploads a file with upload_file and places it with add_widget.
A file widget shows one image or PDF as it is, with a caption of up to 280 characters. A PDF tile shows the first page, and the expanded widget scrolls through every page. Click the tile to open the file full size.
A markdown widget can show an uploaded image inline:
FILE_ID is the id upload_file returned. Only this workspace's uploads display there, and images
from other websites stay blocked.
A chart built from an uploaded file names it under Sourced from. Click the name to open an image or PDF, or to download a spreadsheet or text file.
When an uploaded file is deleted, the widgets that use it stay in place. A file widget, or an image in a markdown widget, reads Source removed. A chart drawn from a table in the file keeps showing its last data until that data expires. Its next refresh fails, and the expanded chart reads Source file deleted with who deleted it and when. Editors also get Fix with assistant, which opens the built-in assistant to point the chart at new data. Scheduled refreshes skip the chart until then.
Warning
Everyone who can view a dashboard can open the files it shows or charts, guests included. On a public dashboard that means anyone with the address, and on an embed anyone who can open the page around it. Remove the last widget that uses a file and the dashboard stops sharing it.
How do you add headings, dividers and spacers?
With a markdown widget that drops its card frame. Without the frame it reads as part of the page rather than as another tile.
| Write this | Get this |
|---|---|
## Customers and a sentence |
A section heading |
--- |
A divider |
| (nothing) | A spacer |
The grid closes up empty cells, so a spacer is the only way to leave deliberate whitespace.
Data widgets always keep their frame. It holds the title, the expand button and the Discussions button.
How do you discuss a widget with your team?
Open Discussions in the widget's header. Every framed widget has its own thread there. A dot on the button marks an open thread. @mention a colleague in the thread and Vistazo
notifies them.
How do you change a widget?
Ask. Once a widget is on a dashboard, you edit it in place. There is no properties form and no Save button, on the canvas or in the expanded widget. Ask the built-in assistant on the dashboard, or your agent:
Drop the 2019 bar, label this in millions, and make it a line chart.
The title, description, appearance and data source are all reachable this way.
When an edit brings a new transform, Vistazo runs it before saving anything. A transform that fails is refused, so the widget keeps working. An edit that supplies rows directly, or only changes styling, skips that check.