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
GridDashboardItem	DashboardDataAxisNames.DefaultAxis
ChartDashboardItem	DashboardDataAxisNames.ChartArgumentAxis DashboardDataAxisNames.ChartSeriesAxis
ScatterChartDashboardItem	DashboardDataAxisNames.ChartArgumentAxis
PieDashboardItem	DashboardDataAxisNames.ChartArgumentAxis DashboardDataAxisNames.ChartSeriesAxis
CardDashboardItem	DashboardDataAxisNames.DefaultAxis
GaugeDashboardItem	DashboardDataAxisNames.DefaultAxis
MapDashboardItem	DashboardDataAxisNames.DefaultAxis
TreemapDashboardItem	DashboardDataAxisNames.DefaultAxis

Note

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 a custom interactivity to dashboards using the ASPxClientDashboard.ItemVisualInteractivity event. This example demonstrates the following capabilities.

• The Grid dashboard item allows you to select categories and visualize a corresponding product quantity using the dxBarGauge widget. Note that the hidden ‘Quantity’ measure is used to pass the required values to the client.
• The Chart dashboard item highlights bars corresponding to a hovered argument value.

View Example

CustomInteractivity.js

var defaultAxis = DashboardDataAxisNames.DefaultAxis,
    argumentAxis = DashboardDataAxisNames.ChartArgumentAxis;

function addCustomInteractivity(args) {
    if (args.ItemName == "gridDashboardItem1") {
        args.SetTargetAxes([defaultAxis]);
        args.SetSelectionMode("Multiple");
    }
    if (args.ItemName == "chartDashboardItem1") {
        args.SetTargetAxes([argumentAxis]);
        args.EnableHighlighting(true);
    }
}

function createControls() {
    $('#barGauge').dxBarGauge({
        startValue: 0,
        endValue: 10000,
        values: getAllValues(),
        label: {
            format: 'fixedPoint',
            precision: 0
        }
    });
}

function applyCurrentSelection(args) {
    var quantityValues = [];
    if (args.ItemName == "gridDashboardItem1" & args.GetCurrentSelection().length != 0) {
        var clientData = webViewer.GetItemData("gridDashboardItem1");
        for (var i = 0; i < args.GetCurrentSelection().length; i++) {
            var currentTuple = args.GetCurrentSelection()[i],
                slice = clientData.GetSlice(currentTuple.GetAxisPoint()),
                quantity = (slice.GetMeasureValue(clientData.GetMeasures()[0].Id)).GetValue();
            quantityValues.push(quantity);
        }
    } else {
        quantityValues = getAllValues();
    }
    $('#barGauge').data("dxBarGauge").values(quantityValues);
}

function getAllValues() {
    var quantityValues = [],
        clientData = webViewer.GetItemData("gridDashboardItem1");
    for (var i = 0; i < clientData.GetAxis(defaultAxis).GetPoints().length; i++) {
        var slice = clientData.GetSlice(clientData.GetAxis(defaultAxis).GetPoints()[i]),
            quantity = (slice.GetMeasureValue(clientData.GetMeasures()[0].Id)).GetValue();
        quantityValues.push(quantity);
    }
    return quantityValues;
}

WebForm1.aspx (C#)

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="WebForm1.aspx.cs" 
    Inherits="ASPxDashboard_CustomVisualInteractivity.WebForm1" %>

<%@ Register Assembly="DevExpress.Dashboard.v17.1.Web, Version=17.1.1.0, Culture=neutral, PublicKeyToken=b88d1754d700e49a" 
    Namespace="DevExpress.DashboardWeb" TagPrefix="dx" %>

<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title></title>

</head>
<body>
    <form id="form1" runat="server">
    <div style="display: inline-block; float: left;">
        <dx:ASPxDashboard ID="ASPxDashboard1" runat="server" Height="600px" Width="800px"
            WorkingMode="Viewer"          
            ClientInstanceName="webViewer" 
            ClientSideEvents-DashboardEndUpdate="function() { createControls(); }"
            ClientSideEvents-ItemSelectionChanged="function(s, e) { applyCurrentSelection(e); }" 
            ClientSideEvents-ItemVisualInteractivity = "function(s, e) { addCustomInteractivity(e); }">
        </dx:ASPxDashboard>
    </div>
    <div id="barGauge" style="display: inline-block; float: left; width: 600px; height: 600px;"></div>
    </form>
</body>
</html>
<script type="text/javascript" src="<%= Page.ResolveClientUrl("~/Scripts/CustomInteractivity.js") %>"></script>

WebForm1.aspx.cs

using DevExpress.DashboardWeb;
using System;

namespace ASPxDashboard_CustomVisualInteractivity
{
    public partial class WebForm1 : System.Web.UI.Page
    {
        protected void Page_Load(object sender, EventArgs e)
        {
            ASPxDashboard1.SetDashboardStorage(new DashboardFileStorage(Server.MapPath("App_Data/Dashboards")));
        }
    }
}

WebForm1.aspx.vb

Imports DevExpress.DashboardWeb
Imports System

Namespace ASPxDashboard_CustomVisualInteractivity
    Partial Public Class WebForm1
        Inherits System.Web.UI.Page

        Protected Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs)
            ASPxDashboard1.SetDashboardStorage(New DashboardFileStorage(Server.MapPath("App_Data/Dashboards")))
        End Sub
    End Class
End Namespace

WebForm1.aspx (VB.NET)

<%@ Page Language="vb" AutoEventWireup="true" CodeBehind="WebForm1.aspx.vb" 
    Inherits="ASPxDashboard_CustomVisualInteractivity.WebForm1" %>

<%@ Register Assembly="DevExpress.Dashboard.v17.1.Web, Version=17.1.1.0, Culture=neutral, PublicKeyToken=b88d1754d700e49a" 
    Namespace="DevExpress.DashboardWeb" TagPrefix="dx" %>

<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title></title>

</head>
<body>
    <form id="form1" runat="server">
    <div style="display: inline-block; float: left;">
        <dx:ASPxDashboard ID="ASPxDashboard1" runat="server" Height="600px" Width="800px"
            WorkingMode="Viewer"          
            ClientInstanceName="webViewer" 
            ClientSideEvents-DashboardEndUpdate="function() { createControls(); }"
            ClientSideEvents-ItemSelectionChanged="function(s, e) { applyCurrentSelection(e); }" 
            ClientSideEvents-ItemVisualInteractivity = "function(s, e) { addCustomInteractivity(e); }">
        </dx:ASPxDashboard>
    </div>
    <div id="barGauge" style="display: inline-block; float: left; width: 600px; height: 600px;"></div>
    </form>
</body>
</html>
<script type="text/javascript" src="<%=Page.ResolveClientUrl("~/Scripts/CustomInteractivity.js")%>"></script>

Inherited Members

constructor

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.

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.

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.

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.

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.

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.

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.

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.