Manage Interactivity Capabilities

  • 6 minutes to read

Use the Master Filtering and Drill-Down features to enable interaction between various dashboard items.

The ASPxDashboard allows you to apply master filtering and to perform drill-down on the client side. You can also provide custom visual interactivity for data-bound dashboard items that support element selection and highlighting using the ASPxClientDashboard.ItemVisualInteractivity event.

Master Filtering

Refer to End-User Documentation for Dashboard for information on how to apply filtering using a specific dashboard item.

The ASPxClientDashboard.CanSetMasterFilter method allows you to determine whether master filtering can apply to the specified dashboard item. Use the ASPxClientDashboard.GetAvailableFilterValues method to obtain the values of all selectable elements in the current state of the master filter item.

To apply filtering in code, use the ASPxClientDashboard.SetMasterFilter method (or the ASPxClientDashboard.SetRange method for the Range Filter dashboard item).

When filtering is applied, or the state of the master filter item changes, the ASPxClientDashboard.ItemMasterFilterStateChanged event is raised. Its ASPxClientDashboardItemMasterFilterStateChangedEventArgs.Values property allows you to obtain the currently selected values for the dashboard item that causes the event.

MasterFiltering_API_Web

For instance, for the dashboard in the image above, the ASPxClientDashboardItemMasterFilterStateChangedEventArgs.Values property returns “[Anne Dodsworth, UK]” and “[Margaret Peacock, USA]” for the Grid dashboard item.

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).

You can use the client ASPxClientDashboard.GetCurrentFilterValues method to obtain current filter values for a master-filter item.

To clear the selection in the Master Filter item, use the ASPxClientDashboard.ClearMasterFilter method, after which the ASPxClientDashboard.ItemMasterFilterStateChanged event is raised again.

View Example: How to apply master filter in code

View Example: How to apply master filter in OLAP mode

Drill-Down

To learn how end-users can drill down using a particular dashboard item, refer to End-User Documentation for Dashboard.

To perform drill-down/drill-up in code, use the ASPxClientDashboard.PerformDrillDown methods. The ASPxClientDashboard.GetAvailableDrillDownValues method allows you to obtain values that can be used to perform drill-down.

After drill-down (or drill-up) is performed, the ASPxClientDashboard.ItemDrillDownStateChanged event is raised. Its ASPxClientDashboardItemDrillDownStateChangedEventArgs.Values event parameter allows you to obtain values from the current drill-down hierarchy.

View Example: How to perform a drill-down

Custom Interactivity

ASPxClientDashboard allows you to provide custom visual interactivity for data-bound dashboard items that support element selection and highlighting using the ASPxClientDashboard.ItemVisualInteractivity event for dashboard items with master filtering disabled. Visual interactivity is enabled for master filter items by default. The ASPxClientDashboard also fires this event when master filtering applies 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 changes, 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.

View Example: How to add custom interactivity to a dashboard

API Members

Client-side API (Master Filtering) Description
ASPxClientDashboard.CanSetMasterFilter Returns whether master filtering can be applied in the current state of the specified master filter item.
ASPxClientDashboard.GetAvailableFilterValues Returns elements that can be selected in the master filter item’s current state (except Range Filter or Date Filter items).
ASPxClientDashboard.GetCurrentFilterValues Returns axis point tuples identifying currently selected elements in the master filter item.
ASPxClientDashboard.GetCurrentSelection Returns currently selected elements in the master filter item.
ASPxClientDashboard.SetMasterFilter Selects required elements by their values in the specified master filter item.
ASPxClientDashboard.GetEntireRange Returns the visible range for the specified Range Filter or Date Filter dashboard item.
ASPxClientDashboard.GetCurrentRange Returns the currently selected range in the specified Range Filter or Date Filter dashboard item.
ASPxClientDashboard.SetRange Selects the required range in the specified Range Filter or Date Filter dashboard item.
ASPxClientDashboard.SetPredefinedRange Selects a predefined range in the Range Filter or Date Filter dashboard item.
ASPxClientDashboard.CanClearMasterFilter Returns whether the specified master filter can be cleared in the current state.
ASPxClientDashboard.ClearMasterFilter Clears the specified master filter item.
ASPxClientDashboard.ItemMasterFilterStateChanged Occurs when a master filter state is changed.
ASPxClientDashboard.ActionAvailabilityChanged Occurs after the available interactivity actions have changed for the specific dashboard item.
ViewerApiExtension.canSetMasterFilter(itemName) Returns whether master filtering can be applied in the current state of the specified master filter item.
ViewerApiExtension.getAvailableFilterValues(itemName) Returns elements that can be selected in the master filter item’s current state (except Range Filter or Date Filter items).
ViewerApiExtension.getCurrentFilterValues(itemName) Returns axis point tuples identifying currently selected elements in the master filter item.
ViewerApiExtension.getCurrentSelection(itemName) Returns currently selected elements in the master filter item.
ViewerApiExtension.setMasterFilter(itemName, values) Selects required elements by their values in the specified master filter item.
ViewerApiExtension.getEntireRange(itemName) Returns the visible range for the specified Range Filter dashboard item.
ViewerApiExtension.getCurrentRange(itemName) Returns the currently selected range in the specified Range Filter dashboard item.
ViewerApiExtension.setRange(itemName, range) Selects the required range in the specified Range Filter / Date Filter dashboard item.
ViewerApiExtension.setPredefinedRange(itemName, dateTimePeriodName) Selects a predefined range in the Range Filter dashboard item.
ViewerApiExtension.canClearMasterFilter(itemName) Returns whether the specified master filter can be cleared in the current state.
ViewerApiExtension.clearMasterFilter(itemName) Clears the specified master filter item.
ViewerApiExtensionOptions.onItemMasterFilterStateChanged Specifies a handler for the event occurring when the master filter state is changed.
ViewerApiExtensionOptions.onItemActionAvailabilityChanged Specifies a handler for the event occurring after the available interactivity actions have changed for the specific dashboard item.
Client-side API (Drill-Down) Description
ASPxClientDashboard.CanPerformDrillDown Returns whether drill down is possible in the current state of the specified dashboard item.
ASPxClientDashboard.CanPerformDrillUp Returns whether drill up is possible in the current state of the specified dashboard item.
ASPxClientDashboard.GetAvailableDrillDownValues Returns axis point tuples identifying elements that can be used to perform drill-down in the specified dashboard item.
ASPxClientDashboard.GetCurrentDrillDownValues Returns the axis point tuple identifying the current drill-down state.
ASPxClientDashboard.PerformDrillDown Performs a drill-down into the required element by its value.
ASPxClientDashboard.PerformDrillUp Performs a drill-up for the specified dashboard item.
ASPxClientDashboard.ItemDrillDownStateChanged Occurs when a drill-down/drill-up is performed.
ViewerApiExtension.canPerformDrillDown(itemName) Returns whether drill down is possible in the current state of the specified dashboard item.
ViewerApiExtension.canPerformDrillUp(itemName) Returns whether drill up is possible in the current state of the specified dashboard item.
ViewerApiExtension.getAvailableDrillDownValues(itemName) Returns axis point tuples identifying elements that can be used to drill down in the specified dashboard item.
ViewerApiExtension.getCurrentDrillDownValues(itemName) Returns the axis point tuple identifying the current drill-down state.
ViewerApiExtension.performDrillDown(itemName, value) Performs a drill-down into the required element.
ViewerApiExtension.performDrillUp(itemName) Performs a drill-up for the required element.
ViewerApiExtensionOptions.onItemDrillDownStateChanged Specifies a handler for the event occurring when a drill-down/drill-up is performed.