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.