Custom Properties

• Jun 02, 2020
• 4 minutes to read

Custom properties allow you to store custom settings in a dashboard definition. You can read these settings and use these 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:

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:

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('viewer-api');
// 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

Examples

The following tutorials describe how to create custom properties:

• Chart's Scale Breaks - Custom Property
• Chart's Line Options - Custom Property
• Dashboard Description - Custom Property
• Dashboard Item Description - Custom Property
• Chart's Constant Lines - Custom Property