Navigation

• Dundas BI
• Dundas Dashboard v5.5
• Dundas Dashboard v5.0
• » Downloads/Upgrades
• » Add-ons
• » Documentation
• » How-To Videos
• Dundas Dashboard v4.0
• Older Versions

• Create an Account
• Your Account
• Request Support
• About Support

This site makes extensive use of JavaScript.

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

Adding Parameters (for filtering, drill-down and hover-over)

Click to return to: Documentation | Designing Dashboards

Table of Contents [Hide/Show] Overview Managing parameters Creating a new parameter     Creating a parameter to control a KPI or dataset filter        Set the parameter name and filter type        Choose the KPI/dataset and filter        Select the parameter control type and set default values        Customizing tokens        Completing the wizard     Setting up calendar controls Creating multiple parameters Using parameters     Adding a parameter to your dashboard     Configuring a parameter control     Styling a parameter control     Using a hierarchy control     Parameter token menu     Hiding the token menu     Using the Parameter Update Button Examples Related topics

Overview¶

Use dashboard parameters to create interactive dashboards that support filtering, drill-down, or hover-over views. In the case of filtering, dashboard parameters provide the link between input controls on your dashboard and the filter choices defined by a KPI or dataset.

A dashboard parameter appearing as a dropdown list for filtering data.

The figure below shows the relationship between a dashboard parameter and the elements on your dashboard:

A dashboard parameter links a dropdown list to a public KPI filter.

Managing parameters¶

While using the Dashboard Designer, click Parameters in the Sidebar to access the Parameters toolbox:

The Parameters toolbox.

You can add a new parameter, edit or delete an existing parameter from this toolbox.

If you already have a parameter in the toolbox that is connected to a KPI or dataset filter, simply drag that parameter from the toolbox and drop it onto the design canvas. The parameter will be displayed as the chosen input control (⪚ dropdown list). See the following sections for more details.

Creating a new parameter¶

Creating a parameter to control a KPI or dataset filter¶

To create a new dashboard parameter for controlling a KPI or dataset filter:

1. Ensure that a KPI or dataset has been added to your dashboard already.
2. Click the Add New Parameter button in the Parameters toolbox.
   

The Set Up a Dashboard Parameter wizard is displayed.

Set the parameter name and filter type¶

In the first step of the wizard:

• Enter a name for your dashboard parameter (but don't use any spaces).
• (Optional) Enter a description for the parameter.
• Choose the filter type from among the following choices:
  1. Filter - A Filter parameter controls the value of a KPI or dataset filter. Filter parameters can be dragged onto the dashboard and used in scripts. This is the default choice.
  2. Grain - 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.
  3. Date Offset - Date offset parameters are used to implement period-over-period analysis. They can be used in scripts.
  4. Virtual Cube Filter - Virtual cube manual query parameters are used to filter an OLAP cube's content before the KPI/dataset data is retrieved by the dashboard.
  5. Script Parameter - Script parameters do not act on a KPI or dataset filter. They are used to collect external input only and can be used as variables on your dashboard for scripting purposes. See the script example, Collapsing a Pie Chart.
• Click Next to continue.
  

Set Up a Dashboard Parameter (first screen).

Choose the KPI/dataset and filter¶

In the second step of the wizard:

• In the Data Source grid, choose one or more KPIs or datasets that the dashboard parameter will act upon by checking the corresponding boxes in the Select grid column. Note that only KPIs or datasets that have a public filter defined appear in the grid.
  

Choose a KPI or dataset.

• Once you make your selections in the Data Source grid, the Filter grid below it is updated with a list of the public filters defined by the currently selected data source.
• Connect the dashboard parameter to one or more of these filters by checking the corresponding boxes in the Select grid column.
• Click Next to continue.
  

Choose a public filter.

Choosing a KPI and/or its contextual metric.

Select the parameter control type and set default values¶

The third step of the wizard lets you choose the type of input control you want the parameter to appear as when you drag it to the dashboard. Once you've chosen the control type, you must also set the default value(s) for your parameter.

The available options in this step varies depending on the characteristics of your filter (e.g. single selection filter versus multiple selection filter).

Select the Drop Down List parameter control type for a single selection filter.

Select the Check Box List parameter control type for a multiple selection filter.

Select the Calendar control type for a filter on an existing time dimension.

For more information on the Calendar control type, see Setting up calendar controls.

Select the Hierarchy parameter control type for a filter on an existing standard dimension.

For more information on the Hierarchy control type, see Using a hierarchy control.

Customizing tokens¶

The third step of the wizard also lets you customize the tokens appearing in the token menu of the parameter control. You can select the tokens that will appear, override the token text, and supply localized caption names for each token.

Customizing tokens.

Completing the wizard¶

Click Finish to complete the wizard. Your new parameter appears in the Parameters toolbox.

New parameter added to toolbox.

Setting up calendar controls¶

The Calendar parameter control type lets you filter KPIs and datasets using a single date-picker control.

Calendar control.

If your KPI/dataset filter allows range selection, you can also choose the Calendar (Range) parameter control type which presents two date-picker controls for selecting a start date and an end date.

Choosing a Calendar (Range) control.

The Calendar option is available in the third step of the Set Up a Dashboard Parameter wizard in the following cases:

• You have a KPI/dataset filter on an instant datetime dimension.
• You have a KPI/dataset filter on a full time dimension.
• You have a KPI/dataset that is based on a virtual cube with a date mapping.
  

To set up a Calendar parameter control:

1. In the third step of the wizard, select the Calendar control type, or Calendar (Range) (if available).
2. Use the Grain dropdown list to choose the lowest level (or most detailed time span) that you want the date-picker to allow. For example, if you want your dashboard viewers to be able to choose down to a specific day, set the dropdown list to Date. Or, if your filter is for an instant datetime dimension, you will have the option of also choosing Hour or Minute as a selectable time span.
   
3. Select the default calendar view for the date-picker control(s). The options here are date levels that are higher (or more general) than the Grain level you chose in the previous step. For example, if your Grain is Date, the default calendar view must be Month, Year or Decade. It's good to select a convenient default for your dashboard viewers so that they don't have to click so many times whenever they use the date-picker to choose another date.
   • If the default calendar view is Month: The calendar shows all the days in a given month.
   • If the default calendar view is Year: The calendar shows all the months in a given year.
   • If the default calendar view is Decade: The calendar shows all the years in a particular decade.
     
4. Use the date-picker control(s) to set the default value(s) for your dashboard parameter. The value(s) that you select will be at the Grain level that you chose earlier.
   
   

Click Finish to complete the setup for the parameter, then drag the parameter from the Parameters toolbox to the dashboard canvas.

Creating multiple parameters¶

You can create multiple parameters for your dashboard, where each parameter controls a different KPI filter. For example, suppose you have a KPI that defines two public filters, each filtering on a different dimension. In this case, you can create one parameter to control one filter, and a second parameter to control the other filter.

Using parameters¶

Adding a parameter to your dashboard¶

Once you've configured a dashboard parameter to control a KPI or dataset filter, add the parameter to your dashboard as follows:

1. Select the parameter in the Parameters toolbox.
   
2. Drag the parameter and drop it onto the design canvas where you want an input control (⪚ dropdown list) to be placed.
   • If your parameter is connected to a filter on an instant dimension or column of type string:
     • The Dashboard Parameter Editor appears, which displays each of the possible string values for the filter.
       
     • (Optional) To change the display name of a filter value, click inside the Display Name cell and type the new name.
     • (Optional) To hide the filter value from the eventual input control, uncheck the Allow Selection option.
     • Use the bottom section of the dialog to add more filter values or to remove an existing one. You can also change the order of a selected filter value by clicking the arrow buttons.
       
     • Click Finish.
   • If your parameter is connected to a filter on an existing standard or time dimension and the parameter control type is a hierarchy control:
     • The Edit Regular Full Dimension Parameter dialog appears. In the first step of the wizard:
       • Choose the LAST visible level in the dimension hierarchy. This is the most detailed dimension level that you want to appear in the eventual input control.
         
       • Choose the FIRST selectable level in the dimension hierarchy. This is the most general dimension level that contains selectable members.
       • Choose the LAST selectable level in the dimension hierarchy. This is the most detailed dimension level that contains selectable members.
       • If the first selectable level you chose is not the top level, you can optionally choose the option to hide unselectable top levels. In this case, you must also select a parent member for the first selectable level. Additionally, if you choose this option, the All values member will still represent all member values (including hidden members) when it is set as the default value for the parameter. However, when you apply the All values option from the hierarchy control itself, hidden values will be excluded as expected.
       • Select the Allow multiple selection option if you want the input control to allow multiple filter values to be selected. Note that your KPI or dataset filter must allow multiple value selection in order for this option to be enabled.
       • (Optional) Select a sort rule for sorting hierarchy members (e.g. if you have sorting rules defined at the KPI or dataset level).
     • (Optional) Click Next to go to the second step of the wizard, which lets you define additional validation rules. In this case, specifying validation rules means choosing members from the dimension hierarchy that will be visible in the input control:
       • Select the Add additional Validation Rules option.
         
       • Click the first button on the left, which opens the Select value dialog. Choose a member from the dimension hierarchy, then click OK.
       • Click Add Member to add the current member to the grid.
       • Repeat the above steps in order to add other members (&ie; validation rules).
       • To remove a member, select its row in the grid, then click Delete Selected Member.
     • Click Finish.
3. The parameter appears on your dashboard as an input control.
   
4. Click Preview from the toolbar to preview your dashboard and to test the input control.
   

A hierarchy control that supports multiple selection.

Configuring a parameter control¶

To re-configure settings for an input control:

1. Click the menu button of the input control.
2. Choose the Configure Parameter Control option (if available).
   
3. If your input control is connected to a filter on an instant dimension or column of type string, the Dashboard Parameter Editor is displayed, which lets you add, edit or remove filter values.
4. If your input control is connected to a filter on a standard or time dimension, the Edit Regular Full Dimension Parameter dialog appears, which lets you determine the visible and selectable members of the dimension hierarchy.
   

Styling a parameter control¶

Certain types of parameter controls have appearance properties that you can configure. Use the Selector Background and Selector Foreground brush properties to style the selector button for the following types of parameter controls:

• ParameterDropDownList - This control connects to a filter on an instant dimension.
• ParameterAxisLevelDropDownList - This control appears when the dashboard parameter is tied to a Grain filter.
• ParameterHierarchyViewer - This hierarchy control appears as a dropdown list when it is connected to a single-selection filter on a standard dimension with no hierarchy.
  

To change the appearance of the selector button for a parameter control:

1. Select the parameter control on your dashboard, then go to its properties list.
   
2. Under the Appearance section, change the selector properties as desired.
3. Preview your dashboard to see the updated appearance of the parameter control.
   
   

Using a hierarchy control¶

While viewing a dashboard, a Hierarchy control appears as a button that displays the current filter value as its label text. Click the button to open the Select value dialog, which lets you navigate a dimension hierarchy and choose a different filter value.

Hierarchy control for a time dimension filter.

By default, the selection dialog displays the title “Select a value” plus the name of the dimension (⪚ “Time” or “Product”). However, you can customize the title by setting the Dialog Title advanced property of the hierarchy control. If you want to go back to the default behavior, just clear or reset this property.

Setting the title of the hierarchy control.

Parameter token menu¶

The dropdown menu beside a parameter control lets you choose special filter values, called tokens, which may include:

• All values
• Default
• Null
• Not null
  

In the case of a time dimension filter, you will see additional choices for specifying a relative date value, such as:

• Today
• Current week
• Month to date
• Year to date
• Advanced - This option opens the Advanced Parameter Options dialog, which lets you specify an offset from a relative date value. The offset uses the same units as the relative date value, and can be negative in value.
  

Note that relative date values such as Today and Month to date implicitly define a date range.

Parameter token menu.

Advanced parameter options.

You can also define your own custom tokens from the Administration sidebar. See Using the Token Designer for more details.

Hiding the token menu¶

Due to redundancy, you may want to hide the dropdown (&ie; token) menu that is displayed for certain types of parameter controls, such as the Hierarchy (Viewer) control.

The figure below shows a Hierarchy control that is connected to a KPI filter on a standard dimension. The hierarchy dropdown list already contains an All values item, so having the item also appear as the only item in the token menu is redundant.

Hierarchy control with a token menu.

To hide the token menu:

1. Select the parameter control in the Dashboard Designer.
2. Go to the Properties grid and click the Show Advanced Properties button at the top.
3. Locate the Token Menu Visibility property under the Common section. Set the property value to Collapsed.
   
4. Save, then preview your dashboard.
   

The dropdown menu button is hidden from the parameter control.

Using the Parameter Update Button¶

Each type of parameter control has an advanced property called Update Type. By default, this property is set to Automatic, which means that the parameter control (such as the Parameter Drop Down List) will automatically apply its filter values to data whenever the user (&ie; dashboard viewer) makes a selection change.

Update Type property (advanced).

The automatic behavior may not be ideal though in situations where you have multiple parameter controls on your dashboard, or you are using one of the range-type parameter controls (⪚ a Parameter Date Range Picker). In these cases, you can avoid having the dashboard reload itself on every single input change to a parameter control by using the manual update option:

1. For each parameter control on your dashboard, set its Update Type property to Manual.
2. Drag a Parameter Update Button to the Canvas (from either the Parameters Toolbox or the General Controls folder in the Toolbox). This button lets users decide when parameter controls on the dashboard should apply their filter values to data.
   
3. Save, then preview your dashboard.
   

Now, when the user changes the input or selection in a parameter control on the dashboard, no update to the data will occur. This lets the user set up their filter selections beforehand without any overhead. The dashboard will only be updated when the user clicks the Update button.

Click Update to apply the date range filter.

Examples¶

For examples of using dashboard parameters for filtering, drill-down and hover-over, see Dashboard Parameter Examples.

Related topics¶

• Getting Started - Using a Dashboard Parameter
• Defining a Filter
• Using an Existing Dimension
• Adding Data
• Data Controls
• Parameter Controls
• Scripting in Dundas Dashboard
• Creating a Simple Drill Down
• Dashboard Parameter Examples
• Using the Token Designer
• Sample: Hover-over a Datagrid Cell
  

Click to return to: Documentation | Designing Dashboards