416.467.9100 | Dundas Data Visualization | Login
Welcome Guest
Dashboard v5.0

This site makes extensive use of JavaScript.

Please enable JavaScript in your web browser and reload the page before proceeding.

How to read data from a control

Hide navigation
RSS
Modified on Wed, 19 Mar 2014 11:12 AM Categorized as Scripting
Dundas Dashboard Script LibraryPrevious


This will briefly explain how to read data from a control when using a script. This is useful in almost all dashboards since most customization depends on the data that needs to be shown.

Background

In order to use a control's data, it is important to know how each control and its data are linked together.

How data is linked to a control

Whenever you drop a KPI or dataset onto the dashboard or an existing control, a link is made between a data visualization control on the dashboard and the KPI/dataset. This is what we refer to as a data descriptor. Each descriptor on a dashboard must have a unique name.

Some controls only allow a single KPI/dataset to be added while some allow many. You can see all of the KPIs/datasets which were added to a control by right-clicking on it in the designer and choosing Data Information:

A chart with 3 KPIs added to it

A chart with 3 KPIs added to it


You can rename descriptors here by clicking on the name, and the settings here allow you to configure how data from the linked KPI/dataset is used in the control (for example, which measure is used as the Y axis value in a chart series).

Referencing a data descriptor in script

The data descriptors are accessible through script. Each data-driven control has a property, DataDescriptors, which is a collection of those descriptors. The descriptors are in the same order as you see in the Data Information popup.

The DashboardContent type (for example, from services.CurrentDashboard) has an AnalyticalDataDescriptors collection for analytical dashboards, and a DataDescriptors collection for performance dashboards. These collections all the data descriptors for every control in the dashboard. There are also methods for finding descriptors by their name, by the name of the control they're used in, etc.:

  • GetAnalyticalDataDescriptorByName
  • GetAnalyticalDataDescriptorsByAnalyticalVisualObjectName
  • GetDataDescriptorByName
  • GetDataDescriptorByToken
  • GetDataDescriptorsByDataVisualizationObjectName



The data result

Whenever data is retrieved for a KPI/dataset, the result is stored in the data descriptor's DataResult property. The data result contains a DataPoints collection, where each data point represents a row of data. The data point itself then has the values for each column inside its FieldValues collection.

Every KPI/dataset contains a single value representation rule which summarizes the entire KPI/dataset into a single data point. Examples of controls that use this are gauges, data labels, and state indicators. This data point is in the data result's SingleDataPoint property.

Tip: The DataResult property will be null until the very first time data is loaded. Controls normally load their data by the time the Loaded Interaction runs unless the Disable Loading Data property is used.

Tip: When the dashboard's Parameter Changed interaction fires, the data has been retrieved but the control has not had a chance to process it yet. Scripts that need to use the new data and some visual element of the control need to be put in the control's On Data Changed Interaction or the On Layout Updated Interaction instead.



Reading data from a control

Putting all the above together, it's easy to see how to read data from a control. For example, here is how to loop over every row of the raw data result:

DashboardDataDescriptor dd = Control.DataDescriptors0; DataResult dr = dd.DataResult;

foreach (DataPoint dataPoint in dr.DataPoints) { // Do something with the data object firstColumnValue = dataPoint.FieldValues0; ... }


The problem with the code above is that the index for the FieldValues collection is sensitive to columns being re-ordered, and it provides little hint as to what the column being read is. For this reason it's better to use the methods on the data descriptor to read data, as you're able to retrieve values using the name of the column:

DashboardDataDescriptor dd = Control.DataDescriptors0; DataResult dr = dd.DataResult;

foreach (DataPoint dataPoint in dr.DataPoints) { // Do something with the data object columnValue = dd.GetDataPointColumnValue(dataPoint, "ColumnName"); ... }


The ColumnName you must provide is the name of the column as seen in the KPI/dataset preview.

Tip: The data result contains all columns from your KPI/dataset even if you haven't used them anywhere in your control. For example, you can get the value for a measure that isn't your Y axis value to determine the color of your chart's points.

Add,modify,delete or remove datapoints at runtime

If you want to modify the data controls dynamically see this article: How to modify data controls using scripting

Related Topics

About Dundas | Contact Us Follow us on Twitter! | Privacy Statement | Report Site Issues

Copyright © 2009-2014 Dundas Data Visualization, Inc.