SIGNALS Docs
Exit Reader View
100%
Theme

Reader View

Dashboard widgets

Register plugin widgets through the dashboard slot and understand their sizing, permissions, settings and caching.

Register a dashboard widget

Declare a dashboard.widgets slot in your plugin manifest, then register that same slot and component through the plugin registrar. Use a core component such as signals.stat-card; plugin-supplied Blade views are not supported. See UI slots for the manifest and registrar contract.

The dashboard bridge gives each slot a stable plugin: widget key and makes it available in the widget gallery. It chooses plugin-stat for signals.stat-card and plugin-html for other supported slot output. Titles come from the slot payload; the plugin name becomes the gallery category. Set the slot permission to a declared permission so the gallery and layout resolver can apply the same access check. Data is resolved for the viewer, including on shared dashboards. Plugin data callbacks receive only the generic widget settings (range, comparison, custom dates and limit); other saved keys never reach plugin code.

Definition fields

The host represents widgets with WidgetDefinition. These fields describe the host contract; plugin slots are adapted by PluginWidgetBridge rather than registering core services directly.

Field Meaning
key, title, category, description Stable identity and gallery text.
allowedSizes, rows Width choices and default vertical grid span. Plugin slots offer one-quarter, one-half and full width.
renderer, dataProvider Core renderer and callback or provider that produces its payload.
permission, anyPermissions, requiresCostVisibility Required ability, alternative abilities, and additional cost visibility.
ranges, comparisonModes, defaultRange, defaultComparison Supported windows and comparison controls.
boardRangeAware Whether the widget follows the board range until pinned.
drillLabel, drillRoute, defaultSection Drill-down and initial placement metadata.
sharedCache, aclSharedCache, sharedCacheWhen Permission-aware cache partition declarations.

Saved settings accept only declared keys and scalar values of the supported shape. Dates use YYYY-MM-DD; a completed custom window must have its start on or before its end. Limits are bounded, unknown keys are discarded, and settings over 2 KB are discarded. Dashboard names accept at most 255 characters; group labels accept at most 80.

Cache and recipient scope

Plugin slot widgets use a per-viewer cache partition. Widget results expire after five minutes by default, configurable under Admin → System → Caching. Settings and board filters participate in the key. Do not retain request data in a singleton or capture a publisher’s identity for use by a recipient.

Core definitions can opt into company-wide caching or a warehouse-permission partition. Those declarations are safe only when every visibility input is represented by the cache context. Personal data must remain per-viewer. The slot bridge does not opt plugin widgets into shared caching.

Verify the widget

Test registration, permission refusal, valid payload rendering, and the same layout viewed by two people with different access. Use the slot bridge tests as examples, then check the widget gallery and a shared board. A shared board shares placement and settings; it does not grant access to the underlying records.