Skip to main content
All docs
V25.1
  • ASPxClientDashboardItemVisualInteractivityEventArgs Class

    Provides data for the ASPxClientDashboard.ItemVisualInteractivity event.

    Declaration

    declare class ASPxClientDashboardItemVisualInteractivityEventArgs extends ASPxClientEventArgs

    Remarks

    The ASPxClientDashboard.ItemVisualInteractivity event allows you to provide custom visual interactivity for data-bound dashboard items that support element selection and highlighting. This event is raised for dashboard items with disabled master filtering. Visual interactivity is enabled for master filter items by default. The ASPxClientDashboard fires this event when master filtering is applied to the current dashboard item or you drill down to this dashboard item.

    Use the ASPxClientDashboardItemVisualInteractivityEventArgs.ItemName event parameter to obtain the name of the dashboard item for which the event was raised. The ASPxClientDashboardItemVisualInteractivityEventArgs.SetTargetAxes method allows you to specify data axes used to perform custom interactivity actions (selection of grid rows, selection and highlighting of chart series points, etc.).

    To specify the selection mode and enable highlighting, use the ASPxClientDashboardItemVisualInteractivityEventArgs.SetSelectionMode and ASPxClientDashboardItemVisualInteractivityEventArgs.EnableHighlighting methods respectively. The ASPxClientDashboardItemVisualInteractivityEventArgs.SetDefaultSelection method provides the capability to specify the default selection for the current dashboard item.

    After the selection is changed, the ASPxClientDashboard.ItemSelectionChanged event is raised. Its ASPxClientDashboardItemSelectionChangedEventArgs.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.

    Warning

    A use of ASPxClientDashboard API reduces flexibility when you configure the control. The DashboardControl underlies the ASPxClientDashboard object. The control provides access to all client settings and allows you to implement complex scenarios. We recommend that you use the DashboardControl API to configure the Web Dashboard on the client. More information: Client-Side Functionality.

    The corresponding DashboardControl’s event: ViewerApiExtensionOptions.onItemVisualInteractivity.

    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;
    }
    

    Inherited Members

    Inheritance

    ASPxClientEventArgs
    ASPxClientDashboardItemVisualInteractivityEventArgs

    Properties

    ItemName Property

    Gets the component name of the dashboard item for which the event was raised.

    Declaration

    ItemName: string

    Property Value

    Type Description
    string

    A string value that is the component name of the dashboard item.

    Methods

    EnableHighlighting(enableHighlighting) Method

    Enables highlighting for the current dashboard item.

    Declaration

    EnableHighlighting(
        enableHighlighting: boolean
    ): void

    Parameters

    Name Type Description
    enableHighlighting boolean

    true, to enable highlighting; otherwise, false.

    See Also

    GetDefaultSelection Method

    Gets the default selection for the current dashboard item.

    Declaration

    GetDefaultSelection(): ASPxClientDashboardItemDataAxisPointTuple[]

    Returns

    Type Description
    ASPxClientDashboardItemDataAxisPointTuple[]

    An array of ASPxClientDashboardItemDataAxisPointTuple objects that are the axis point tuples identifying the selected elements.

    See Also

    GetSelectionMode Method

    Gets the selection mode for dashboard item elements.

    Declaration

    GetSelectionMode(): string

    Returns

    Type Description
    string

    A DashboardSelectionMode value that specifies the selection mode.

    Remarks

    Use the ASPxClientDashboardItemVisualInteractivityEventArgs.SetSelectionMode property to set the selection mode.

    See Also

    GetTargetAxes Method

    Gets data axes used to perform custom interactivity actions.

    Declaration

    GetTargetAxes(): string[]

    Returns

    Type Description
    string[]

    An array of String objects that are the names of data axes.

    See Also

    IsHighlightingEnabled Method

    Returns whether highlighting is enabled for the current dashboard item.

    Declaration

    IsHighlightingEnabled(): boolean

    Returns

    Type Description
    boolean

    true, if highlighting is enabled; otherwise, false.

    See Also

    SetDefaultSelection(values) Method

    Sets the default selection for the current dashboard item.

    Declaration

    SetDefaultSelection(
        values: ASPxClientDashboardItemDataAxisPointTuple[]
    ): void

    Parameters

    Name Type Description
    values ASPxClientDashboardItemDataAxisPointTuple[]

    An array of ASPxClientDashboardItemDataAxisPointTuple objects specifying axis point tuples used to select default elements.

    See Also

    SetSelectionMode(selectionMode) Method

    Sets the selection mode for dashboard item elements.

    Declaration

    SetSelectionMode(
        selectionMode: string
    ): void

    Parameters

    Name Type Description
    selectionMode string

    A DashboardSelectionMode value that specifies the selection mode.

    Remarks

    Use the ASPxClientDashboardItemVisualInteractivityEventArgs.GetSelectionMode property to get the selection mode.

    See Also

    SetTargetAxes(targetAxes) Method

    Sets data axes used to perform custom interactivity actions.

    Declaration

    SetTargetAxes(
        targetAxes: string[]
    ): void

    Parameters

    Name Type Description
    targetAxes string[]

    An array of String objects that specify names of data axes.

    See Also