ContextQMD
Back to Devexpress

Create Custom Properties in the Web Dashboard

dashboard-401702-web-dashboard-advanced-customization-create-custom-properties.md

latest9.5 KB
Original Source

Create Custom Properties in the Web Dashboard

  • Aug 05, 2025
  • 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

  2. Viewer

  3. Designer

  4. Event Subscription

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:

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

ClassDescriptionPropertyExample
DashboardStores custom data related to the dashboard.Dashboard.customPropertiesDashboard Description
DashboardItemStores 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.customPropertiesChart’s Scale Breaks
Dashboard Item Description
Chart’s Constant Lines
DataItemContainerStores custom data related to grid column, chart series, and other dashboard item elements.DataItemContainer.customPropertiesChart’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:

ClassUI elementAPI
DashboardDashboardToolboxExtension
DashboardMenuItem
DashboardItemDashboard Item MenuOptionsPanelExtensionOptions.onCustomizeSections
DataItemContainerData Item MenuBindingPanelExtensionOptions.onCustomizeDataItemContainerSections

Event Subscription

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

javascript
// 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.

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

Tutorials

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

Examples on GitHub