Create and Configure Dashboard Parameters
- 6 minutes to read
This topic describes how to create and configure a parameter in a dashboard template using the Dashboard Designer. The configured parameter becomes available in dashboard data queries, filters, calculated fields, and application code.
Create a Parameter
Follow these steps to create a dashboard parameter:
- Open a dashboard in the Dashboard Designer.
Click the Menu icon in the top-left corner to open the DASHBOARD MENU:
Click Parameters in the DASHBOARD MENU:
Click Add New Parameter and specify parameter options:
If one or more parameters already exist, click Add above the parameter list:
Click Save in the DASHBOARD MENU to save the parameter and return to the dashboard:
Parameter Options
Use the following options to configure parameter values, behavior, and appearance:
- NAME
- Specifies the unique identifier used to reference the parameter in queries, filters, and calculated fields.
- DESCRIPTION
Specifies the parameter label displayed in the Dashboard Parameters dialog. If the DESCRIPTION field is empty, NAME is used as the parameter label.
- Visible
- Specifies whether the parameter editor is displayed in the Dashboard Parameters dialog. A hidden parameter still applies to queries, filters, and calculated fields.
- Allow Null
Allows the parameter to have an empty value.
- Allow Multiselect | Select All Values
Allows users to select multiple parameter values. Enable the Select All Values option to preselect all items in the parameter value list.
- TYPE
- Specifies the parameter value type and determines which editor is displayed for the parameter.
- DEFAULT VALUE
- Specifies the default value for a single-value parameter or selects values for a multi-value parameter. The parameter type determines which value editor is displayed.
- LOOK-UP SETTINGS
- Specifies how the parameter obtains its values: a single value or expression (No Look-Up), a static list, or a dynamic list loaded at runtime from a data source.
Look-Up Values
The LOOK-UP SETTINGS option determines whether users enter a value directly or select from a predefined set. The selected value source determines additional parameter options displayed in the parameter editor.
No Look-Up
Use the value specified in the DEFAULT VALUE field.
Static List
Use this value source for a short set of values that rarely change, such as order status or display modes. When users select a label from the list, the dashboard receives the corresponding parameter value.
To define parameter VALUES displayed in the Dashboard Parameters dialog:
- Click the Plus button to add a new value.
- Click the Delete button to remove the selected value.
- Click the Up or Down arrow button to change the value order in the list.
Enable Allow Multiselect to allow users to select more than one list item. Select All Values preselects all list items.
Dynamic List
A dynamic list loads parameter values from a data source. Use this value source when available values can change, such as customers, products, or locations.
- DATA SOURCE
- Specifies the data source that supplies parameter values.
- DATA MEMBER
- Specifies the table or view in the selected data source.
- VALUE MEMBER
- Specifies the data field used as the dashboard parameter value.
- DISPLAY MEMBER
- Specifies the data field that supplies parameter labels in the UI. If this field is not specified, the VALUE MEMBER field is used for both parameter values and labels.
- SORT BY
- Specifies the data field used to sort the value list. If sorting is not configured, values retain their order in the data source.
- SORT ORDER
- Specifies whether values are sorted in ascending or descending order.
Tip
Enable Allow Multiselect to allow users to select more than one list item. Select All Values preselects all list items.
Rearrange Parameters
To change the order of parameters in the Dashboard Parameters dialog:
Click Reorder above the parameter list (this option appears only when the list contains more than one parameter):
Drag the grip handle next to the parameter name to move the parameter up or down in the list:
Click Done to save the new parameter order:
Next Steps
Review the following help topics for detailed information about how to use dashboard parameters:
- Filter Data Using Dashboard Parameters
- Dashboard parameters allow you to filter out data at different app hierarchy levels (individual dashboard tiles, data source, and endpoint URL). Each technique suits specific usage scenarios and software configurations.
- Use Dashboard Parameter Values in Calculated Fields
- This topic contains step-by-step instructions on how to use dashboard parameters to calculate dynamic values not available in the dashboard data source.
Related Tutorial
The following tutorial creates a parameter, assigns its value, and passes the value to a data source:
- Follow this tutorial to create an application that obtains data from a stored database procedure and passes a dashboard parameter as a procedure parameter.
Related GitHub-Hosted Sample Projects
This section lists all public GitHub repositories (DevExpress-Examples) that demonstrate primary usage scenarios for dashboard parameters:
- This example filters dashboard data by country name.
- This example displays sales data for a selected country. The example passes the country to the underlying SQL query as a hidden dashboard parameter.
Related Compiled Demo
To see the dashboard export functionality in action, run the BI Dashboards Designer/Viewer demo in the VCL Demo Center installed with compiled DevExpress VCL demos. Select any demo in the sidebar on the left, click the Export button, and use any export option listed in the menu.
Compiled DevExpress demos ship with source code installed in the Public Documents folder (%PUBLIC%) for all users (default). You can find all project and source code files for the BI Dashboards Designer/Viewer demo in the following folder:
%PUBLIC%\Documents\DevExpress VCL Demos\MegaDemos\Product Demos\ExpressDashboards\
Tip
Project and source code files for all compiled DevExpress VCL Demos are maintained in a public repository hosted on GitHub: