All docs
V20.1
20.1
19.2
The page you are viewing does not exist in version 19.2. This link will take you to the root page.
19.1
The page you are viewing does not exist in version 19.1. This link will take you to the root page.
18.2
The page you are viewing does not exist in version 18.2. This link will take you to the root page.
18.1
The page you are viewing does not exist in version 18.1. This link will take you to the root page.
17.2
The page you are viewing does not exist in version 17.2. This link will take you to the root page.

Custom Properties

  • 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:

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('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:

Examples

The following tutorials describe how to create custom properties: