Chart's Line Options - Custom Property

• Feb 24, 2023
• 3 minutes to read

This extension changes the dash style of the each series line in the Chart dashboard item.

In the extension code you can find how to:

• Add a custom string property for a specific data item container (Chart’s series).
• Integrate a Line Options (Custom) section into the data item menu with the SelectBox widget as an editor.

Tip

Examples on GitHub:

• HTML JavaScript Dashboard - Custom Properties
• ASP.NET Core Dashboard Control - Custom Properties
• ASP.NET MVC Dashboard Control - Custom Properties
• ASP.NET Web Forms Dashboard Control - Custom Properties

Every extension that provides a custom property can be divided to the following parts:

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 (a dashboard, dashboard item or data item container). Use the Model.registerCustomProperty property to register the custom property definition.

var ChartLineOptionsExtension = (function() {
    var Model = DevExpress.Dashboard.Model;

    // 1. Model
    const dashStyleProperty = {
        ownerType: Model.SimpleSeries,
        propertyName: "DashStyleProperty",
        defaultValue: "solid",
        valueType: 'string'
    };

    Model.registerCustomProperty(dashStyleProperty);

    return ChartLineOptionsExtension;
}());

Viewer

In this part, you modify the viewer according to the saved custom property value. You can use the client methods and events to change the displayed elements. In this example, you change the Chart widget’s LineSeries.dashStyle according to the custom property value.

var ChartLineOptionsExtension = (function() {
    var Model = DevExpress.Dashboard.Model;

    // 2. Viewer
    function onItemWidgetOptionsPrepared(args) {
        if (args.dashboardItem instanceof Model.ChartItem) {
            var seriesOptionArray = args.options['series'] || [];
            seriesOptionArray.forEach(function(seriesOption) {
                if (seriesOption.type === "line") {
                    var series = args.chartContext.getDashboardItemSeries(seriesOption);
                    if (series) {
                        var dashStyle = series.customProperties.getValue(dashStyleProperty.propertyName);
                        seriesOption.dashStyle = dashStyle;
                    }
                }
            });
        }
    };

    return ChartLineOptionsExtension;
}());

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. For this custom property, integrate a Line Options (Custom) section in the data item menu with the SelectBox widget as an editor.

var ChartLineOptionsExtension = (function() {
    var Model = DevExpress.Dashboard.Model;

    // 3. Designer
    function onCustomizeSections(args) {
        var simpleSeries = args.dataItemContainer;
        if (simpleSeries instanceof Model.SimpleSeries
            && ['Line', 'FullStackedLine', 'StackedLine', 'StepLine', 'Spline'].indexOf(simpleSeries.seriesType()) !== -1
        ) {
            args.addSection({
                title: "Line Options (Custom)",
                items: [
                    {
                        dataField: dashStyleProperty.propertyName,
                        editorType: "dxSelectBox",
                        label: {
                            text: 'Dash style'
                        },
                        editorOptions: {
                            items: [
                                { value: 'dash', displayValue: "Dashes" },
                                { value: 'dot', displayValue: "Dots" },
                                { value: 'longDash', displayValue: "Long Dashes" },
                                { value: 'solid', displayValue: "Solid Line" },
                                { value: 'dashdot', displayValue: "Dash-Dots" }
                            ],
                            displayExpr: "displayValue",
                            valueExpr: "value"
                        }
                    }
                ]
            });
        }
    };

    return ChartLineOptionsExtension;
}());

Event Subscription

This part contains event subscriptions. In this example, it is the ViewerApiExtensionOptions.onItemWidgetOptionsPrepared and BindingPanelExtensionOptions.onCustomizeDataItemContainerSections events.

var ChartLineOptionsExtension = (function() {

    // 4. Event Subscription
    function ChartLineOptionsExtension(dashboardControl) {
        this.name = 'ChartLineOptions',
        this.start = function () {
            let viewerApiExtension = dashboardControl.findExtension('viewerApi');
            if (viewerApiExtension) {
                viewerApiExtension.on('itemWidgetOptionsPrepared', onItemWidgetOptionsPrepared);
            }
            let bindingPanelExtension = dashboardControl.findExtension("itemBindingPanel");
            if (bindingPanelExtension) {
                bindingPanelExtension.on('customizeDataItemContainerSections', onCustomizeSections);
            }
        },
        this.stop = function () {
            let viewerApiExtension = dashboardControl.findExtension('viewerApi');
            if (viewerApiExtension) {
                viewerApiExtension.off('itemWidgetOptionsPrepared', onItemWidgetOptionsPrepared);
            }
            let bindingPanelExtension = dashboardControl.findExtension("itemBindingPanel");
            if (bindingPanelExtension) {
                bindingPanelExtension.off('customizeDataItemContainerSections', onCustomizeSections);
            }
        }
    }

    return ChartLineOptionsExtension;
}());