416.467.9100 | Dundas Data Visualization | Login
Welcome Guest
This is the support page for the legacy Dundas Dashboard application. For assistance with the current Dundas BI application please click here.
Dashboard v5.0

This site makes extensive use of JavaScript.

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

Scripting a Parameter Filter

Hide navigation
RSS
Modified on Wed, 06 Nov 2013 09:07 AM Categorized as Level-Advanced, Parameter Controls, Parameters, Scripting
Click to return to: Documentation


Dundas Dashboard parameters can be set dynamically through custom scripting. Since parameters are structured to handle many different situations, the parameter properties that need to be set vary from one scenario to the next.

This article describes in detail how to set parameter values for each type of Dashboard Parameter as well as each corresponding Dashboard Parameter Control (if applicable).

Tip: Watch the how-to video: Add Parameter Scripting

Filter Parameters

A filter parameter controls the value of a KPI or dataset filter. Filter parameters can be dragged onto the dashboard and used in scripts.

Selecting a filter parameter when setting up a Dashboard Parameter.

Selecting a filter parameter when setting up a Dashboard Parameter.


Structure

Each filter parameter is made up of a DashboardParameter object.

The DashboardParameter object has a FilterValues property, which contains a list of filters. Each item in the list is of type DashboardFilterValueData. When only single selection is allowed, the FilterValues object will contain only one item. When multi-selection is allowed, the FilterValues object could be empty (nothing selected) or there could be multiple items in the list (one DashboardFilterValueData object for each selected item).

Each individual DashboardFilterValueData object then has a MemberValues property, which contains a list of member values. Each item in the list is of type DashboardMemberValueData. The MemberValues object will contain one item for each element in the filter. For a parameter with a single dimension (e.g. a drop down list), there will be one element in MemberValues corresponding to the selected item. A parameter that allowes ranges to be selected (e.g. a date range) will consist of two elements (start date and end date) and will therefore have two corresponding member values. For a parameter with multiple hierarchy levels (e.g. a cascading hierarchy), the MemberValues object will contain one item for each hierarchy level. If a token such as All values is set for the given filter value, the MemberValues object will be empty, since no specific value has been set.

Each individual DashboardMemberValueData object in turn has a Values property, which contains one or many keys that uniquely identifies it. If the member is a token (e.g. Beginning of time), then the Values property will be empty and the DashboardMemberValueData object will instead have a token value set for that member.

The structure of a filter parameter.

The structure of a filter parameter.


Getting Parameter Values

The parameter properties listed in the table below are relevant when setting a parameter filter via scripting. Not every property needs to be set for every type of Dashboard Parameter control. The specific properties that are needed for each control are covered in the next section.

Script NameTypeDescription
DashboardParameter.FilterValuesCollection<DashboardFilterValueData>The filter values. Each item in the list contains details specific to a single selection.
DashboardParameter.FilterValues.IsConsolidatedDateTimeboolA value indicating whether this instance is a consolidated date time. This is true for a date or a date range.
DashboardParameter.FilterValues.IsRangeboolA value indicating whether this instance is a range. This is true for a date or a date range.
DashboardParameter.FilterValues.NamedTokenValueNamedTokenThe named token value of the filter. A token represents an intelligent selection of values.
DashboardParameter.FilterValues.MemberValuesCollection<DashboardMemberValueData>The member values. Each item in the list contains details specific to a single element that comprises the selection.
DashboardParameter.FilterValues.MemberValues.DateTimeGrainDateTimeGrainThe Gregorian calendar date time grain.
DashboardParameter.FilterValues.MemberValues.HierarchyLevelintThe hierarchy level of the member. The hierarchy level can be in the range [0, n-1] where n is the total number of hierarchy levels. 0 denotes the highest hierarchy level and n-1 the lowest.
DashboardParameter.FilterValues.MemberValues.NamedTokenValueNamedTokenThe named token value of the member. A token represents an intelligent selection of values.
DashboardParameter.FilterValues.MemberValues.OperatorComparisonOperatorThe operator of the member. This property is set for date or numeric ranges. The default range start operator is GreaterOrEqualThan. The default range end operator is SmallerThan for a date/time and SmallerOrEqualThan for a number.
DashboardParameter.FilterValues.MemberValues.TextstringThe string representation of the member.
DashboardParameter.FilterValues.MemberValues.ValuesCollection<object>The values. These are the key(s) used to uniquely identify an element in the dimension.
DashboardParameter.FilterValues.MemberValues.ReadableValuesCollection<string>The readable values. ReadableValues must always be set whenever Values is set. The purpose here is to provide a human-readable value to the script engine in case the user wishes to print out the values of this parameter.

Debugging the Parameter

The following script can help you debug your own filter parameter by outputing all of these parameter properties in the script console. Follow these steps to add this debug script to your Dashboard:

  1. Add a Dashboard Button to your dashboard.
  2. Place the following script in the button's Click Interactions list. Make sure to change the parameter name at the top of the script to point to your own filter parameter.
  3. When previewing your dashboard, clicking the newly created Dashboard Button will output the current filter properties in the script console.

Note: If you haven't already done so, drag your parameter onto your dashboard canvas where it will turn into the corresponding parameter control. Use this control to arbitrarily filter your data and then click the button to output the corresponding filter values. This will help you to get familiar with the parameter structure.

  1. UNSUPPORTED UNLIMITED
    /******************** User Variables ********************/
    object param = YourParameterName; // your parameter
    /********************************************************/

// Create a debug string to hold all relevant information string s = string.Empty;

// Output the parameter name s += "PARAMETER FILTER FOR " + param.Name + "\r\n";

// Output the number of items in FilterValues s += "param.FilterValues.Count : " + param.FilterValues.Count.ToString() + "\r\n";

// Iterate through the parameter's FilterValues object int fvIndex = 0; foreach (DashboardFilterValueData fvd in param.FilterValues) { // Output relevant FilterValues properties s += "fvd" + fvIndex.ToString() + ".IsConsolidatedDateTime : " + fvd.IsConsolidatedDateTime.ToString() + "\r\n"; s += "fvd" + fvIndex.ToString() + ".IsRange : " + fvd.IsRange.ToString() + "\r\n"; s += "fvd" + fvIndex.ToString() + ".NamedTokenValue : " + fvd.NamedTokenValue.ToString() + "\r\n";

// Output the number of items in MemberValues s += "fvd" + fvIndex.ToString() + ".MemberValues.Count : " + fvd.MemberValues.Count.ToString() + "\r\n";

// Iterate through the filter's MemberValues object int mvIndex = 0; foreach (DashboardMemberValueData mvd in fvd.MemberValues) { // Output relevant MemberValues properties s += " mvd" + mvIndex.ToString() + ".DateTimeGrain : " + mvd.DateTimeGrain.ToString() + "\r\n"; s += " mvd" + mvIndex.ToString() + ".HierarchyLevel : " + mvd.HierarchyLevel.ToString() + "\r\n"; s += " mvd" + mvIndex.ToString() + ".NamedTokenValue : " + mvd.NamedTokenValue.ToString() + "\r\n"; s += " mvd" + mvIndex.ToString() + ".Operator : " + mvd.Operator.ToString() + "\r\n"; s += " mvd" + mvIndex.ToString() + ".Text : " + mvd.Text + "\r\n";

// Output the number of items in Values s += " mvd" + mvIndex.ToString() + ".Values.Count : " + mvd.Values.Count.ToString() + "\r\n";

// Iterate through the member's Values object int vIndex = 0; foreach (object v in mvd.Values) { s += " v" + vIndex.ToString() + " : " + v.ToString() + "\r\n"; vIndex = vIndex + 1; }

// Output the number of items in ReadableValues s += " mvd" + mvIndex.ToString() + ".ReadableValues.Count : " + mvd.ReadableValues.Count.ToString() + "\r\n";

// Iterate through the member's ReadableValues object int rvIndex = 0; foreach (object rv in mvd.ReadableValues) { s += " rv" + rvIndex.ToString() + " : " + rv.ToString() + "\r\n"; rvIndex = rvIndex + 1; }

mvIndex = mvIndex + 1; }

fvIndex = fvIndex + 1; }

// Output the debug string to the script console (preview mode)
  1. TRACE s;


Note: Make sure to set param to your own parameter name at the top of the script.

Setting Filter Parameter Values

Each type of filter control is covered separately:


Tip: In Dundas Dashboard 4.0 or later, the DashboardParameter class has new methods and properties to make it easier to:

  • Get or set a single parameter value.
  • Get or set a date range.
  • Get or set multi-selection values (ids and captions).
  • Copy values from one parameter to another.

Some of the (per-control type) examples above can be handled instead using these new properties/methods.

Grain Parameters

A grain parameter controls the current level of a dimension hierarchy, such as Year vs. Month. Grain parameters are typically used for drill-down. They can be dragged onto the dashboard and used in scripts.

Selecting a grain parameter when setting up a Dashboard Parameter.

Selecting a grain parameter when setting up a Dashboard Parameter.


Axis Level Drop Down List

The Dundas Dashboard Parameter Axis Level Drop Down List control lets users change the grain of a KPI/dataset filter.

Parameter Axis Level Drop Down List control.

Parameter Axis Level Drop Down List control.


Structure

Each grain parameter is made up of a DashboardParameter object, which has a GrainLevel property (of type int) to hold the current grain level.

Getting parameter values

Follow these steps to get the grain level of your grain parameter via scripting:

  1. Add a Dashboard Button to your dashboard.
  2. Place the following script in the button's Click Interactions list. Make sure to change the parameter name at the top of the script to point to your own grain parameter.
  3. When previewing your dashboard, clicking the newly created Dashboard Button will output the currently selected grain level in the script console.

Note: To get familiar with the grain level, drag your parameter onto your dashboard canvas where it will turn into the corresponding parameter control. Use this control to change the grain and then click the button to output the corresponding grain level.

/******************** User Variables ********************/ object param = YourParameterName; // your parameter /********************************************************/

// Create a debug string to hold all relevant information string s = string.Empty;

// Output relevant parameter properties s += "PARAMETER FILTER FOR " + param.Name + "\r\n"; s += "param.GrainLevel : " + param.GrainLevel.ToString() + "\r\n";

// Output the debug string to the script console (preview mode)
  1. TRACE s;


Note: Make sure to set param to your own parameter name at the top of the script.

Setting new parameter values

Use the following script to set a new grain level for the Axis Level Drop Down List control.

/******************** User Variables ********************/ object param = ParameterDateGrain; // your parameter int newGrainLevel = 0; // new grain level /********************************************************/

// Set the new grain level param.GrainLevel = newGrainLevel;

// Invalidate the filter thus updating any data visualizations connected to it param.InvalidateFilter();


Note: Make sure to change the user variables at the top of the script. Set param to your own parameter name. Set newGrainLevel to the desired grain level. The grain level can be in the range [0, n] where 0 is the highest grain level and n is the lowest. For example, a date grain that includes Year, Month, and Day will have the following grain levels:
  • 0 = Year
  • 1 = Month
  • 2 = Day


Date Offset Parameters

Date offset parameters are used to implement period-over-period analysis.

A period over period comparison is achieved using the Date Offset filter type option which is available when creating a dashboard parameter.

Selecting a date offset parameter when setting up a Dashboard Parameter.

Selecting a date offset parameter when setting up a Dashboard Parameter.


Parameter structure

Each date offset parameter is made up of a DashboardParameter object, which has a GrainLevel property (of type int) and a DateOffsetGrain property (of type int) to hold the grain level and the offset date, respectively.

Getting current parameter values

Follow these steps to output the relevant date offset parameter properties:

  1. Add a Dashboard Button to your dashboard.
  2. Place the following script in the button's Click Interactions list. Make sure to change the parameter name at the top of the script to point to your own date offset parameter.
  3. When previewing your dashboard, clicking the newly created Dashboard Button will output the current date offset properties in the script console.

/******************** User Variables ********************/ object param = YourParameterName; // your parameter /********************************************************/

// Create a debug string to hold all relevant information string s = string.Empty;

// Output relevant parameter properties s += "PARAMETER FILTER FOR " + param.Name + "\r\n"; s += "param.DateOffset : " + param.DateOffset.ToString() + "\r\n"; s += "param.DateOffsetGrain : " + param.DateOffsetGrain.ToString() + "\r\n";

// Output the debug string to the script console (preview mode)
  1. TRACE s;


Note: Make sure to set param to your own parameter name at the top of the script.

Setting new parameter values

Use the following script to set a new Date Offset.

/******************** User Variables ********************/ object param = ParameterDateOffset; // your parameter

// Date offset: // + = forwards // - = backwards int newDateOffset = 1;

// Grain levels: // 5 = year // 4 = quarter // 3 = month // 1 = day int newGrainLevel = 5; /********************************************************/

// Set the new date offset param.DateOffset = newDateOffset;

// Set the new grain level param.DateOffsetGrain = newGrainLevel;

// Invalidate the filter thus updating any data visualizations connected to it param.InvalidateFilter();


Note: Make sure to change the user variables at the top of the script. Set param to your own parameter name. Set newDateOffset to the amount you would like to offset your date by. Set newGrainLevel to your date offset grain. For example, to offset backwards by one year, set newDateOffset to -1 and newGrainLevel to 5.

Related Topics


Click to return to: Documentation

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

Copyright © 2009-2014 Dundas Data Visualization, Inc.