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.

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

Hide navigation
RSS
Modified on Tue, 11 Feb 2014 04:15 PM Categorized as Design, Parameters
Click to return to: Documentation | Designing Dashboards


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.

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.

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


Tip: This article concerns performance dashboards but you can also add parameters to analytical dashboards.

Managing parameters

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

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.

Tip: You can also create a parameter by right-clicking on a DV control, point to Create Parameter in the menu, and then select the filter type. In this case, the wizard is displayed starting at the second step.

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).

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.

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.

Choose a public filter.


Note: If your KPI defines a contextual metric, which is also displayed on your dashboard, you will see an entry for the KPI plus an entry for the contextual metric in the Data Source grid. You can choose to have the dashboard parameter act upon either the KPI or contextual metric, or both.

Choosing a KPI and/or its contextual metric.

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 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 Check Box List parameter control type for a multiple selection filter.


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

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.

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.

Customizing tokens.


Completing the wizard

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

Tip: You can expand a parameter in the Parameters toolbox to see its attached DV controls.

New parameter added to 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.

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.

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.
    Choose the Grain.
  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.
      Choose the default calendar view.
  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.
    Set the default value(s).

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.

Note: While it is possible to create two parameters and have them control the same KPI filter, this usage is not recommended and may give unexpected results.

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.
    Select parameter.
  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.
        Dashboard Parameter Editor.
      • (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.
        Adding a custom filter value.
      • 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.
          Edit Regular Full Dimension Parameter.
        • 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.
          Additional validation rules.
        • 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.
    A hierarchy control.
  4. Click Preview from the toolbar to preview your dashboard and to test the input control.

A hierarchy control that supports multiple selection.

A hierarchy control that supports multiple selection.


Tip: A hierarchy control that supports multiple selection allows member items at the same level to be selected even if they have different parents.

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).
    Configure parameter control.
  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.
    Selector properties.
  2. Under the Appearance section, change the selector properties as desired.
  3. Preview your dashboard to see the updated appearance of the parameter control.
    Updated selector appearance.

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.

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.

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.

Parameter token menu.


Advanced parameter options.

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.

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.
    Token Menu Visibility property.
  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).

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.
    Parameter Update Button in Parameters Toolbox.
  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.

Click Update to apply the date range filter.


Tip: The Parameter Update Button will only apply the filter values to the data if the input in the parameter controls has changed (⪚ since the last update). Otherwise, clicking the button will have no effect.

Examples

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

Related topics


Click to return to: Documentation | Designing Dashboards

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

Copyright © 2009-2014 Dundas Data Visualization, Inc.