workspace sdk dashboard widgets

About dashboard widgets

Dashboard widgets appear in Security Desk's dashboard pages. Operators add widgets from a picker panel that displays each widget's name, description, and thumbnail. Once placed on a dashboard, widgets provide live visual content that can refresh automatically and expose configuration options.

Use a dashboard widget when operators need always-visible status, summary data, or lightweight controls on a dashboard page rather than a full page or tile extension.

Note

For tile-based monitoring pages instead of dashboard pages, see About content builders to control what appears inside a tile. See About tile extensions to add side-panel controls, in-tile overlays, and configuration tabs for the selected tile.

Creating a dashboard widget requires two classes:

• DashboardWidgetBuilder - registered as a component, acts as a factory that creates widget instances
• DashboardWidget - provides the visual content and configuration for a placed widget

How dashboard widgets work

1. Your module registers a DashboardWidgetBuilder component.
2. Security Desk lists the builder in the dashboard widget picker using the builder's metadata.
3. When an operator adds the widget, the framework calls CreateWidget(...) to create a DashboardWidget instance.
4. The widget creates its visual content through CreateView().
5. The dashboard refreshes or resizes the widget according to its capabilities and settings.
6. When the module unloads, it unregisters the builder.

DashboardWidgetBuilder

Inherit from DashboardWidgetBuilder and implement the abstract members:

public class MyWidgetBuilder : DashboardWidgetBuilder
{
    public override string Name => "My Widget Builder";

    public override Guid UniqueId => new Guid("A1B2C3D4-E5F6-7890-ABCD-EF1234567890");

    public override string Description => "Displays real-time status information.";

    public override BitmapSource Thumbnail => new BitmapImage(new Uri("pack://application:,,,/MyPlugin;component/Resources/widget.png"));

    public override bool IsSupported(DashboardWidgetBuilderContext context)
    {
        return context.Type == UniqueId;
    }

    public override DashboardWidget CreateWidget(DashboardWidgetBuilderContext context)
    {
        return new MyWidget();
    }
}

DashboardWidgetBuilder members

Member	Type	Description
Name	Property (abstract)	Name shown in the widget picker.
UniqueId	Property (abstract)	Identifier for this builder. Use the same value that the widget returns from WidgetTypeId.
Description	Property (abstract)	Widget description displayed in the widget picker.
Thumbnail	Property (abstract)	Preview image displayed in the widget picker.
Category	Property (virtual)	Widget category identifier. Defaults to Guid.Empty.
Priority	Property (virtual)	Display order in the widget picker. Lower values appear first. Defaults to int.MaxValue.
IsSupported(DashboardWidgetBuilderContext)	Method (abstract)	Return true when the widget can be created in the given context.
CreateWidget(DashboardWidgetBuilderContext)	Method (abstract)	Create and return a new DashboardWidget instance.

DashboardWidgetCategories

The DashboardWidgetCategories class provides built-in category identifiers for the widget picker. Return one of these values from DashboardWidgetBuilder.Category to place your widget under a built-in group.

Constant	Description
DashboardWidgetCategories.GeneralId	General-purpose widgets.
DashboardWidgetCategories.AccessControlId	Access-control widgets.
DashboardWidgetCategories.VideoId	Video-related widgets.
DashboardWidgetCategories.ReportingId	Reporting widgets.
DashboardWidgetCategories.HealthId	Health and status widgets.

public override Guid Category => DashboardWidgetCategories.VideoId;

DashboardWidgetBuilderContext

The context passed to IsSupported and CreateWidget provides:

Member	Type	Description
Type	Guid	The widget's unique type identifier.

DashboardWidget

Inherit from DashboardWidget and implement the abstract members:

public class MyWidget : DashboardWidget
{
    public override Guid WidgetTypeId => new Guid("A1B2C3D4-E5F6-7890-ABCD-EF1234567890");

    public override string WidgetName => "My Widget";

    public override UIElement CreateView()
    {
        return new MyWidgetControl();
    }

    public override void Refresh()
    {
        // Update the widget's data
    }
}

Important

The WidgetTypeId must match the UniqueId of the corresponding DashboardWidgetBuilder. The system uses this identifier to associate placed widgets with their builder.

DashboardWidget required members

Member	Type	Description
WidgetTypeId	Property (abstract)	Unique identifier for this widget type. Must match the builder's UniqueId.
WidgetName	Property (abstract)	Title displayed in the widget's configuration panel.
CreateView()	Method (abstract)	Create the widget's visual content. Called once when the widget is first displayed.

Size and resize

Member	Type	Description
WidgetSize	Property (virtual)	Default dimensions in grid cells. Defaults to 2x2.
MinWidgetSize	Property (virtual)	Minimum dimensions in grid cells. Defaults to 2x2.
MaxWidgetSize	Property (virtual)	Maximum dimensions in grid cells. Defaults to unlimited.
IsResizableHorizontally	Property (virtual)	Whether the widget can be resized horizontally. Defaults to true.
IsResizableVertically	Property (virtual)	Whether the widget can be resized vertically. Defaults to true.

Display defaults

Member	Type	Description
DefaultShowTitle	Property (virtual)	Whether to display the title above the widget. Defaults to false.
DefaultTitle	Property (virtual)	Title text displayed above the widget when DefaultShowTitle is true. Not set by default; override to supply a title.
DefaultBackgroundColor	Property (virtual)	Widget background color. Defaults to dark gray (#282828).

Refresh

Member	Type	Description
IsRefreshable	Property (virtual)	Whether the widget supports refreshing. Defaults to true.
DefaultRefreshAutomatically	Property (virtual)	Whether the widget refreshes on a timer by default. Defaults to false.
DefaultRefreshInterval	Property (virtual)	Timer interval for automatic refresh. Defaults to 1 minute. The minimum is 1 minute and the interval must be a whole number of minutes.
Refresh()	Method (virtual)	Called when the widget needs to update its data. Override to reload content.
CancelRefresh()	Method (virtual)	Called to cancel an in-progress refresh operation.

Options panel

public override UIElement CreateOptionsView()
{
    return new MyWidgetOptionsControl();
}

Member	Type	Description
CreateOptionsView()	Method (virtual)	Create a configuration panel for the widget. Returns null by default (no options panel). The options panel maximum width is 350 pixels.
OnModified()	Method (protected)	Call this when the widget's configuration changes to notify the dashboard to save.

Serialization

Override Serialize and Deserialize to persist widget-specific configuration across sessions:

public override string Serialize()
{
    return m_selectedEntityId.ToString();
}

public override void Deserialize(string value)
{
    if (Guid.TryParse(value, out var entityId))
    {
        m_selectedEntityId = entityId;
    }
}

Member	Type	Description
Serialize()	Method (virtual)	Return a string representing the widget's configuration. Returns null by default.
Deserialize(string)	Method (virtual)	Restore the widget's configuration from a previously serialized string.

Lifecycle

Member	Type	Description
Dispose()	Method (virtual)	Called when the widget is removed from the dashboard. Override to release resources. The base implementation disposes the view and options view if they implement IDisposable.

Registering a dashboard widget builder

Important

This component requires a valid SDK certificate.

Register the builder in your module's Load method. Dashboard widgets are only available in Security Desk.

public class SampleModule : Module
{
    private MyWidgetBuilder m_widgetBuilder;

    public override void Load()
    {
        if (Workspace.ApplicationType == ApplicationType.SecurityDesk)
        {
            m_widgetBuilder = new MyWidgetBuilder();
            m_widgetBuilder.Initialize(Workspace);
            Workspace.Components.Register(m_widgetBuilder);
        }
    }

    public override void Unload()
    {
        if (m_widgetBuilder != null)
        {
            Workspace.Components.Unregister(m_widgetBuilder);
        }
    }
}

See also

• About the Workspace SDK: Workspace SDK architecture and module lifecycle.
• About components: The component registry and registration lifecycle.
• About workspace modules: Workspace module class and Load/Unload lifecycle.
• About Workspace SDK certificates: Certificate requirements for workspace components.