Underlying and Displayed Data
- 7 minutes to read
The DashboardControl API allows you to retrieve underlying data from the dashboard data source and obtain the data displayed within the dashboard item.
Dashboard Item Data
The dashboard aggregates and visualizes data from the underlying data source, creating the inner pivot table that is the MultiDimensionalData object instance. Use the GetItemData method to obtain all data for a dashboard item specified by its ComponentName:
| Platform | Method |
|---|---|
| WinForms | DashboardViewer.GetItemData , DashboardDesigner.GetItemData |
| ASPxClientDashboardControl | ASPxClientDashboard.GetItemData |
| HTML JavaScript Control | ViewerApiExtension.getItemData |
| WPF | DashboardControl.GetItemData |
Data Structure
The MultiDimensionalData object is the data storage for any dashboard item, regardless of the item type. A chart, a grid, a map or a card - all they store its data in a uniform multidimensional type resembling a pivot table. This approach has its advantages - the consistency and compact API, and disadvantages - simple item-specific actions results in complex API expressions.
Consider the PivotDashboardItem shown in the picture below.
A selected cell displays the Measure value of the MultiDimensionalData object obtained by slicing the dashboard item data object (the current MultiDimensionalData object) against the AxisPoints on the Row and Column data axes.
Dimension Values and Axis Points
A dimension value is stored in the AxisPoint class, comprising a point located on a data axis (the DataAxis class). Dimension values for the selected cell are stored in two AxisPoints - one for the Row axis, another for the Column axis.
Different dashboard items have different axis names. The pivot grid has the Row and “ axes, the chart has the Argument and Series axes, other items may have the Default axis. The static DashboardDataAxisNames class contains valid axis names. You can use class properties to specify axes in method parameters.
The AxisPoints, shown in the picture, have the following properties that return dimension values:
| Property | Column AxisPoint Value | Row AxisPoint Value |
|---|---|---|
| DisplayText | Q1 | Chang |
| Value | 1 | Chang |
| UniqueValue | 1 | Chang |
Dimension values comprise an hierarchy of AxisPoints represented as tree-like structure. An AxisPoint is a tree node and has a parent and child nodes. The Column AxisPoint related to the selected cell in the picture has one parent AxisPoint (its display text is “1997”) and no child AxisPoints. The related Row AxisPoint in the picture has one parent AxisPoint (its display text is “Beverages”) and no child AxisPoints.
The image below illustrates how hierarchical data is stored in the MultiDimensionalData object.
The MultiDimensionalData.GetDimensions method, called with the valid axis name as the parameter, returns the collection of DimensionDescriptor objects. A DimensionDescriptor contains the dimension name, identifier, grouping characteristics and the data member name used to populate the dimension with data.
To access dimension values, obtain axis points located on the required data axis. Use the following methods:
| Method | Description |
|---|---|
| MultiDimensionalData.GetAxisPoints | Gets data points belonging to the specified axis. |
| MultiDimensionalData.GetAxisPointsByDimension | Gets axis points corresponding to the specified dimension. |
As an alternative, obtain the required data axis by calling the MultiDimensionalData.GetAxis method. The returned DataAxis object exposes the DataAxis.GetPoints method that returns axis points of the current axis.
Slicing
The MultiDimensionalData.GetSlice method returns the slice of the current MultiDimensionalData object by the specified axis point. In the picture above, the slice by the “Product 3” axis point is shown shaded in green. It contains Measure values for all date intervals. The slice by the “May” axis point is shown shaded in blue, it contains Measure values for all products. If you sequentially call the GetSlice method two times, you can obtain the slice at the intersection of the “Product 3” and “May” axis points. It is the cell MultiDimensionalData object, whose MultiDimensionalData.GetValue method returns the Measure value displayed in the cell.
WinForms Example
Considering the Pivot Item picture in the beginning of the article, the following code returns the “$1.93K” string displayed in the cell:
using DevExpress.DashboardCommon;
using DevExpress.DashboardCommon.ViewerData;
using System.Linq;
// ...
private string GetCellDisplayText()
{
DashboardItem dashboardItem = dashboardViewer1.Dashboard.Items.FirstOrDefault(i => i.Name == "Pivot 1");
MultiDimensionalData displayedData = dashboardViewer1.GetItemData(dashboardItem.ComponentName);
MultiDimensionalData sliceByRow = displayedData.GetSlice(DashboardDataAxisNames.PivotRowAxis, new object[] { "Beverages", "Chang" });
MultiDimensionalData sliceByRowAndColumn = sliceByRow.GetSlice(DashboardDataAxisNames.PivotColumnAxis, new object[] { 2015, 1 });
MeasureValue cellValue = sliceByRowAndColumn.GetValue(displayedData.GetMeasures()[0]);
return cellValue.DisplayText;
}
The slice of the MultiDimensionalData object can be described by the AxisPointTuple class instance containing a set of axis points. The AxisPointTuple class is used in API methods that operate with master filters or drill-down values.
Measure Values
Measure values are summaries calculated for measure data contained in the MultiDimensionalData object. The MultiDimensionalData.GetValue method results in the following values depending on the MultiDimensionalData object type:
- Grand Total for the MultiDimensionalData object with all the data displayed in the dashboard item
- Total for the slice by a single AxisPoint
- cell value for the intersection of several axis points. The method requires a measure whose values are summarized. A measure is specified as the method’s parameter as the MeasureDescriptor object. To obtain this object, call the MultiDimensionalData.GetMeasures method.
Delta Values
Delta values are calculated for the following dashboard items:
- CardDashboardItem
- GaugeDashboardItem
- GridDashboardItem with a GridDeltaColumn
- ChoroplethMapDashboardItem
To obtain delta values, use the MultiDimensionalData.GetDeltaValue method. To obtain a required DeltaDescriptor, use the MultiDimensionalData.GetDeltas method.
The resulting DeltaValue object is a container for delta characteristics, such as Actual and Target values and others.
Note
You can obtain summary values for hidden measures using MultiDimensionalData.GetValue or MultiDimensionalData.GetDeltaValue methods.
Underlying Data
The dashboard visualizes aggregated data from the underlying data source. You can obtain underlying data for a particular dashboard item with the methods listed below:
| Platform | Method |
|---|---|
| WinForms | DashboardViewer.GetUnderlyingData , DashboardDesigner.GetUnderlyingData |
| ASPxClientDashboard | ASPxClientDashboard.RequestUnderlyingData |
| HTML JavaScript Control | ViewerApiExtension.requestUnderlyingData |
| WPF | DashboardControl.GetUnderlyingData |
You can get all dashboard item’s data or a data set related to the specified AxisPoint. The resulting DashboardUnderlyingDataSet object implements the IBindingList interface and you can assign it to the GridControl’s ItemSource property to display data in the Data Grid, as the following sample projects demonstrate:
- WinViewer - How to Display the Underlying Data for a Dashboard Item
- ASPxDashboard - How to obtain a dashboard item’s underlying data for a clicked visual element
You can use Data Inspector to obtain raw or aggregated data in UI.
Events
WinForms
The DashboardViewer allows you to access underlying and displayed data when handling the following events:
- DashboardViewer.DashboardItemClick
- DashboardViewer.DashboardItemDoubleClick
- DashboardViewer.DashboardItemMouseDown
- DashboardViewer.DashboardItemMouseUp
When handling these events, you can obtain the axis point related to the clicked visual element (the DashboardItemMouseHitTestEventArgs.GetAxisPoint method) or corresponding underlying data (the DashboardItemMouseHitTestEventArgs.GetUnderlyingData method). Use the DashboardItemMouseEventArgs.DashboardItemName event parameter to obtain the component name of the dashboard item, for which the event was raised.
Web
The ASPxClientDashboard allows you to access underlying and client data when handling the ASPxClientDashboard.ItemClick event.
When handling this event, you can obtain the axis point related to the clicked visual element (the ASPxClientDashboardItemClickEventArgs.GetAxisPoint method) or corresponding underlying data (the ASPxClientDashboardItemClickEventArgs.RequestUnderlyingData method). Use the ASPxClientDashboardItemClickEventArgs.ItemName event parameter to obtain the component name of the dashboard item for which the event was raised.
WPF
The DashboardControl allows you to access underlying and client data when handling the following events:
- DashboardControl.DashboardItemMouseDoubleClick
- DashboardControl.DashboardItemMouseDown
- DashboardControl.DashboardItemMouseMove
- DashboardControl.DashboardItemMouseUp
When handling these events, you can obtain AxisPoints related to the element under the mouse pointer using the GetAxisPoint method. The (the GetUnderlyingData method gives you the underlying data for an element under the mouse pointer. The DashboardItemName event parameter contains the dashboard item’s component name.