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.

Scripting with Parameters

Hide navigation
RSS
Modified on Mon, 27 Jan 2014 04:28 PM Categorized as Level-Advanced, Level-Expert, Parameters, Scripting

Parameters on Dundas Dashboard are structured to handle many different situations. This article describes the underlying structure of parameters and how they behave so that you can build your own custom scripts to manipulate parameters.

The Basics

Parameters are updated using a four- to five-level hierarchy.
Summary of the ParameterInfo Hierarchy

Summary of the ParameterInfo Hierarchy


DashboardMemberValueData

Each member (node) of a full dimension has one or many keys that uniquely identify it. This can be a product code or a date. When scripting with parameters on the dashboard, these are stored in the .Values collection of a DashboardMemberValueData object. In most cases, each member of a dimension will only have one key. If there are multiple keys there will be multiple values in this collection. A DashboardMemberValueData object identifies a single member of a dimension.

DashboardFilterValueData

A user’s choice on a parameter can sometimes be complex. For example, a date range actually consists of two parameter keys: a start date and an end date. In this situation, each DashboardMemberValueData object identifies a different member of the dimension and so need to be stored in a collection in a DashboardFilterValueData object. This object uniquely identifies a selection.

ParameterInfo

In certain cases, it is possible to make multiple selections. For example, if a user wanted to see the performance of only two specific employees, a multi-select parameter could be used. This would mean that a collection of selections is necessary. This is why ParameterInfo objects store DashboardFilterValueData objects in a collection. ParameterInfo objects store all of the relevant details for one parameter. When modifying a particular parameter, a ParameterInfo object is passed to the .UpdateFromParameterInfo() method of a DashboardParameter.

ParameterInfoCollection

When parameters are updated through script such as in a drill-down or a hover-over it is possible for them to pass the values of several parameters during that process. As a result, a collection of ParameterInfo objects (in other words, a ParameterInfoCollection) is needed.

Examples

Simple Categorical Selection

Suppose you have a "Countries" dimension that used a three-letter identifier for each country. If you wanted to set the value of the parameter to a particular country, you would need to first add the key to the Values collection of a DashboardMemberValueData object.

string mySelection = "USA"; DashboardMemberValueData mvd = new DashboardMemberValueData(); mvd.Values.Add(mySelection);

Next, we need to add the selection to a DashboardFilterValueData object which will then be added to a ParameterInfo object.

DashboardFilterValueData fvd = new DashboardFilterValueData(); fvd.MemberValues.Add(mvd); ParameterInfo myParam = new ParameterInfo(); myParam.ParameterName = "Countries"; myParam.FilterValues.Add(fvd);

If this will be used in a drill-down or hover-over, a ParameterInfoCollection object is necessary.

ParameterInfoCollection params = new ParameterInfoCollection(); params.Add(myParam);

The end result is what is illustrated in the image below.
The hierarchy setup for a simple categorical selection.

The hierarchy setup for a simple categorical selection.


This ParameterInfoCollection object is then used in the drill-down or hover-over script:

services.NavigateToDashboard(myDashboardID, params);

Simple Date Selection

Suppose you have a date dimension that you want to modify. Dates are managed slightly different from categorical dimensions in that they require a start and end point. So let's start off by defining the start and end dates in two separate MemberValueData objects:

DateTime startDate = new DateTime(2011, 12, 1); DashboardMemberValueData mvdStart = new DashboardMemberValueData(); mvdStart.Values.Add(startDate); DateTime endDate = new DateTime(2012, 2, 1); DashboardMemberValueData mvdEnd = new DashboardMemberValueData(); mvdEnd.Values.Add(endDate);

Operators need to be set on both DashboardMemberValueData objects to specify how the range is evaluated. They are then added to a DashboardFilterValueData object.

mvdStart.Operator = ComparisonOperator.GreaterOrEqualThan; mvdEnd.Operator = ComparisonOperator.SmallerThan; DashboardFilterValueData fvd = new DashboardFilterValueData(); fvd.MemberValues.Add(mvdStart); fvd.MemberValues.Add(mvdEnd);

Since the DashboardFilterValueData object is managing a date parameter, we need to set the .IsConsolidatedDateTime property. We then add it to a ParameterInfo object so that it can be used to update a parameter.

fvd.IsConsolidatedDateTime = true; ParameterInfo dateParam = new ParameterInfo(); dateParam.FilterValues.Add(fvd); dateParam.ParameterName = "Date"; Date.UpdateFromParameterInfo(dateParam); Date.InvalidateFilter();

The end result is shown below:
The structure of a date selection.

The structure of a date selection.


Simple Multi-Selection

When using a categorical dimension, sometimes you may want to select more than one item in the hierarchy. Since each DashboardMemberValueData represents a unique dimension node, we need to create one for each of the selections.

DashboardMemberValueData mvdA = new DashboardMemberValueData(); DashboardMemberValueData mvdB = new DashboardMemberValueData(); string hats = "Hats"; string shoes = "Shoes"; mvdA.Values.Add(hats); mvdB.Values.Add(shoes);

Now since each DashboardFilterValueData represents a unique selection and we have two items selected, we will need two DashboardFilterValueData objects:

DashboardFilterValueData fvdA = new DashboardFilterValueData(); DashboardFilterValueData fvdB = new DashboardFilterValueData(); fvdA.MemberValues.Add(mvdA); fvdB.MemberValues.Add(mvdB);

We now have two DashboardFilterValueData objects ready to be added to a ParameterInfo object to be used to update a parameter.

ParameterInfo param = new ParameterInfo(); param.FilterValues.Add(fvdA); param.FilterValues.Add(fvdB); param.ParameterName = "Product"; Product.UpdateFromParameterInfo(param); Product.InvalidateFilter();

The end result is shown below:
The structure of a multi-selection.

The structure of a multi-selection.


Advanced Multi-Selection

The previous examples of using a categorical dimension are ones where a single-level hierarchy is used. In many instances, you may have a product hierarchy where there are each product belongs to a category. In these instances, the higher-level nodes need to be included in the DashboardFilterValueData objects along with the original selection node.

string hats = "Hats"; string beret = "Beret"; string fedora = "Fedora"; DashboardMemberValueData mvd_Hats = new DashboardMemberValueData(); DashboardMemberValueData mvd_Beret = new DashboardMemberValueData(); DashboardMemberValueData mvd_Fedora = new DashboardMemberValueData(); mvd_Hats.Values.Add(hats); mvd_Beret.Values.Add(beret); mvd_Fedora.Values.Add(fedora);

Since the DashboardMemberValueData objects belong to different levels of the hierarchy, we need to explicitly set the .HierarchyLevel.

mvd_Hats.HierarchyLevel = 0; mvd_Beret.HierarchyLevel = 1; mvd_Fedora.HierarchyLevel = 1;

Since we have multiple items selected, we will need multiple DashboardFilterValueData objects.

DashboardFilterValueData fvd_Beret = new DashboardFilterValueData(); DashboardFilterValueData fvd_Fedora = new DashboardFilterValueData(); fvd_Beret.MemberValues.Add(mvd_Beret); fvd_Beret.MemberValues.Add(mvd_Hats); fvd_Fedora.MemberValues.Add(mvd_Fedora); fvd_Fedora.MemberValues.Add(mvd_Hats);

The DashboardFilterValueData objects are then added to a ParameterInfo object as usual.

ParameterInfo prodParam = new ParameterInfo(); prodParam.FilterValues.Add(fvd_Beret); prodParam.FilterValues.Add(fvd_Fedora); prodParam.ParameterName = "Product"; Product.UpdateFromParameterInfo(prodParam); Product.InvalidateFilter();

The resulting structure is as follows:
Selecting multiple items in a two-level hierarchy.

Selecting multiple items in a two-level hierarchy.


Multiple Parameters

Changing multiple parameters is very straight forward. When drilling down, simply add multiple ParameterInfo objects to the ParameterInfoCollection. Otherwise, simply invalidate multiple parameters. The script below is quite long and so requires the #UNSUPPORTED UNLIMITED line.

#UNSUPPORTED UNLIMITED

string hats = "Hats"; string beret = "Beret"; string fedora = "Fedora";

DashboardMemberValueData mvd_Hats = new DashboardMemberValueData(); DashboardMemberValueData mvd_Beret = new DashboardMemberValueData(); DashboardMemberValueData mvd_Fedora = new DashboardMemberValueData(); mvd_Hats.Values.Add(hats); mvd_Beret.Values.Add(beret); mvd_Fedora.Values.Add(fedora); mvd_Hats.HierarchyLevel = 0; mvd_Beret.HierarchyLevel = 1; mvd_Fedora.HierarchyLevel = 1;

DashboardFilterValueData fvd_Beret = new DashboardFilterValueData(); DashboardFilterValueData fvd_Fedora = new DashboardFilterValueData(); fvd_Beret.MemberValues.Add(mvd_Beret); fvd_Beret.MemberValues.Add(mvd_Hats); fvd_Fedora.MemberValues.Add(mvd_Fedora); fvd_Fedora.MemberValues.Add(mvd_Hats);

ParameterInfo prodParam = new ParameterInfo(); prodParam.FilterValues.Add(fvd_Beret); prodParam.FilterValues.Add(fvd_Fedora); prodParam.ParameterName = "Product";

DateTime startDate = new DateTime(2011, 12, 1); DashboardMemberValueData mvdStart = new DashboardMemberValueData(); mvdStart.Values.Add(startDate);

DateTime endDate = new DateTime(2012, 2, 1); DashboardMemberValueData mvdEnd = new DashboardMemberValueData(); mvdStart.Values.Add(endDate);

startDate.Operator = ComparisonOperator.GreaterOrEqualThan; endDate.Operator = ComparisonOperator.SmallerThan;

DashboardFilterValueData fvd = new DashboardFilterValueData(); fvd.MemberValues.Add(startDate); fvd.MemberValues.Add(endDate); fvd.IsConsolidatedDateTime = true; ParameterInfo dateParam = new ParameterInfo(); dateParam.FilterValues.Add(fvd); dateParam.ParameterName = "Date";

ParameterInfoCollection params = new ParameterInfoCollection(); params.Add(prodParam); params.Add(dateParam); services.NavigateToDashboard(myDashboardID, params);


The resulting structure is as follows:
A complex update of several parameters.

A complex update of several parameters.


Related topics

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

Copyright © 2009-2014 Dundas Data Visualization, Inc.