Pass a Dashboard Parameter to a Filter String
- 5 minutes to read
This tutorial demonstrates how to pass a dashboard parameter to a dashboard item’s filter string using the WinForms Dashboard Designer.
Our dashboard is already connected to the SalesPerson view of the Northwind database. The Grid dashboard item is bound to the CategoryName and Extended Price fields.
Suppose that you want to filter the Grid dynamically by selecting the required category or several categories. To do this, perform the following steps.
- Create a new SQL query that returns the list of categories.
- Create a dashboard parameter that allows you to use a list of categories from the created query as parameter values.
- Pass the created parameter to the filter string of the Grid dashboard item.
Create a Query
To add the query containing category names, click the Add Query button in the Query group on the Data Source ribbon tab.
In the invoked Query Editor, click the Run Query Builder… button.
The Query Builder will be invoked. To add the Categories table to a query, double-click this table and select all columns.
Click OK. The Query Editor will display the generated SQL query.
Click Finish to add the Categories query to the data source.
Create a Parameter
To create a dashboard parameter, click the Parameters button in the Home ribbon tab.
In the invoked dialog, click Add to create a new parameter. Then, specify its settings in the following way.
- Set Allow Multiselect to Yes to allow end-users to select multiple categories.
- Specify the Description that will be displayed in the Dashboard Parameters dialog for this parameter.
- Set Look-Up Settings to Dynamic List to use a list of categories from the Categories query as parameter values.
- Specify the Data Source and select the Categories query as the Data Member.
- Select the CategoryName field from the Value Member drop-down.
- Leave the default parameter’s type (String) and specify the default parameter value as Beverages.
- Finally, change the default parameter name to categoryParameter.
Click OK to create the dashboard parameter.
Pass the Parameter to a Filter String
To pass the created parameter to a filter string, select the Grid and click the Edit Filter button in the Data tab.
In the invoked Filter Editor, click the 
button to insert a new condition.
Make sure that the CategoryName dimension is selected in a created condition. Then, select the Is any of criteria operator from the list.
Click the 
button next to the <enter a value> operand value, then click the 
button. The categoryParameter will be selected as an operand value (note that the 
icon will be displayed next to the selected parameter).
Click OK. You can now filter the Grid by selecting the required categories in the Dashboard Parameters dialog. To invoke this dialog, click the Parameters button in the dashboard title.
Select required categories in the Value column, click OK and click the Submit button. The Grid will be filtered according to the selected categories.
Example 1 - How to Pass a Dashboard Parameter to a Filter String
The following example demonstrates how to create a new dashboard parameter and pass it to a dashboard item filter string.
In this example, the dashboard data source contains two queries - the SalesPerson query is used for data visualization while the Categories query provides values for the dashboard parameter.
After the dashboard parameter is created, it is passed to a dashboard item’s filter strings. So, the dashboard displays data according to the selected values.
using DevExpress.XtraEditors;
using DevExpress.DashboardCommon;
namespace Dashboard_Parameters {
public partial class Form1 : XtraForm {
public Form1() {
InitializeComponent();
Dashboard dashboard = new Dashboard();
dashboard.LoadFromXml(@"..\..\Data\Dashboard.xml");
// Obtain dashboard items and specify identifiers for data items.
GridDashboardItem grid = (GridDashboardItem)dashboard.Items[0];
PieDashboardItem pie = (PieDashboardItem)dashboard.Items[1];
((GridDimensionColumn)grid.Columns[0]).Dimension.UniqueId = "categoryColumn";
pie.SeriesDimensions[0].UniqueId = "categorySeries";
// Obtain the dashboard data source used to provide parameter values.
DashboardSqlDataSource parameterDataSource =
(DashboardSqlDataSource)dashboard.DataSources[0];
// Create a new parameter that obtains its values from the Categories query.
DynamicListLookUpSettings settings = new DynamicListLookUpSettings();
settings.DataSource = parameterDataSource;
settings.DataMember = "Categories";
settings.ValueMember = "CategoryName";
DashboardParameter parameter = new DashboardParameter("categoryParameter",
typeof(string), "Beverages", "Select categories:", true, settings);
// Enable multi-selection for the created parameter.
parameter.AllowMultiselect = true;
// Add the created parameter to a collection of dashboard parameters.
dashboard.Parameters.Add(parameter);
// Include the created parameter in filter strings as an operand value.
grid.FilterString = "categoryColumn in (?categoryParameter)";
pie.FilterString = "categorySeries in (?categoryParameter)";
dashboardViewer1.Dashboard = dashboard;
}
}
}
Example 2 - How to Use the Pivot Dashboard Item as a Master Filter Item
This example demonstrates how to make the Pivot dashboard item behave like a single-select Master Filter item. You can filter other dashboard items by dashboard parameters related to the Pivot Item.
