Skip to main content
All docs
V25.1
  • Custom Interactivity in the Web Dashboard

    • 3 minutes to read

    Dashboard Item Interactivity

    Along with built-in master filtering and drill-down, data-bound dashboard items in which you can select and highlight elements also support custom visual interactivity. The ViewerApiExtensionOptions.onItemVisualInteractivity event is raised for dashboard items with disabled master filtering. The Web Dashboard control also fires this event when a user applies master filtering to the current dashboard item or changes the drill-down level in this dashboard item.

    You can use the following event arguments:

    e.itemName
    Gets the component name of the dashboard item for which the event was raised.
    e.setTargetAxes
    Sets data axes used to perform custom interactivity actions.
    e.setSelectionMode
    Sets the selection mode for dashboard item elements.
    e.enableHighlighting
    Specifies whether to enable highlighting for the current dashboard item.
    e.setDefaultSelection
    Sets the default selection for the current dashboard item.

    Selection changes raise the ViewerApiExtensionOptions.onItemSelectionChanged event. Its e.getCurrentSelection method returns the selected elements.

    The following table lists possible target axes for each dashboard item and supported interactivity capabilities:

    Dashboard Item

    Target Axes

    Selection

    Highlighting

    GridItem

    Default

    Dashboard_GreenTick

    ChartItem

    Argument

    Series

    Dashboard_GreenTick

    Dashboard_GreenTick

    ScatterChartItem

    Argument

    Dashboard_GreenTick

    Dashboard_GreenTick

    PieItem

    Argument

    Series

    Dashboard_GreenTick

    Dashboard_GreenTick

    CardItem

    Default

    Dashboard_GreenTick

    Dashboard_GreenTick

    GaugeItem

    Default

    Dashboard_GreenTick

    Dashboard_GreenTick

    MapItem

    Default

    Dashboard_GreenTick

    Dashboard_GreenTick

    TreemapItem

    Default

    Dashboard_GreenTick

    Dashboard_GreenTick

    Note that the Grid dashboard item does not support custom interactivity when Cell Merging is enabled.

    Custom Item Interactivity

    You can implement a master filter and drill-down for custom dashboard items. Refer to the following topic for details: Implement a Custom Item Interactivity.

    Example

    The Web Dashboard allows you to add custom interactivity to dashboards. For this, handle the ViewerApiExtensionOptions.onItemVisualInteractivity event. You can get data axes used to apply custom interactivity actions, specify the selection mode for dashboard item elements and so on. Use event arguments to process the multidimensional data to get the slice, axes, or tuples.

    The change of the selection in the dashboard item raises the ViewerApiExtensionOptions.onItemSelectionChanged event.

    • Select categories in the Grid dashboard item to visualize its quantity in the dxBarGauge widget. The hidden ‘Quantity’ measure is used to pass values to the client.

      Web Dashboard - Custom Interactivity (Grid and dxBarGauge)

    • The Chart dashboard item highlights bars corresponding to a hovered argument value.

      Web Dashboard - Custom Interactivity - Highlight selection in a Chart item

    View Example: ASP.NET Core

    var dimensionValues = [];
    
    function onBeforeRender(dashboardControl) {
        if (dashboardControl) {
            dashboardControl.on('dashboardEndUpdate', createControls);
            var viewerApiExtension = dashboardControl.findExtension("viewerApi");
        }
        if (viewerApiExtension) {
            viewerApiExtension.on('itemVisualInteractivity', addCustomInteractivity);
            viewerApiExtension.on('itemSelectionChanged', applyCurrentSelection);
        }
    }
    
    function addCustomInteractivity(args) {
        if (args.itemName == "gridDashboardItem1") {
            args.setTargetAxes(["Default"]);
            args.setSelectionMode("Multiple");
        }
        if (args.itemName == "chartDashboardItem1") {
            args.setTargetAxes(["Argument"]);
            args.enableHighlighting(true);
        }
    }
    
    function createControls() {
        $('#barGauge').dxBarGauge({
            startValue: 0,
            endValue: 10000,
            values: getAllValues(),
            title: {
                text: "Product Quantity",
                font: {
                    size: 28,
                }
            },
            label: {
                format: 'fixedPoint',
                precision: 0
            },
            tooltip: {
                enabled: true,
                customizeTooltip(arg) {
                    return {
                        text: getText(dimensionValues[arg.index], arg.value),
                    };
                },
            },
            legend: {
                visible: true,
                verticalAlignment: 'bottom',
                horizontalAlignment: 'center',
                customizeText(arg) {
                    return getText(dimensionValues[arg.item.index], arg.text);
                }
            }
        });
    }
    
    function getText(item, text) {
        return `${item} - ${text}`    
    }
    
    function applyCurrentSelection(args) {
        var quantityValues = [];
        dimensionValues = [];
        if (args.itemName == "gridDashboardItem1" & args.getCurrentSelection().length != 0) {
            var viewerApiExtension = dashboardControl.findExtension('viewerApi');
            var clientData = viewerApiExtension.getItemData("gridDashboardItem1");
            for (var i = 0; i < args.getCurrentSelection().length; i++) {
                var dimensionValue = args.getCurrentSelection()[i].getAxisPoint().getValue();
                var currentTuple = args.getCurrentSelection()[i],
                    slice = clientData.getSlice(currentTuple.getAxisPoint()),
                    quantity = (slice.getMeasureValue(clientData.getMeasures()[0].id)).getValue();            
                quantityValues.push(quantity);
                dimensionValues.push(dimensionValue);
            }
        } else {
            quantityValues = getAllValues();
        }
        $("#barGauge").dxBarGauge("instance").values(quantityValues);
    }
    
    function getAllValues() {
        var viewerApiExtension = dashboardControl.findExtension('viewerApi');
        dimensionValues = [];
        var quantityValues = [];
        var   clientData = viewerApiExtension.getItemData("gridDashboardItem1");
        for (var i = 0; i < clientData.getAxis("Default").getPoints().length; i++) {
            var slice = clientData.getSlice(clientData.getAxis("Default").getPoints()[i]),
                quantity = (slice.getMeasureValue(clientData.getMeasures()[0].id)).getValue(),
                dimensionValue = clientData.getAxis("Default").getPoints()[i].getValue();        
            quantityValues.push(quantity);
            dimensionValues.push(dimensionValue);
        }
        return quantityValues;
    }
    
    See Also