Create Custom Properties in the Web Dashboard

• Oct 10, 2023
• 4 minutes to read

Custom properties allow you to store custom settings in a dashboard definition. You can read these settings and use their values to implement and embed your functionality into the Web Dashboard.

To update the control according to a custom property’s value, create an extension (a JavaScript module). Such extensions need to implement the following parts:

1. Model

   The model is a CustomPropertyMetadata object that contains the property name, type, and the default value. It also specifies on which level the property is created (dashboard, dashboard item or data item container).

2. Viewer

   In this part you modify the viewer part according to the saved custom property value. You can use the client methods and events to change the displayed elements.

3. Designer

   This part contains designer settings. Add editors and control elements to configure and change the custom property’s values in the UI. This part is not required if you use the extension in Viewer mode or do not want to let users edit a custom property’s value.

4. Event Subscription

   This part contains event subscriptions.

Model

Custom properties are stored in a CustomProperties collection in a structured format. Each object in this collection contains the custom property’s metadata.

Create a CustomPropertyMetadata object and pass it to the Model.registerCustomProperty method. This method integrates custom property to a dashboard:

var dashboardDescriptionProperty = {
    ownerType: Model.Dashboard,
    propertyName: "DashboardDescription",
    defaultValue: "",
    valueType: 'string'
};
Model.registerCustomProperty(dashboardDescriptionProperty);

If you do not register the property, you still can read and write a custom property’s values. But in this case the control does not react to changes of the property’s value. For example, you cannot save your actions to the control’s history and use undo/redo. For example, this approach is useful when you want to record the time when a dashboard was created and other technical information.

The following table lists classes where you can store custom properties:

Class	Description	Property	Example
Dashboard	Stores custom data related to the dashboard.	Dashboard.customProperties	Dashboard Description
DashboardItem	Stores custom data related to a particular dashboard item. For example, DashboardItem stores data for all dashboard items, while ChartItem stores it only for Chart item.	DashboardItem.customProperties	Chart’s Scale Breaks Dashboard Item Description Chart’s Constant Lines
DataItemContainer	Stores custom data related to grid column, chart series, and other dashboard item elements.	DataItemContainer.customProperties	Chart’s Line Options

Viewer

Use the custom property’s getValue method to obtain the current value. To avoid XSS attacks, do not pass this value to HTML markup as is.

Access a dashboard or underlying widgets and change the behavior according to the obtained custom property value and handle events that allow you to customize the viewer. For example, use the ViewerApiExtension‘s events.

Designer

You can provide editors that enable users to change the custom property’s value in Designer mode. The table below lists UI elements that you can customize:

Class	UI element	API
Dashboard	Dashboard	ToolboxExtension DashboardMenuItem
DashboardItem	Dashboard Item Menu	OptionsPanelExtensionOptions.onCustomizeSections
DataItemContainer	Data Item Menu	BindingPanelExtensionOptions.onCustomizeDataItemContainerSections

Event Subscription

The extension’s on and off methods help you subscribe to and unsubscribe from events:

// An event handler for the ItemWidgetOptionsPrepared event:
function onItemWidgetOptionsPrepared(args) {
    alert(args.itemName)
}
...
var viewerApiExtension = dashboardControl.findExtension('viewerApi');
// Subscribe to the ItemWidgetOptionsPrepared event:
if(viewerApiExtension) {
    viewerApiExtension.on('itemWidgetOptionsPrepared', onItemWidgetOptionsPrepared)
}
...
// Unsubscribe from the ItemWidgetOptionsPrepared event:
if(viewerApiExtension) {
    viewerApiExtension.off('itemWidgetOptionsPrepared', onItemWidgetOptionsPrepared)
}

Extension Registration

To add the extension to the Web Dashboard, call the DashboardControl.registerExtension method and pass the extension name as a parameter.

The code snippet below shows how to register the ChartConstantLinesExtension extension that allows you to add and display constant lines.

 function onBeforeRender(s, e) {
     // ...
    dashboardControl.registerExtension(new ChartConstantLinesExtension(dashboardControl));
 }

You need to register the extension before the control is rendered (before you call the DashboardControl.render method or when handling the BeforeRender event). See the following topics for more information about handling client-side events:

• HTML JavaScript - Client-Side API Overview
• ASP.NET Core - Client-Side API Overview
• ASP.NET MVC - Client-Side API Overview
• ASP.NET Web Forms - Client-Side API Overview

Tutorials

The following tutorials describe how to create custom properties step-by-step:

• Chart’s Scale Breaks
• Chart’s Line Options
• Dashboard Description
• Dashboard Item Description
• Chart’s Constant Lines

Examples on GitHub

• Dashboard for ASP.NET Core - Custom Properties
• Dashboard for MVC - Custom Properties
• Dashboard for MVC - How to Hide Series by Clicking on a Chart Legend
• Dashboard for Web Forms - Custom Properties
• Dashboard for Web Forms - How to use Custom Properties to Modify Ranges in the Gauge Dashboard Item
• Dashboard for JavaScript - Custom Properties