Struct Widget 

pub struct Widget {
    pub key: &'static str,
    pub title: String,
    pub kind: WidgetKind,
    pub default_span: Span,
    pub permission: Option<&'static str>,
    pub data: WidgetDataFn,
    pub default_period: Option<&'static str>,
    pub filters: Vec<WidgetFilter>,
}

A registered dashboard widget.

Register via AdminPlugin::register_widget(...).

Fields

key: &'static str

URL-safe unique key, e.g. "umbral_total_models".

title: String

Human-readable title shown in the widget card header.

kind: WidgetKind

Determines which renderer (KPI card, chart, table, feed).

default_span: Span

Default grid span when the user hasn’t customized.

permission: Option<&'static str>

Optional permission codename. None = any staff user may see.

data: WidgetDataFn

Async function that computes and returns the payload.

default_period: Option<&'static str>

Default period preset used by line/bar/etc. widgets that carry a period-chip strip — "7d", "30d", "90d". When Some, the handler pre-fills WidgetParams.period from this value on first load (no ?period= in the URL), so the matching chip renders highlighted AND the data closure receives the same period via params.period_days(). None falls back to whatever the template / data closure chooses as its fallback.

filters: Vec<WidgetFilter>

Controls rendered in this widget’s header — see WidgetFilter.

Empty means no controls, with one compatibility exception: a WidgetKind::Line with no declared filters still gets the historic [7d][30d][90d] strip, because that strip used to be hardcoded in line.html and removing it would silently strip controls from every line chart already in the wild.

Implementations

impl Widget

pub fn new( key: &'static str, title: impl Into<String>, kind: WidgetKind, data: WidgetDataFn, ) -> Self

Build a widget without naming every field.

Prefer this over a struct literal. Widget grows fields as the dashboard grows (this is how filters arrived), and every new field breaks every literal that spells out the old ones. Going through the builder means the next field costs you nothing.

Widget::new("orders", "Orders", WidgetKind::Bar, data_fn)
    .with_span(6, 2)
    .filter(WidgetFilter::period_default())

pub fn with_permission(self, codename: &'static str) -> Self

Gate the widget behind a permission codename.

pub fn filter(self, filter: WidgetFilter) -> Self

Add one filter control to the widget header.

pub fn with_filters( self, filters: impl IntoIterator<Item = WidgetFilter>, ) -> Self

Replace the widget’s filters wholesale.

pub fn with_span(self, cols: u8, rows: u8) -> Self

Override the default grid span. Lets a caller resize a builtin (or any pre-built widget) at registration time without having to re-construct the whole struct literal:

.register_widget(builtin_total_models_widget().with_span(6, 2))
.register_widget(builtin_recent_users_widget().with_span(6, 2))

cols is clamped at the 12-col grid; rows is whatever the dashboard’s auto-rows-[...] accepts (1 = 120px).

pub fn with_default_period(self, period: &'static str) -> Self

Pre-select a period chip on the widget — "7d", "30d", "90d". On first load (no ?period= in the URL), the handler stamps this into WidgetParams.period before calling the data closure, so the chip strip highlights the right preset AND the data fn computes the right window. Override on a per-request basis happens via the chip clicks (which send their own ?period= query).

shop_daily_sales_chart().with_default_period("7d")
// → first paint shows 7d highlighted, 7 days of data;
//   clicking "30d" hands control to the URL state.

Trait Implementations

impl Clone for Widget

fn clone(&self) -> Widget

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Widget

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.