Dashboards and widgets

A widget is a card computed on the server for a date range. Widgets sit on dashboards, or above a resource’s list.

final class RevenueStat extends VectorWidget
{
    public function __construct(private readonly SqlLink $db) {}

    public function type(): string { return self::STAT; }
    public function cacheSeconds(): int { return 60; }

    public function calculate(WidgetRequest $request): WidgetResult
    {
        // one query for $request->from .. $request->to
        return WidgetResult::stat($current, $previous, 'money:EUR');
    }
}

Widget types

Type

Shows

stat

One figure, compared with the previous period.

trend

A series over time.

partition

A breakdown into slices, such as orders by status.

progress

A figure against a target.

table

A few rows, optionally linking to the full list.

A value’s format is a number, money:EUR, percent or duration.

Shaping a widget

Method

Effect

ranges()

The ranges offered, as key => label, the first the default; 7d, 30d, 90d and 1y by default, and an empty array for none.

width()

3, 4, 6 or 12 columns of the grid.

name(), label(), icon()

The URL segment (by default the class name without Widget, in kebab-case: RevenueWidget is revenue) and how it is shown.

canView()

Who sees it, on top of the dashboard’s or resource’s own visibility.

cacheSeconds()

Above zero, memoizes the result in a bounded per-worker cache, keyed by widget, range and the account it was computed for.

cacheShared()

Shares one cached result between all admins, for figures that are the same for everyone.

Dashboards

#[Dashboard]
final class MainDashboard extends VectorDashboard
{
    public function widgets(): array { return [RevenueStat::class, OrdersTrend::class]; }
}

A dashboard’s name is its class name without Dashboard, in kebab-case (MainDashboard is main), unless name() says otherwise. The dashboard named main — or, without one, the first — is the admin’s home page; the others appear in the navigation drawer under their own labels. canView() hides a whole dashboard from a user.

Resource widgets

A resource’s widgets() appear above its list. A widget runs its own query: when the resource’s scope() narrows what a user may see, narrow the widget’s query the same way, and leave cacheShared() false so one admin is never shown another’s figures.

See also