Card Block – one key figure¶
The card shows a single number computed from the records of a query – a count, a sum, an average, a duration – with a caption. It is the widget for the key figures at the top of a dashboard.
This page is part of the widget reference.
1. At a glance¶
| Purpose | Reduces the records of a query to one number |
| Typical use | "Open tickets: 42", "Revenue this month", "Average resolution time in hours" |
| Related | Chart for a development over time, Badge for a small value next to a heading |
2. Settings¶
In addition, the widget has the settings every widget has.
| Setting | Meaning | Default |
|---|---|---|
| "Title" | The caption of the number, computed | none |
| "Query" | The query whose records are counted or calculated | none – required |
| "Function" | The calculation (see below) | None – must be set |
| "Field" | The field the calculation runs over. Not shown for NumberRecords. | – |
| "Start", "End" | For the duration functions: the date fields the span is measured between. The earlier date belongs into "Start". | – |
| "Unit" | For the duration functions: Days, Weeks, Months, Quarters, Years, Hours, Minutes, Seconds | – |
Functions¶
| Function | Result | Needs |
|---|---|---|
| NumberRecords | How many records the query returns | nothing else |
| Minimum, Maximum | The smallest or largest value of the field | "Field" |
| Average, Total | The average or the sum of the field | "Field" (a number field) |
| MinimumDuration, MaximumDuration, AverageDuration, TotalDuration | The shortest, longest, average or summed span between two date fields | "Start", "End" and "Unit" |
A duration function without a "Unit" fails and the card shows no value.
3. Behaviour¶
- The calculation runs in the database over all records of the query, with the read limits of the viewing user. Two users can therefore see different numbers.
- A click on the number opens the records of the query in a dialog, shown with the default grid of the entity.
- If the query cannot be found, the card is left out of the dashboard.
- With "Auto Refresh" the number is calculated again at the interval.
- A configured "Font Size" makes the number one step larger than the caption; a "Text Color" applies to both.
4. Examples¶
Open tickets. "Title" "Open tickets", "Query" "Open tickets", "Function" NumberRecords, "Auto Refresh" on with 60 seconds.
Average resolution time. "Function" AverageDuration, "Start" "Created At", "End" "Resolved At", "Unit" Hours, with a query that only returns resolved tickets.
5. Limitations¶
- The number is shown as the database returns it, without a unit or thousands separator of its own. Put the unit into the "Title".