The requested page is not available for the requested platform. You are viewing the content for Default platform.
All docs
V19.1
19.1
18.2
The page you are viewing does not exist in version 18.2. This link will take you to the root page.
18.1
The page you are viewing does not exist in version 18.1. This link will take you to the root page.
17.2
The page you are viewing does not exist in version 17.2. This link will take you to the root page.

ASPxClientDashboard Class

A client-side equivalent of the ASPxDashboard control.

Declaration

declare class ASPxClientDashboard extends ASPxClientControl

Remarks

To learn more, see Client-Side Functionality.

Inheritance

Methods

CanClearMasterFilter(itemName) Method

Returns whether the specified master filter can be cleared in the current state.

Declaration

CanClearMasterFilter(itemName: string): boolean

Parameters

Name Type Description
itemName string

A string that specifies the component name of the master filter item.

Returns

Type Description
boolean

true, if the specified master filter can be cleared in the current state; otherwise, false.

Remarks

To clear the specified master filter item, use the ASPxClientDashboard.ClearMasterFilter method.

Examples

The following example demonstrates how to apply master filtering in the Web Dashboard on the client side.

In this example, the ASPxClientDashboard.SetMasterFilter method is used to select required rows in the Grid dashboard item while the ASPxClientDashboard.SetRange method is called to select the required range in the Range Filter dashboard item. These methods are called in the onClick event handler of the dxButton.

Imports System
Imports System.Collections.Generic
Imports System.Linq
Imports System.Web
Imports System.Web.UI
Imports System.Web.UI.WebControls

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

        Protected Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs)
            ASPxDashboard1.DashboardXmlPath = Server.MapPath("App_Data/Dashboard.xml")
        End Sub
    End Class
End Namespace
See Also

CanPerformDrillDown(itemName) Method

Returns whether drill down is possible in the current state of the specified dashboard item.

Declaration

CanPerformDrillDown(itemName: string): boolean

Parameters

Name Type Description
itemName string

A string that specifies the component name of the dashboard item.

Returns

Type Description
boolean

true, if drill down is possible in the current state of the specified dashboard item; otherwise, false.

See Also

CanPerformDrillUp(itemName) Method

Returns whether drill up is possible in the current state of the specified dashboard item.

Declaration

CanPerformDrillUp(itemName: string): boolean

Parameters

Name Type Description
itemName string

A string that specifies the component name of the dashboard item.

Returns

Type Description
boolean

true, if drill up is possible in the current state of the specified dashboard item; otherwise, false.

See Also

CanSetMasterFilter(itemName) Method

Returns whether master filtering can be applied in the current state of the specified master filter item.

Declaration

CanSetMasterFilter(itemName: string): boolean

Parameters

Name Type Description
itemName string

A string that specifies the component name of the master filter item.

Returns

Type Description
boolean

true, if master filtering can be applied in the current state of the specified master filter item; otherwise, false.

Examples

The following example demonstrates how to apply master filtering in the Web Dashboard on the client side.

In this example, the ASPxClientDashboard.SetMasterFilter method is used to select required rows in the Grid dashboard item while the ASPxClientDashboard.SetRange method is called to select the required range in the Range Filter dashboard item. These methods are called in the onClick event handler of the dxButton.

Imports System
Imports System.Collections.Generic
Imports System.Linq
Imports System.Web
Imports System.Web.UI
Imports System.Web.UI.WebControls

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

        Protected Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs)
            ASPxDashboard1.DashboardXmlPath = Server.MapPath("App_Data/Dashboard.xml")
        End Sub
    End Class
End Namespace
See Also

ClearMasterFilter(itemName) Method

Clears the specified master filter item.

Declaration

ClearMasterFilter(itemName: string): void

Parameters

Name Type Description
itemName string

A String that specifies the component name of the master filter item.

Examples

The following example demonstrates how to apply master filtering in the Web Dashboard on the client side.

In this example, the ASPxClientDashboard.SetMasterFilter method is used to select required rows in the Grid dashboard item while the ASPxClientDashboard.SetRange method is called to select the required range in the Range Filter dashboard item. These methods are called in the onClick event handler of the dxButton.

Imports System
Imports System.Collections.Generic
Imports System.Linq
Imports System.Web
Imports System.Web.UI
Imports System.Web.UI.WebControls

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

        Protected Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs)
            ASPxDashboard1.DashboardXmlPath = Server.MapPath("App_Data/Dashboard.xml")
        End Sub
    End Class
End Namespace
See Also

ExportDashboardItemToExcel(itemName) Method

Exports a dashboard item to an Excel file and writes it to the Response.

Declaration

ExportDashboardItemToExcel(itemName: string, options?: DashboardExcelExportOptions | ASPxClientDashboardExportOptions, fileName?: string): void

Parameters

Name Type Description
itemName string

A string that is the component name of the dashboard item to be exported.

Optional Parameters

Name Type Default Description
options DashboardExcelExportOptions | ASPxClientDashboardExportOptions null
fileName string null
See Also

ExportDashboardItemToImage(itemName) Method

Exports a dashboard item to an Image file and writes it to the Response.

Declaration

ExportDashboardItemToImage(itemName: string, options?: DashboardImageExportOptions | ASPxClientDashboardExportOptions, fileName?: string): void

Parameters

Name Type Description
itemName string

A string that is the component name of the dashboard item to be exported.

Optional Parameters

Name Type Default Description
options DashboardImageExportOptions | ASPxClientDashboardExportOptions null
fileName string null
See Also

ExportDashboardItemToPdf(itemName) Method

Exports a dashboard item to a PDF file and writes it to the Response.

Declaration

ExportDashboardItemToPdf(itemName: string, options?: DashboardPdfExportOptions | ASPxClientDashboardExportOptions, fileName?: string): void

Parameters

Name Type Description
itemName string

A string that is the component name of the dashboard item to be exported.

Optional Parameters

Name Type Default Description
options DashboardPdfExportOptions | ASPxClientDashboardExportOptions null
fileName string null
See Also

ExportToExcel Method

Exports dashboard data to the specified file in Excel format.

Declaration

ExportToExcel(options?: DashboardExcelExportOptions, fileName?: string): void

Optional Parameters

Name Type Default Description
options DashboardExcelExportOptions null
fileName string null

ExportToImage Method

Exports a dashboard to an Image file and writes it to the Response.

Declaration

ExportToImage(options?: DashboardImageExportOptions | ASPxClientDashboardExportOptions, fileName?: string): void

Optional Parameters

Name Type Default Description
options DashboardImageExportOptions | ASPxClientDashboardExportOptions null
fileName string null
See Also

ExportToPdf Method

Exports a dashboard to a PDF file and writes it to the Response.

Declaration

ExportToPdf(options?: DashboardPdfExportOptions | ASPxClientDashboardExportOptions, fileName?: string): void

Optional Parameters

Name Type Default Description
options DashboardPdfExportOptions | ASPxClientDashboardExportOptions null
fileName string null
See Also

GetAvailableDrillDownValues(itemName) Method

Returns axis point tuples identifying elements that can be used to perform drill-down in the specified dashboard item.

Declaration

GetAvailableDrillDownValues(itemName: string): ASPxClientDashboardItemDataAxisPointTuple[]

Parameters

Name Type Description
itemName string

A String that is the component name of the dashboard item.

Returns

Type Description
ASPxClientDashboardItemDataAxisPointTuple[]

An array of ASPxClientDashboardItemDataAxisPointTuple objects identifying elements that can be used to perform drill-down in the specified dashboard item.

Examples

The following example demonstrates how to perform a drill-down in ASPxDashboard on the client side.

In this example, the ASPxClientDashboard.PerformDrillDown method is used to perform a drill-down for a specified row in a Grid dashboard item. The dxSelectBox widget contains categories for which a drill-down can be performed. These categories are obtained using the ASPxClientDashboard.GetAvailableDrillDownValues method. Select a required category and click the Perform Drill-Down button to perform a drill-down by the selected category.

When the Grid displays a list of products (the bottom-most detail level), you can only perform a drill-up action that returns you to the top detail level. The ASPxClientDashboard.PerformDrillUp method is called to do this.

Dim access97Params As New Access97ConnectionParameters()
access97Params.FileName = "..\..\Data\nwind.mdb"

Dim sqlDataSource As New DashboardSqlDataSource("SQL Data Source 1", access97Params)
Dim selectQuery As SelectQuery = SelectQueryFluentBuilder.AddTable("SalesPerson"). _
    SelectColumns("CategoryName", "Sales Person", "OrderDate", "Extended Price").Build("Query 1")
sqlDataSource.Queries.Add(selectQuery)
sqlDataSource.Fill()

dashboardDesigner1.Dashboard.DataSources.Add(sqlDataSource)
See Also

GetAvailableFilterValues(itemName) Method

Returns axis point tuples identifying elements that can be selected in the current state of the master filter item.

Declaration

GetAvailableFilterValues(itemName: string): ASPxClientDashboardItemDataAxisPointTuple[]

Parameters

Name Type Description
itemName string

A String that is the component name of the master filter item.

Returns

Type Description
ASPxClientDashboardItemDataAxisPointTuple[]

An array of ASPxClientDashboardItemDataAxisPointTuple objects identifying elements that can be selected in the current state of the master filter item.

See Also

GetAvailablePredefinedRanges(itemName) Method

Returns names of the predefined ranges available for the specified Range Filter.

Declaration

GetAvailablePredefinedRanges(itemName: string): string[]

Parameters

Name Type Description
itemName string

A string value that specifies the component name of the Range Filter dashboard item.

Returns

Type Description
string[]

An array of string values that are names of the available predefined ranges.

Remarks

Use the GetAvailablePredefinedRanges method after the Range Filter has loaded data. When the Range Filter has no data to display, the GetAvailablePredefinedRanges method returns null.

GetCurrentDrillDownValues(itemName) Method

Returns the axis point tuple identifying the current drill-down state.

Declaration

GetCurrentDrillDownValues(itemName: string): ASPxClientDashboardItemDataAxisPointTuple

Parameters

Name Type Description
itemName string

A String that is the component name of the dashboard item.

Returns

Type Description
ASPxClientDashboardItemDataAxisPointTuple

An ASPxClientDashboardItemDataAxisPointTuple object representing a set of axis points.

See Also

GetCurrentFilterValues(itemName) Method

Returns axis point tuples identifying currently selected elements in the master filter item.

Declaration

GetCurrentFilterValues(itemName: string): ASPxClientDashboardItemDataAxisPointTuple[]

Parameters

Name Type Description
itemName string

A String that is the component name of the master filter item.

Returns

Type Description
ASPxClientDashboardItemDataAxisPointTuple[]

An array of ASPxClientDashboardItemDataAxisPointTuple objects identifying elements that can be selected in the current state of the master filter item.

See Also

GetCurrentPredefinedRange(itemName) Method

Returns the name of the currently selected predefined range.

Declaration

GetCurrentPredefinedRange(itemName: string): string

Parameters

Name Type Description
itemName string

A string value that specifies the component name of the Range Filter or Date Filter dashboard item.

Returns

Type Description
string

A string value that is the name of the currently selected predefined range.

Remarks

Use the GetCurrentPredefinedRange method after the dashboard item loads data. When the Range Filter or Date Filter has no data to display, the GetCurrentPredefinedRange method returns null.

GetCurrentRange(itemName) Method

Returns the currently selected range in the specified Range Filter or Date Filter dashboard item.

Declaration

GetCurrentRange(itemName: string): ASPxClientDashboardRangeFilterSelection

Parameters

Name Type Description
itemName string

A String value that specifies the component name of the Range Filter or Date Filter dashboard item.

Returns

Type Description
ASPxClientDashboardRangeFilterSelection

A ASPxClientDashboardRangeFilterSelection object that is the selected range.

Remarks

Use the GetCurrentRange method after the dashboard item loads data. When the Range Filter or Date Filter has no data to display, the GetCurrentRange method returns null.

See Also

GetCurrentSelection(itemName) Method

Returns currently selected elements in the master filter item.

Declaration

GetCurrentSelection(itemName: string): ASPxClientDashboardItemDataAxisPointTuple[]

Parameters

Name Type Description
itemName string

A String that specifies a component name of the master filter item.

Returns

Type Description
ASPxClientDashboardItemDataAxisPointTuple[]

An array of ASPxClientDashboardItemDataAxisPointTuple objects that identify currently selected elements.

See Also

GetDashboardControl Method

Gets the DashboardControl object that is the client-side part of the Web Dashboard.

Declaration

GetDashboardControl(): any

Returns

Type Description
any

A DashboardControl object that is the client-side part of the Web Dashboard.

See Also

GetDashboardId Method

Gets the identifier of the dashboard that is displayed in the ASPxClientDashboard.

Declaration

GetDashboardId(): string

Returns

Type Description
string

A String value that is the identifier of the dashboard displayed in the ASPxClientDashboard.

Remarks

You can obtain the state of the displayed dashboard using the ASPxClientDashboard.GetDashboardState method.

GetDashboardState Method

Gets the current dashboard state.

Declaration

GetDashboardState(): string

Returns

Type Description
string

A string value that identifies the state of the dashboard displayed in the ASPxClientDashboard.

Remarks

To learn more about a dashboard state, see Manage Dashboard State.

See Also

GetEntireRange(itemName) Method

Returns the visible range for the specified Range Filter or Date Filter dashboard item.

Declaration

GetEntireRange(itemName: string): ASPxClientDashboardRangeFilterSelection

Parameters

Name Type Description
itemName string

A String value that specifies the component name of the Range Filter or Date Filter dashboard item.

Returns

Type Description
ASPxClientDashboardRangeFilterSelection

A ASPxClientDashboardRangeFilterSelection object that is the visible range.

Remarks

Use the GetEntireRange method after the dashboard item loads data. When the Range Filter or Date Filter has no data to display, the GetEntireRange method returns null.

See Also

GetExcelExportOptions Method

Allows you to obtain options related to exporting a dashboard/dashboard item to the Excel format.

Declaration

GetExcelExportOptions(): DashboardExcelExportOptions

Returns

Type Description
DashboardExcelExportOptions

A DashboardExcelExportOptions object containing options related to exporting a dashboard item to the Excel format.

See Also

GetExportOptions Method

Obsolete. Returns settings that specify parameters affecting how the dashboard is exported.

Declaration

GetExportOptions(): ASPxClientDashboardExportOptions

Returns

Type Description
ASPxClientDashboardExportOptions

A ASPxClientDashboardExportOptions object containing settings that specify parameters affecting how the dashboard is exported.

See Also

GetImageExportOptions Method

Allows you to obtain options related to exporting a dashboard/dashboard item to an image.

Declaration

GetImageExportOptions(): DashboardImageExportOptions

Returns

Type Description
DashboardImageExportOptions

A DashboardImageExportOptions object containing options related to exporting a dashboard/dashboard item to an image.

See Also

GetItemData(itemName) Method

Returns the client data for the specified dashboard item.

Declaration

GetItemData(itemName: string): ASPxClientDashboardItemData

Parameters

Name Type Description
itemName string

A string that specifies the component name of the dashboard item.

Returns

Type Description
ASPxClientDashboardItemData

An ASPxClientDashboardItemData object that represents multidimensional data visualized in the dashboard item.

Examples

The following example demonstrates how to obtain client data corresponding to a particular visual element using ASPxDashboard's client-side API. In this example, the ASPxClientDashboard.ItemClick event is handled to obtain client data and invoke the dxPopup widget with the child dxChart.

In the event handler, the ASPxClientDashboardItemClickEventArgs.GetData method is called to obtain dashboard item's client data. The ASPxClientDashboardItemClickEventArgs.GetAxisPoint method returns the axis point corresponding to the clicked card while the ASPxClientDashboardItemData.GetSlice method returns the slice of client data by this axis point. To obtain axis points belonging to the "Sparkline" data axis, the ASPxClientDashboardItemDataAxis.GetPoints method is used. Corresponding actual/target values are obtained using the ASPxClientDashboardItemData.GetDeltaValue method.

The dxChart is used to display the detailed chart showing a variation of actual/target values over time.

function getClientData(args) {
    if (args.ItemName == "cardDashboardItem1") {
        var clientData = [],
            clientDataTable = [],
            clickedItemData,
            delta;
        var sparklineAxis = DashboardDataAxisNames.SparklineAxis,
            defaultAxis = DashboardDataAxisNames.Default;

        clientData = args.GetData();
        clickedPoint = args.GetAxisPoint(defaultAxis);
        clickedItemData = clientData.GetSlice(clickedPoint);
        delta = args.GetDeltas()[0];

        for (var i = 0; i < clickedItemData.GetAxis(sparklineAxis).GetPoints().length; i++) {
            var dataTableRow = {},
            axisPoint = clickedItemData.GetSlice(clickedItemData.GetAxis(sparklineAxis).GetPoints()[i]);

            dataTableRow["Argument"] = clickedItemData.GetAxis(sparklineAxis).GetPoints()[i].GetValue();
            if (axisPoint.GetDeltaValue(delta.Id).GetActualValue().GetValue() != null &&
                axisPoint.GetDeltaValue(delta.Id).GetTargetValue().GetValue() != null) {
                dataTableRow["Actual"] = axisPoint.GetDeltaValue(delta.Id).GetActualValue().GetValue();
                dataTableRow["Target"] = axisPoint.GetDeltaValue(delta.Id).GetTargetValue().GetValue();
            }
            else {
                dataTableRow["Actual"] = 0;
                dataTableRow["Target"] = 0;
            }
            clientDataTable.push(dataTableRow);
        }

        var $chart = $('<div/>');
        $chart.dxChart({
            height: 500,
            dataSource: clientDataTable,
            series: [{
                valueField: 'Actual', name: 'Actual'
            }, {
                valueField: 'Target', name: 'Target'
            }
            ],
            commonSeriesSettings: {
                type: 'splineArea',
                argumentField: 'Argument',
                ignoreEmptyPoints: true
            },
            argumentAxis: {
                showZero: false,
                type: 'discrete'
            },
            valueAxis: {
                showZero: false,
                type: 'continuous',
                label: { format: 'currency' }
            }
        });

        var popup = $("#myPopup").data("dxPopup");
        popup.option('title', clickedPoint.GetValue() + " - Details");
        $popupContent = popup.content();
        $popupContent.empty();
        $popupContent.append($chart);
        popup.show();
    };
}

function initPopup() {
    $("#myPopup").dxPopup({
        width: 800, height: 600,
        title: "Details",
        showCloseButton: true
    });
}
See Also

GetMaximizedDashboardItemName Method

Returns the name of the maximized dashboard item.

Declaration

GetMaximizedDashboardItemName(): string

Returns

Type Description
string

A String value that is a maximized dashboard item's name.

Remarks

To maximize an item:

To restore an item's size:

Note

Maximize or restore actions re-create the dashboard item and fire all events related to the item life cycle (ItemWidgetCreated and ItemWidgetUpdated).

See Also

GetParameters Method

Returns dashboard parameter settings and metadata.

Declaration

GetParameters(): ASPxClientDashboardParameters

Returns

Type Description
ASPxClientDashboardParameters

A ASPxClientDashboardParameters object that is a collection of ASPxClientDashboardParameter objects.

Remarks

ASPxClientDashboardParameter class objects returned by the GetParameters method allow you to obtain parameter settings such as the parameter type (the ASPxClientDashboardParameter.GetType method), the default parameter value (the ASPxClientDashboardParameter.GetDefaultValue method), the parameter name (the ASPxClientDashboardParameter.GetName method), etc.

The ASPxClientDashboardParameter.GetValues method returns possible parameter values. Use the ASPxClientDashboardParameter.SetValue method to specify the current parameter value.

Examples

This example demonstrates how to change dashboard parameter values in the ASPxDashboard control on the client side using the ASPxClientDashboard.GetParameters method.

In this example, parameter values are specified using the ASPxClientDashboardParameter.SetValue method. The ASPxClientDashboard.ShowParametersDialog method is used to invoke the Dashboard Parameters dialog that displays applied parameter values.

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

<%@ Register Assembly="DevExpress.Dashboard.v17.1.Web, Version=17.1.2.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 id="setParameterValuesButton" style="float: left; margin-left: 150px;"></div>
    <div id="showParametersForm" style="float: left; margin-left: 100px;"></div>

    <div style="position: absolute; left: 0; right: 0; top:50px; bottom:0;">
        <dx:ASPxDashboard ID="ASPxDashboard1" runat="server" 
            WorkingMode="Viewer" 
            ClientInstanceName="webViewer"
            ClientSideEvents-DashboardEndUpdate="function() { setParameterValues(); }"
            Width="100%" Height="100%">
        </dx:ASPxDashboard>
    </div>
    </form>
</body>
</html>
<script type="text/javascript" src="<%= Page.ResolveClientUrl("~/Scripts/ParameterValues.js") %>"></script>
See Also

GetPdfExportOptions Method

Allows you to obtain options related to exporting a dashboard/dashboard item to the PDF format.

Declaration

GetPdfExportOptions(): DashboardPdfExportOptions

Returns

Type Description
DashboardPdfExportOptions

A DashboardPdfExportOptions object containing options related to exporting a dashboard/dashboard item to the PDF format.

See Also

GetSelectedTabPage(tabContainerName) Method

Gets the selected page in the specified tab container.

Declaration

GetSelectedTabPage(tabContainerName: string): string

Parameters

Name Type Description
tabContainerName string

A String object that is the tab container's componentName property value.

Returns

Type Description
string

A String object that is the tab page's componentName property value.

GetSelectedTabPageIndex(tabContainerName) Method

Gets the index of the selected page in the specified tab container.

Declaration

GetSelectedTabPageIndex(tabContainerName: string): number

Parameters

Name Type Description
tabContainerName string

A String object that is the tab container's componentName property value.

Returns

Type Description
number

A Int32 object that is the tab page's index.

GetWorkingMode Method

Gets the current working mode of the Web Dashboard.

Declaration

GetWorkingMode(): string

Returns

Type Description
string

A String value that is the working mode of the Web Dashboard.

Remarks

You can switch between working modes of the Web Dashboard on the client side using the ASPxClientDashboard.SwitchToViewer/ASPxClientDashboard.SwitchToDesigner methods.

To specify the default working mode on the server side, use the ASPxDashboard.WorkingMode property.

HideExportDialog Method

Hides the dialog that allows end-users to export the dashboard/dashboard item.

Declaration

HideExportDialog(): void
See Also

HideParametersDialog Method

Closes the Dashboard Parameters dialog.

Declaration

HideParametersDialog(): void
See Also

IsDesignMode Method

Declaration

IsDesignMode(): boolean

Returns

Type Description
boolean

LoadDashboard(dashboardId) Method

Loads a dashboard with the specified identifier from the dashboard storage.

Declaration

LoadDashboard(dashboardId: string): void

Parameters

Name Type Description
dashboardId string

A string value that specifies the dashboard identifier.

Remarks

Use the ASPxClientDashboard.SaveDashboard method to save the current dashboard.

Note

To learn more about different methods of loading a dashboard, see Loading a Dashboard.

MaximizeDashboardItem(itemName) Method

Expands the specified dashboard item to the entire dashboard size to examine data in greater detail.

Declaration

MaximizeDashboardItem(itemName: string): void

Parameters

Name Type Description
itemName string

A String object that is the dashboard item component name.

Remarks

To maximize an item:

To restore an item's size:

Note

Maximize or restore actions re-create the dashboard item and fire all events related to the item life cycle (ItemWidgetCreated and ItemWidgetUpdated).

See Also

PerformDataCallback(parameter, onCallback) Method

Sends a callback to the server and generates the server-side ASPxDashboard.CustomDataCallback event, passing it the specified argument.

Declaration

PerformDataCallback(parameter: string, onCallback: ASPxClientDataCallback): void

Parameters

Name Type Description
parameter string

A string value that represents any information that needs to be sent to the server-side ASPxDashboard.CustomDataCallback event.

onCallback ASPxClientDataCallback

An ASPxClientDataCallback object that represents the JavaScript function which receives the callback data as a parameter.

Remarks

Use the PerformDataCallback method if you need to asynchronously go to the server and perform some server-side processing using AJAX-based callback technology. You can pass the required information to be collected on the client side as a string of arguments (for instance, in the "Name = Value;" form) using the PerformDataCallback method's parameter parameter.

The PerformDataCallback method posts back to the server using the callback technology and generates a server-side ASPxDashboard.CustomDataCallback event. So, the necessary server-side actions can be performed in the event's handler based upon the values of the arguments obtained by parsing the passed information string.

Note

The ASPxClientDashboard.BeginCallback and ASPxClientDashboard.EndCallback client events can also be used to perform necessary client actions before and after callback processing.

See Also

PerformDrillDown(itemName, value) Method

Performs a drill-down into the required element by its value.

Declaration

PerformDrillDown(itemName: string, value: any | ASPxClientDashboardItemDataAxisPointTuple): void

Parameters

Name Type Description
itemName string

A String that species the component name of the dashboard item.

value any | ASPxClientDashboardItemDataAxisPointTuple

A value that will be used to perform a drill-down for the required element.

See Also

PerformDrillUp(itemName) Method

Performs a drill-up for the specified dashboard item.

Declaration

PerformDrillUp(itemName: string): void

Parameters

Name Type Description
itemName string

A String that specifies the component name of the dashboard item.

See Also

Refresh Method

Refreshes an entire dashboard displayed in the Web Dashboard control.

Declaration

Refresh(itemName?: string | string[]): void

Optional Parameters

Name Type Default Description
itemName string | string[] null

Remarks

The Refresh method requests the actual state of the dashboard/dashboard item from the web server. For instance, the call of this method returns the actual data from the web or database server.

ReloadData Method

Reloads data in the data sources.

Declaration

ReloadData(): void

Remarks

When the client data processing mode is used, Web Dashboard caches data on the server side to improve data loading performance. When you call the ReloadData method on the client side, a callback is sent to the server. The server-side's cache for all data sources is reset and all dashboard items request new data from data sources.

Important

Since multiple users can simultaneously open the dashboard and share the same server-side cache, execution of the reloadData method by one of the clients forces the server cache to be reset. All users get new data on the next request to the server.

See Also

RequestUnderlyingData(itemName, args, onCompleted) Method

Requests underlying data for the specified dashboard item.

Declaration

RequestUnderlyingData(itemName: string, args: ASPxClientDashboardItemRequestUnderlyingDataParameters, onCompleted: ASPxClientDashboardItemRequestUnderlyingDataCompleted): void

Parameters

Name Type Description
itemName string

A string that specifies the component name of the dashboard item.

args ASPxClientDashboardItemRequestUnderlyingDataParameters

A ASPxClientDashboardItemRequestUnderlyingDataParameters object containing parameters used to obtain the underlying data.

onCompleted ASPxClientDashboardItemRequestUnderlyingDataCompleted

A ASPxClientDashboardItemRequestUnderlyingDataCompleted object that references a method executed after the request is completed.

Remarks

Note that the RequestUnderlyingData method does not return data for calculated fields containing the Aggr function.

The following code snippet shows how to set the method's parameters to obtain underlying data:

var requestParameters = {
    DataMembers: ['ProductName', 'OrderID']
};
Dashboard.RequestUnderlyingData("gaugeDashboardItem1", requestParameters, function(data) {
    var dataM = data.GetDataMembers();
    for(var i = 0; i < data.GetRowCount(); i++) {
        var dataTableRow = {};
        $.each(dataM, function(_, dataMember) {
            dataTableRow[dataMember] = data.GetRowValue(i, dataMember);
        });
        underlyingData.push(dataTableRow);
    }
})
See Also

RestoreDashboardItem Method

Restores the item size if an item is expanded to the entire dashboard size (maximized).

Declaration

RestoreDashboardItem(): void

Remarks

To maximize an item:

To restore an item's size:

Note

The dashboard item is re-created when you maximize / restore the item. All events connected with dashboard item life cycle (such as ItemWidgetCreated, ItemWidgetUpdated, etc.) are fired again.

SaveDashboard Method

Saves a current dashboard to the dashboard storage.

Declaration

SaveDashboard(): void

Remarks

Use the ASPxClientDashboard.LoadDashboard method to load a dashboard with the specified identifier.

SetDashboardState(dashboardState) Method

Applies the dashboard state to the loaded dashboard.

Declaration

SetDashboardState(dashboardState: any | string): void

Parameters

Name Type Description
dashboardState any | string

A JSON object that specifies the dashboard state.

Remarks

The DashboardState class includes states of individual dashboard items (the DashboardState.Items property) and currently selected parameter values (DashboardState.Parameters).

To learn more about a dashboard state, see Manage Dashboard State.

SetExcelExportOptions(options) Method

Allows you to specify options related to exporting a dashboard/dashboard item to the Excel format.

Declaration

SetExcelExportOptions(options: DashboardExcelExportOptions): void

Parameters

Name Type Description
options DashboardExcelExportOptions

A DashboardExcelExportOptions object containing options related to exporting a dashboard item to the Excel format.

See Also

SetExportOptions(options) Method

Obsolete. Specifies settings that configures dashboard export parameters.

Declaration

SetExportOptions(options: ASPxClientDashboardExportOptions): void

Parameters

Name Type Description
options ASPxClientDashboardExportOptions

A ASPxClientDashboardExportOptions object containing settings that specify parameters affecting how the dashboard is exported.

See Also

SetImageExportOptions(options) Method

Allows you to specify options related to exporting a dashboard/dashboard item to an image.

Declaration

SetImageExportOptions(options: DashboardImageExportOptions): void

Parameters

Name Type Description
options DashboardImageExportOptions

A DashboardImageExportOptions object containing options related to exporting a dashboard/dashboard item to an image.

See Also

SetMasterFilter(itemName, values) Method

Selects required elements by their values in the specified master filter item.

Declaration

SetMasterFilter(itemName: string, values: object[][] | ASPxClientDashboardItemDataAxisPointTuple[]): void

Parameters

Name Type Description
itemName string

A String that specifies the component name of the master filter item.

values object[][] | ASPxClientDashboardItemDataAxisPointTuple[]

Values that will be used to select elements in the master filter item.

Remarks

Only dimension fields can be a part of the master filter values. To select a row, create a filter with unique values that unambiguously define this row.

Examples

The following example demonstrates how to apply master filtering in the Web Dashboard on the client side.

In this example, the ASPxClientDashboard.SetMasterFilter method is used to select required rows in the Grid dashboard item while the ASPxClientDashboard.SetRange method is called to select the required range in the Range Filter dashboard item. These methods are called in the onClick event handler of the dxButton.

Imports System
Imports System.Collections.Generic
Imports System.Linq
Imports System.Web
Imports System.Web.UI
Imports System.Web.UI.WebControls

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

        Protected Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs)
            ASPxDashboard1.DashboardXmlPath = Server.MapPath("App_Data/Dashboard.xml")
        End Sub
    End Class
End Namespace
See Also

SetPdfExportOptions(options) Method

Allows you to specify options related to exporting a dashboard/dashboard item to the PDF format.

Declaration

SetPdfExportOptions(options: DashboardPdfExportOptions): void

Parameters

Name Type Description
options DashboardPdfExportOptions

A DashboardPdfExportOptions object containing options related to exporting a dashboard/dashboard item to the PDF format.

See Also

SetPredefinedRange(itemName, dateTimePeriodName) Method

Selects a predefined range in the Range Filter or Date Filter dashboard item.

Declaration

SetPredefinedRange(itemName: string, dateTimePeriodName: string): void

Parameters

Name Type Description
itemName string

A String value that specifies the component name of the Range Filter or Date Filter.

dateTimePeriodName string

A String value that specifies the predefined range name.

Remarks

Use the SetPredefinedRange method after the dashboard item loads data. When the Range Filter or Date Filter has no data to display, the SetPredefinedRange method returns null.

SetRange(itemName, range) Method

Selects the required range in the specified Range Filter or Date Filter dashboard item.

Declaration

SetRange(itemName: string, range: ASPxClientDashboardRangeFilterSelection): void

Parameters

Name Type Description
itemName string

A String that specifies the component name of the Range Filter or Date Filter dashboard item.

range ASPxClientDashboardRangeFilterSelection

A ASPxClientDashboardRangeFilterSelection object that specifies a range to be selected.

Remarks

Use the SetRange method after the dashboard item loads data. When the Range Filter or Date Filter has no data to display, the SetRange method returns null.

See Also

SetSelectedTabPage(tabPageName) Method

Selects the specified tab page by its component name.

Declaration

SetSelectedTabPage(tabPageName: string): void

Parameters

Name Type Description
tabPageName string

A String object that is the tab page's componentName property value.

SetSelectedTabPageIndex(tabContainerName, index) Method

Selects the specified tab page by its index in the specified tab container.

Declaration

SetSelectedTabPageIndex(tabContainerName: string, index: number): void

Parameters

Name Type Description
tabContainerName string

A String object that is the tab container's componentName property value.

index number

A Int32 object that is the tab page's index.

ShowExportDashboardDialog(format) Method

Invokes the dialog that allows end-users to export the entire dashboard to the specified format.

Declaration

ShowExportDashboardDialog(format: string): void

Parameters

Name Type Description
format string

A string value that specifies the format. For instance, you can use 'PDF', 'Image', or 'Excel'.

See Also

ShowExportDashboardItemDialog(itemComponentName, format) Method

Invokes the dialog that allows end-users to export the dashboard item to the specified format.

Declaration

ShowExportDashboardItemDialog(itemComponentName: string, format: string): void

Parameters

Name Type Description
itemComponentName string

A string value that specifies the component name of the dashboard item to export.

format string

A string value that specifies the format. For instance, you can use 'PDF, 'Image' or 'Excel'. Note that some items (i.e., TextBoxDashboardItem or ImageDashboardItem) do not support exporting to the 'Excel' format.

See Also

ShowParametersDialog Method

Invokes the Dashboard Parameters dialog.

Declaration

ShowParametersDialog(): void
See Also

SwitchToDesigner Method

Switches the ASPxClientDashboard to the designer mode.

Declaration

SwitchToDesigner(): void

Remarks

Use the ASPxClientDashboard.SwitchToViewer method to switch the ASPxClientDashboard to the viewer mode. You can obtain the current working mode using the ASPxClientDashboard.GetWorkingMode method.

SwitchToViewer Method

Switches the ASPxClientDashboard to the viewer mode.

Declaration

SwitchToViewer(): void

Remarks

Use the ASPxClientDashboard.SwitchToDesigner method to switch the ASPxClientDashboard to the designer mode. You can obtain the current working mode using the ASPxClientDashboard.GetWorkingMode method.

UpdateDashboardTitleToolbar Method

Declaration

UpdateDashboardTitleToolbar(): void

Remarks

The DashboardTitleToolbarUpdated event occurs before the dashboard title toolbar is updated. Use the UpdateDashboardTitleToolbar method to trigger the following event manually.

UpdateItemCaptionToolbar(itemName) Method

Fires the ItemCaptionToolbarUpdated event for the specified item.

Declaration

UpdateItemCaptionToolbar(itemName: string): void

Parameters

Name Type Description
itemName string

A dashboard item name for which the event is fired.

Remarks

The ItemCaptionToolbarUpdated event occurs before the dashboard item's caption toolbar is updated. Use the UpdateItemCaptionToolbar method to trigger the following event manually. If the itemName parameter is empty, the ItemCaptionToolbarUpdated event is fired for all dashboard items and groups.

Events

ActionAvailabilityChanged Event

Occurs after the available interactivity actions have changed for the specific dashboard item.

Declaration

ActionAvailabilityChanged: ASPxClientEvent<ASPxClientActionAvailabilityChangedEventHandler<ASPxClientDashboard>>

Event Data

The ActionAvailabilityChanged event handler receives an argument of the ASPxClientActionAvailabilityChangedEventArgs type. The following properties provide information specific to this event.

Property Description
ItemName Gets the component name of the dashboard item.

Examples

The following example demonstrates how to perform a drill-down in ASPxDashboard on the client side.

In this example, the ASPxClientDashboard.PerformDrillDown method is used to perform a drill-down for a specified row in a Grid dashboard item. The dxSelectBox widget contains categories for which a drill-down can be performed. These categories are obtained using the ASPxClientDashboard.GetAvailableDrillDownValues method. Select a required category and click the Perform Drill-Down button to perform a drill-down by the selected category.

When the Grid displays a list of products (the bottom-most detail level), you can only perform a drill-up action that returns you to the top detail level. The ASPxClientDashboard.PerformDrillUp method is called to do this.

Dim access97Params As New Access97ConnectionParameters()
access97Params.FileName = "..\..\Data\nwind.mdb"

Dim sqlDataSource As New DashboardSqlDataSource("SQL Data Source 1", access97Params)
Dim selectQuery As SelectQuery = SelectQueryFluentBuilder.AddTable("SalesPerson"). _
    SelectColumns("CategoryName", "Sales Person", "OrderDate", "Extended Price").Build("Query 1")
sqlDataSource.Queries.Add(selectQuery)
sqlDataSource.Fill()

dashboardDesigner1.Dashboard.DataSources.Add(sqlDataSource)

BeforeRender Event

Occurs before any element in the Web Dashboard control has been rendered.

Declaration

BeforeRender: ASPxClientEvent<ASPxClientDashboardBeforeRenderEventHandler<ASPxClientDashboard>>

Event Data

The BeforeRender event handler receives an argument of the ASPxClientEventArgs type.

Remarks

The BeforeRender event allows you to perform client-side customization of the Web Dashboard control before the control and its elements have been rendered. Raise the BeforeRender event and use the ASPxClientDashboard.GetDashboardControl method to get access to the HTML JavaScript dashboard control and its API:

<dx:ASPxDashboard ID="ASPxDashboard1" runat="server">
    <ClientSideEvents BeforeRender="onBeforeRender"/>
</dx:ASPxDashboard>

BeginCallback Event

Occurs when a callback for server-side processing is initiated.

Declaration

BeginCallback: ASPxClientEvent<ASPxClientBeginCallbackEventHandler<ASPxClientDashboard>>

Event Data

The BeginCallback event handler receives an argument of the ASPxClientBeginCallbackEventArgs type. The following properties provide information specific to this event.

Property Description
command Gets a command name that identifies which client action forced a callback to occur.

Remarks

The BeginCallback and ASPxClientDashboard.EndCallback events can be used to perform specific client-side actions while a callback is being processed on the server side.

Note

Note that BeginCallback and ASPxClientDashboard.EndCallback do not work in ASP.NET MVC Dashboard.

See Also

CustomDataCallback Event

Fires when a round trip to the server has been initiated by a call to the client ASPxClientDashboard.PerformDataCallback method.

Declaration

CustomDataCallback: ASPxClientEvent<ASPxClientCustomDataCallbackEventHandler<ASPxClientDashboard>>

Event Data

The CustomDataCallback event handler receives an argument of the ASPxClientCustomDataCallbackEventArgs type. The following properties provide information specific to this event.

Property Description
result Gets a string that contains specific information (if any) that has been passed from the server to the client side for further processing, related to the CustomCallback event.

Remarks

The CustomDataCallback event allows any desired server-side processing to be performed, and any resulting required information to be passed to the client for further processing (if needed).

After the CustomDataCallback event has been processed on the server side, a result can be passed back to the client via the CallbackEventArgs.Result property. To receive the result on the client, handle the ASPxClientDashboard.CustomDataCallback event.

See Also

DashboardBeginUpdate Event

Occurs when a dashboard update is initiated.

Declaration

DashboardBeginUpdate: ASPxClientEvent<ASPxClientDashboardBeginUpdateEventHandler<ASPxClientDashboard>>

Event Data

The DashboardBeginUpdate event handler receives an argument of the ASPxClientDashboardBeginUpdateEventArgs type. The following properties provide information specific to this event.

Property Description
DashboardId Gets the identifier of the dashboard for which the event was raised.

Remarks

After the dashboard update is performed, the ASPxClientDashboard.DashboardEndUpdate event is fired.

See Also

DashboardChanged Event

The DashboardChanged client-side event is obsolete. Use the DashboardInitialized event instead.

Declaration

DashboardChanged: ASPxClientEvent<ASPxClientDashboardChangedEventHandler<ASPxClientDashboard>>

Event Data

The DashboardChanged event handler receives an argument of the ASPxClientDashboardChangedEventArgs type. The following properties provide information specific to this event.

Property Description
DashboardId Gets the identifier of a newly opened dashboard.

DashboardEndUpdate Event

Occurs after the dashboard update is performed.

Declaration

DashboardEndUpdate: ASPxClientEvent<ASPxClientDashboardEndUpdateEventHandler<ASPxClientDashboard>>

Event Data

The DashboardEndUpdate event handler receives an argument of the ASPxClientDashboardEndUpdateEventArgs type. The following properties provide information specific to this event.

Property Description
DashboardId Gets the identifier of the dashboard for which the event was raised.

Remarks

When the dashboard update is initiated, the ASPxClientDashboard.DashboardBeginUpdate event is fired.

See Also

DashboardInitialized Event

Occurs after the dashboard displayed in the control has been initialized.

Declaration

DashboardInitialized: ASPxClientEvent<ASPxClientDashboardInitializedEventHandler<ASPxClientDashboard>>

Event Data

The DashboardInitialized event handler receives an argument of the ASPxClientDashboardInitializedEventArgs type. The following properties provide information specific to this event.

Property Description
DashboardId Gets the dashboard's unique name.

Remarks

Use the DashboardId property to get a dashboard's unique name.

DashboardInitializing Event

Occurs before the dashboard displayed in the control has been initialized.

Declaration

DashboardInitializing: ASPxClientEvent<ASPxClientDashboardInitializingEventHandler<ASPxClientDashboard>>

Event Data

The DashboardInitializing event handler receives an argument of the ASPxClientDashboardInitializingEventArgs type. The following properties provide information specific to this event.

Property Description
Dashboard Gets a model of the dashboard displayed in the control.
DashboardId Gets a string value that is the dashboard identifier.
Ready Specifies a Promise object to observe when all actions of a certain type bound to the collection, queued or not, have finished.

DashboardStateChanged Event

Occurs after the current dashboard state in the ASPxClientDashboard is changed.

Declaration

DashboardStateChanged: ASPxClientEvent<ASPxClientDashboardStateChangedEventHandler<ASPxClientDashboard>>

Event Data

The DashboardStateChanged event handler receives an argument of the ASPxClientDashboardStateChangedEventArgs type. The following properties provide information specific to this event.

Property Description
DashboardState Gets the current state of the dashboard.

Remarks

To learn more about a dashboard state, see Manage Dashboard State.

Examples

The sample illustrates how to save the current ASPxDashboard state (such as master filter or parameter values) to cookies on the client side and restore this state on the server side. The following API is used in this example:

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

<%@ Register Assembly="DevExpress.Dashboard.v17.1.Web, Version=17.1.3.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="position:absolute; left:0; right:0; top:0; bottom:0;">
        <dx:ASPxDashboard ID="ASPxDashboard1" runat="server" 
            WorkingMode="ViewerOnly" 
            ClientInstanceName="webDashboard"
            IncludeDashboardIdToUrl="True"        
            DashboardStorageFolder="~/App_Data/Dashboards" 
            Height="100%" Width="100%" OnSetInitialDashboardState="ASPxDashboard1_SetInitialDashboardState">
            <ClientSideEvents DashboardStateChanged="
                function(s, e) {
                var cookies = e.DashboardState;
                ASPxClientUtils.SetCookie('ASPxDashboardState', cookies);
            }"></ClientSideEvents>
        </dx:ASPxDashboard>
    </div>
    </form>
</body>
</html>

DashboardTitleToolbarUpdated Event

Allows you to customize a dashboard title (for instance, add custom buttons, menus, etc.).

Declaration

DashboardTitleToolbarUpdated: ASPxClientEvent<ASPxClientDashboardTitleToolbarUpdatedEventHandler<ASPxClientDashboard>>

Event Data

The DashboardTitleToolbarUpdated event handler receives an argument of the ASPxClientDashboardTitleToolbarUpdatedEventArgs type. The following properties provide information specific to this event.

Property Description
Options Provides access to dashboard title options.

Remarks

You can handle the DashboardTitleToolbarUpdated event to customize the dashboard's title. For instance, you can add custom command buttons, create additional menus, add static texts, etc. The DashboardTitleToolbarOptions class contains options used to customize a dashboard title's elements (the ViewerToolbarItem objects).

The following code snippet shows how to add a custom button with a drop-down menu to the dashboard's title. This button belongs to the actionItems collection and is displayed on the right (like the Export To and Parameters buttons).

function onDashboardTitleToolbarUpdated(s, e) {
    e.Options.actionItems.push({
        text: 'Custom Menu',
        type: "menu",            
        menu: {
            type: 'list',
            items: ['first', 'second', 'third'],
            selectionMode: 'single',
            itemClick: function () {
                // ...
            }
        },
    })
}

Examples

The code snippet below shows how to add a custom command button to a dashboard title by handling ASPxClientDashboard.DashboardTitleToolbarUpdated. In this example, a custom 'Refresh' button with the specified SVG icon allows end-users to refresh the entire dashboard. Clicking this button calls the ASPxClientDashboard.Refresh method.

var refreshIcon = '<svg id="refreshIcon" ... /></svg>';

function onBeforeRender(s, e) {
    DevExpress.Dashboard.ResourceManager.registerIcon(refreshIcon);
    // ...
}

function onDashboardTitleToolbarUpdated(s, e) {
    e.Options.actionItems.unshift({
        type: "button",
        icon: "refreshIcon",
        hint: "Refresh Dashboard",
        click: function (element) {
            clientDashboardDesigner1.Refresh();
        }
    });
}

DynamicLookUpValuesLoaded Event

Occurs after parameter values provided using a Dynamic List are loaded.

Declaration

DynamicLookUpValuesLoaded: ASPxClientEvent<ASPxClientDynamicLookUpValuesLoadedEventHandler<ASPxClientDashboard>>

Event Data

The DynamicLookUpValuesLoaded event handler receives an argument of the ASPxClientDynamicLookUpValuesLoadedEventArgs type. The following properties provide information specific to this event.

Property Description
ParameterName Gets the dashboard parameter name whose values have been loaded.
See Also

EndCallback Event

Occurs on the client side after a callback's server-side processing has been completed.

Declaration

EndCallback: ASPxClientEvent<ASPxClientEndCallbackEventHandler<ASPxClientDashboard>>

Event Data

The EndCallback event handler receives an argument of the ASPxClientEndCallbackEventArgs type. The following properties provide information specific to this event.

Property Description
command Gets a command name that identifies which client action forced a callback to occur.

Remarks

The ASPxClientDashboard.BeginCallback and EndCallback events can be used to perform specific client-side actions while a callback is being processed on the server side.

Note

Note that ASPxClientDashboard.BeginCallback and EndCallback do not work in ASP.NET MVC Dashboard.

See Also

ItemBeforeWidgetDisposed Event

Allows you to access underlying UI/Data Visualization widgets.

Declaration

ItemBeforeWidgetDisposed: ASPxClientEvent<ASPxClientDashboardItemBeforeWidgetDisposedEventHandler<ASPxClientDashboard>>

Event Data

The ItemBeforeWidgetDisposed event handler receives an argument of the ASPxClientDashboardItemWidgetEventArgs type. The following properties provide information specific to this event.

Property Description
ItemName Gets the component name of the dashboard item for which the event was raised.
See Also

ItemBeginUpdate Event

Occurs when a dashboard item update is initiated.

Declaration

ItemBeginUpdate: ASPxClientEvent<ASPxClientItemBeginUpdateEventHandler<ASPxClientDashboard>>

Event Data

The ItemBeginUpdate event handler receives an argument of the ASPxClientItemBeginUpdateEventArgs type. The following properties provide information specific to this event.

Property Description
ItemName Gets the component name of the dashboard item.

Remarks

After the dashboard item update is performed, the ASPxClientDashboard.ItemEndUpdate event is fired.

See Also

ItemCaptionToolbarUpdated Event

Allows you to customize a dashboard item's caption (for instance, add custom buttons, menus, etc.).

Declaration

ItemCaptionToolbarUpdated: ASPxClientEvent<ASPxClientDashboardItemCaptionToolbarUpdatedEventHandler<ASPxClientDashboard>>

Event Data

The ItemCaptionToolbarUpdated event handler receives an argument of the ASPxClientDashboardItemCaptionToolbarUpdatedEventArgs type. The following properties provide information specific to this event.

Property Description
ItemName Gets a component name of the dashboard item.
Options Provides access to caption options of the dashboard item.

Remarks

You can handle the ItemCaptionToolbarUpdated event to customize the dashboard item's caption. For instance, you can add custom command buttons, create additional menus, add static texts, etc. The DashboardItemCaptionToolbarOptions class contains options used to customize a dashboard item caption's elements (the ViewerToolbarItem objects).

The following code snippets show how to add a custom button to the Chart's caption. This button belongs to the actionItems collection and is displayed only when the mouse pointer hovers over the dashboard item's caption.

function onItemCaptionToolbarUpdated(s, e) {
  if (e.ItemName === "chartDashboardItem1") {
      e.Options.actionItems.push({
          type: "button",
          text: "Custom Button",
          click: function () {
              // ...
          }
      });
  }
}

ItemClick Event

Occurs when an end-user clicks a dashboard item.

Declaration

ItemClick: ASPxClientEvent<ASPxClientDashboardItemClickEventHandler<ASPxClientDashboard>>

Event Data

The ItemClick event handler receives an argument of the ASPxClientDashboardItemClickEventArgs type. The following properties provide information specific to this event.

Property Description
ItemName Gets the name of the dashboard item for which the event has been raised.

Remarks

Use the ASPxClientDashboardItemClickEventArgs.ItemName event parameter to obtain the dashboard item name for which the event has been raised.

The ASPxClientDashboardItemClickEventArgs.GetAxisPoint allows you to obtain the axis point corresponding to the clicked visual element. Use the ASPxClientDashboardItemClickEventArgs.RequestUnderlyingData method to request the underlying data related to this visual element.

The ASPxClientDashboardItemClickEventArgs.GetData method returns the client data for this dashboard item.

Note

The ItemClick event has the following limitations:

ItemDrillDownStateChanged Event

Occurs when a drill-down/drill-up is performed.

Declaration

ItemDrillDownStateChanged: ASPxClientEvent<ASPxClientDashboardItemDrillDownStateChangedEventHandler<ASPxClientDashboard>>

Event Data

The ItemDrillDownStateChanged event handler receives an argument of the ASPxClientDashboardItemDrillDownStateChangedEventArgs type. The following properties provide information specific to this event.

Property Description
Action Gets the drill-down action performed in the dashboard item.
ItemName Gets the component name of the dashboard item.
Values Gets values from the current drill-down hierarchy.

Remarks

The ItemDrillDownStateChanged event is raised when an end-user performs drill-down or drill-up in a certain dashboard item. To determine the component name of this dashboard item, use the ASPxClientDashboardItemEventArgs.ItemName event parameter. Other event parameters include the following.

WebDashboardDrillDownScheme

ItemElementCustomColor Event

Allows you to color the required dashboard item elements using the specified colors.

Declaration

ItemElementCustomColor: ASPxClientEvent<ASPxClientDashboardItemElementCustomColorEventHandler<ASPxClientDashboard>>

Event Data

The ItemElementCustomColor event handler receives an argument of the ASPxClientDashboardItemElementCustomColorEventArgs type. The following properties provide information specific to this event.

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

Remarks

The ItemElementCustomColor event allows you to color the required dashboard item elements (for instance, chart series points, pie segments or scatter chart points) using the specified colors. The ASPxClientDashboardItemElementCustomColorEventArgs class exposes the following settings that allow you to color the required element.

Note that color modifications applied using the ItemElementCustomColor event are not applied in the resulting exported document.

Note

By default, the Chart dashboard item colors lines (or fills areas) for the Line/Area series types using the color of the first series point. For these lines/areas, the ASPxClientDashboardItemElementCustomColorEventArgs.GetTargetElement method returns a tuple that does not contain the axis point on the DashboardDataAxisNames.ChartArgumentAxis.

See Also

ItemEndUpdate Event

Occurs after the dashboard item update is performed.

Declaration

ItemEndUpdate: ASPxClientEvent<ASPxClientItemEndUpdateEventHandler<ASPxClientDashboard>>

Event Data

The ItemEndUpdate event handler receives an argument of the ASPxClientItemEndUpdateEventArgs type. The following properties provide information specific to this event.

Property Description
ItemName Gets the component name of the dashboard item.

Remarks

When the dashboard item update is initiated, the ASPxClientDashboard.ItemBeginUpdate event is fired.

See Also

ItemMasterFilterStateChanged Event

Occurs when a master filter state is changed.

Declaration

ItemMasterFilterStateChanged: ASPxClientEvent<ASPxClientDashboardItemMasterFilterStateChangedEventHandler<ASPxClientDashboard>>

Event Data

The ItemMasterFilterStateChanged event handler receives an argument of the ASPxClientDashboardItemMasterFilterStateChangedEventArgs type. The following properties provide information specific to this event.

Property Description
ItemName Gets the component name of the dashboard item.
Values Gets the currently selected values.

Remarks

The ItemMasterFilterStateChanged event is raised when an end-user applies or clears master filtering in a certain dashboard item. To determine the component name of this dashboard item, use the ASPxClientDashboardItemEventArgs.ItemName event parameter. The ASPxClientDashboardItemMasterFilterStateChangedEventArgs.Values property returns currently selected values.

Note

For the Range Filter dashboard item, the ASPxClientDashboardItemMasterFilterStateChangedEventArgs.Values property returns the minimum and maximum values in the selected range (these values are JavaScript date instances).

ItemSelectionChanged Event

Occurs after the selection within the dashboard item is changed.

Declaration

ItemSelectionChanged: ASPxClientEvent<ASPxClientDashboardItemSelectionChangedEventHandler<ASPxClientDashboard>>

Event Data

The ItemSelectionChanged event handler receives an argument of the ASPxClientDashboardItemSelectionChangedEventArgs type. The following properties provide information specific to this event.

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

Remarks

The ItemSelectionChanged event is raised after the selection within the dashboard item is changed. The selection can be changed in the following ways:

The ASPxClientDashboardItemSelectionChangedEventArgs.ItemName property returns the name of the dashboard item for which the event was raised. Use the ASPxClientDashboardItemSelectionChangedEventArgs.GetCurrentSelection method to obtain the currently selected elements.

Examples

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

ItemVisualInteractivity Event

Allows you to provide custom visual interactivity for data-bound dashboard items that support element selection and highlighting.

Declaration

ItemVisualInteractivity: ASPxClientEvent<ASPxClientDashboardItemVisualInteractivityEventHandler<ASPxClientDashboard>>

Event Data

The ItemVisualInteractivity event handler receives an argument of the ASPxClientDashboardItemVisualInteractivityEventArgs type. The following properties provide information specific to this event.

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

Remarks

The 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 also fires this event when master filtering is applied to the current dashboard item or drill-down is performed in 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

Dashboard_GreenTick

ChartDashboardItem

DashboardDataAxisNames.ChartArgumentAxis

DashboardDataAxisNames.ChartSeriesAxis

Dashboard_GreenTick

Dashboard_GreenTick

ScatterChartDashboardItem

DashboardDataAxisNames.ChartArgumentAxis

Dashboard_GreenTick

Dashboard_GreenTick

PieDashboardItem

DashboardDataAxisNames.ChartArgumentAxis

DashboardDataAxisNames.ChartSeriesAxis

Dashboard_GreenTick

Dashboard_GreenTick

CardDashboardItem

DashboardDataAxisNames.DefaultAxis

Dashboard_GreenTick

Dashboard_GreenTick

GaugeDashboardItem

DashboardDataAxisNames.DefaultAxis

Dashboard_GreenTick

Dashboard_GreenTick

MapDashboardItem

DashboardDataAxisNames.DefaultAxis

Dashboard_GreenTick

Dashboard_GreenTick

TreemapDashboardItem

DashboardDataAxisNames.DefaultAxis

Dashboard_GreenTick

Dashboard_GreenTick

Note

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

See Also

ItemWidgetCreated Event

Allows you to access underlying UI/Data Visualization widgets.

Declaration

ItemWidgetCreated: ASPxClientEvent<ASPxClientDashboardItemWidgetCreatedEventHandler<ASPxClientDashboard>>

Event Data

The ItemWidgetCreated event handler receives an argument of the ASPxClientDashboardItemWidgetEventArgs type. The following properties provide information specific to this event.

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

Remarks

The Web Dashboard uses DevExtreme widgets to visualize data within dashboard items. The ItemWidgetCreated event allows you to access these widgets and customize their settings if necessary.

The ASPxClientDashboard exposes the following events that allow you to access these widgets and customize their settings.

Note that the dashboard item is re-created when you maximize / restore the item. All events connected with dashboard item life cycle (such as ItemWidgetCreated, ItemWidgetUpdated, etc.) are fired again.

Note

The ItemWidgetCreated event is not fired for a custom dashboard item.

The ASPxClientDashboardItemWidgetEventArgs.ItemName event parameter returns the component name of the dashboard item whose widget may be customized. Use the ASPxClientDashboardItemWidgetEventArgs.GetWidget method to access the corresponding underlying widget.

The following table lists dashboard items whose underlying widgets may be accessed when handling the ItemWidgetCreated event.

Dashboard Item

Underlying Widget(s)

GridItem

dxDataGrid

ChartItem

ScatterChartItem

dxChart

PieItem

an array of dxPieChart widgets

GaugeItem

an array of dxCircularGauge or dxLinearGauge widgets

MapItem

dxVectorMap

PivotItem

dxPivotGrid

ComboBoxItem

dxSelectBox or dxTagBox

ListBoxItem

dxList

TreeViewItem

dxTreeList

dxTreeView (for v17.1 and earlier)

TreemapItem

dxTreeMap

RangeFilterItem

dxRangeSelector

CardItem

CardWidget

DateFilterItem

DateFilterWidget

TextBoxItem

n/a See Note 1

ImageItem

n/a See Note 1

CustomItem

n/a See Note 2

1 The content of the TextBoxDashboardItem and the ImageDashboardItem is an HTML element wrapped in a jQuery object.

2 The CustomDashboardItem is a custom widget. You can customize it directly.

ItemWidgetUpdated Event

Allows you to access underlying UI/Data Visualization widgets.

Declaration

ItemWidgetUpdated: ASPxClientEvent<ASPxClientDashboardItemWidgetUpdatedEventHandler<ASPxClientDashboard>>

Event Data

The ItemWidgetUpdated event handler receives an argument of the ASPxClientDashboardItemWidgetEventArgs type. The following properties provide information specific to this event.

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

Remarks

The Web Dashboard uses DevExtreme widgets to visualize data within dashboard items. The ItemWidgetUpdated event allows you to access these widgets and customize their settings if necessary.

The ASPxClientDashboard exposes the following events that allow you to access these widgets and customize their settings.

  • The ASPxClientDashboard.ItemWidgetCreated event is raised once for each widget when the dashboard is loaded to client. Handle this event to subscribe to events of the client widget.
  • ASPxClientDashboard.ItemWidgetUpdating/ItemWidgetUpdated events are raised when the client widget needs to be updated. For instance, this can be related to applying master filtering or changing parameter values. Handle the ASPxClientDashboard.ItemWidgetUpdating event to unsubscribe from events of the client widget. To customize the widget according your requirements, handle the ItemWidgetUpdated event. This allows you to prevent the ASPxClientDashboard from rewriting customized options.

Note that the dashboard item is re-created when you maximize / restore the item. All events connected with dashboard item life cycle (such as ItemWidgetCreated, ItemWidgetUpdated, etc.) are fired again.

Note

The ItemWidgetUpdated event is not fired for a custom dashboard item.

The ASPxClientDashboardItemWidgetEventArgs.ItemName event parameter returns the component name of the dashboard item whose widget may be customized. Use the ASPxClientDashboardItemWidgetEventArgs.GetWidget method to access the corresponding underlying widget.

The following table lists dashboard items whose underlying widgets may be accessed when handling the ItemWidgetUpdated event.

Dashboard Item

Underlying Widget(s)

GridItem

dxDataGrid

ChartItem

ScatterChartItem

dxChart

PieItem

an array of dxPieChart widgets

GaugeItem

an array of dxCircularGauge or dxLinearGauge widgets

MapItem

dxVectorMap

PivotItem

dxPivotGrid

ComboBoxItem

dxSelectBox or dxTagBox

ListBoxItem

dxList

TreeViewItem

dxTreeList

dxTreeView (for v17.1 and earlier)

TreemapItem

dxTreeMap

RangeFilterItem

dxRangeSelector

CardItem

CardWidget

DateFilterItem

DateFilterWidget

TextBoxItem

n/a See Note 1

ImageItem

n/a See Note 1

CustomItem

n/a See Note 2

1 The content of the TextBoxDashboardItem and the ImageDashboardItem is an HTML element wrapped in a jQuery object.

2 The CustomDashboardItem is a custom widget. You can customize it directly.

ItemWidgetUpdating Event

Allows you to access underlying UI/Data Visualization widgets.

Declaration

ItemWidgetUpdating: ASPxClientEvent<ASPxClientDashboardItemWidgetUpdatingEventHandler<ASPxClientDashboard>>

Event Data

The ItemWidgetUpdating event handler receives an argument of the ASPxClientDashboardItemWidgetEventArgs type. The following properties provide information specific to this event.

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

Remarks

The Web Dashboard uses DevExtreme widgets to visualize data within dashboard items. The ItemWidgetUpdating event allows you to access these widgets and customize their settings if necessary.

The ASPxClientDashboard exposes the following events that allow you to access these widgets and customize their settings.

  • The ASPxClientDashboard.ItemWidgetCreated event is raised once for each widget when the dashboard is loaded to client. Handle this event to subscribe to events of the client widget.
  • ItemWidgetUpdating/ASPxClientDashboard.ItemWidgetUpdated events are raised when the client widget needs to be updated. For instance, this can be related to applying master filtering or changing parameter values. Handle the ItemWidgetUpdating event to unsubscribe from events of the client widget. To customize the widget according your requirements, handle the ASPxClientDashboard.ItemWidgetUpdated event. This allows you to prevent the ASPxClientDashboard from rewriting customized options.

Note that the dashboard item is re-created when you maximize / restore the item. All events connected with dashboard item life cycle (such as ItemWidgetCreated, ItemWidgetUpdated, etc.) are fired again.

Note

The ItemWidgetUpdating event is not fired for a custom dashboard item.

The ASPxClientDashboardItemWidgetEventArgs.ItemName event parameter returns the component name of the dashboard item whose widget may be customized. Use the ASPxClientDashboardItemWidgetEventArgs.GetWidget method to access the corresponding underlying widget.

The following table lists dashboard items whose underlying widgets may be accessed when handling the ItemWidgetUpdating event.

Dashboard Item

Underlying Widget(s)

GridItem

dxDataGrid

ChartItem

ScatterChartItem

dxChart

PieItem

an array of dxPieChart widgets

GaugeItem

an array of dxCircularGauge or dxLinearGauge widgets

MapItem

dxVectorMap

PivotItem

dxPivotGrid

ComboBoxItem

dxSelectBox or dxTagBox

ListBoxItem

dxList

TreeViewItem

dxTreeList

dxTreeView (for v17.1 and earlier)

TreemapItem

dxTreeMap

RangeFilterItem

dxRangeSelector

CardItem

CardWidget

DateFilterItem

DateFilterWidget

TextBoxItem

n/a See Note 1

ImageItem

n/a See Note 1

CustomItem

n/a See Note 2

1 The content of the TextBoxDashboardItem and the ImageDashboardItem is an HTML element wrapped in a jQuery object.

2 The CustomDashboardItem is a custom widget. You can customize it directly.

SelectedTabPageChanged Event

Occurs when the selected tab page is changed.

Declaration

SelectedTabPageChanged: ASPxClientEvent<ASPxClientSelectedTabPageChangedEventHandler<ASPxClientDashboard>>

Event Data

The SelectedTabPageChanged event handler receives an argument of the ASPxClientSelectedTabPageChangedEventArgs type. The following properties provide information specific to this event.

Property Description
PreviousPage Gets the tab page that was selected.
SelectedPage Gets the tab page that is selected.
TabContainerName Gets the name of the tab container that contains the selected tab page.