Skip to main content

Reference Dashboard Parameters in WinForms

  • 12 minutes to read

This topic describes how to reference a dashboard parameter in filter string, condition format expressions, calculated fields, and window calculations. You can also bind a dashboard parameter to a query parameter to filter the SQL data source dynamically.

SQL Queries and Stored Procedures

You can filter the SQL data sources dynamically if you bind a query parameter to a dashboard parameter.

You can access the query parameter settings in the second page of the Query Editor or in the Query Builder by clicking the Edit Parameters button.

Select the Expression checkbox and in the Value column, select the dashboard parameter, or specify an expression with a dashboard parameter in Expression Editor.

Query Editor - Configure Query Parameters

Refer to the following article for more information about query parameters: Use Query Parameters.

Tip

You can also create cascading parameters in the WinForms Dashboard Designer. For more information, refer to the following topic: Cascading Parameters.

Example 1 - How to Pass a Dashboard Parameter to a Custom SQL Query

The following example shows how to pass dashboard parameters to a custom SQL query in code:

View Example: How to Pass a Dashboard Parameter to a Custom SQL Query

Example 2 - How to Pass a Hidden Dashboard Parameter to a Custom SQL Query

The example below shows how to pass a hidden dashboard parameter to a custom SQL query and change the parameter value before it is passed to the query:

View Example: How to Pass a Hidden Dashboard Parameter to a Custom SQL Query

Example 3 - How to Pass a Dashboard Parameter to a Stored Procedure

This example shows how to pass a multi-value dashboard parameter to a stored procedure and change the parameter value before it is passed to the stored procedure:

View Example: How to Pass a Dashboard Parameter to a Stored Procedure

EF Data Source - Stored Procedures

You can map a dashboard parameter to a parameter of a stored procedure from the Entity Framework Data Source.

To do this, add a stored procedure. Then, in the Data Source Wizard, specify the settings for stored procedure parameters. Select the Expression check box and in the Value column select/create a dashboard parameter or specify an expression with a dashboard parameter in Expression Editor.

Entity Framework Stored Procedure - Parameters

Tip

For more information on Entity Framework data sources, refer to the following article: Entity Framework Data Source in WinForms.

Data Source Filtering

You can use dashboard parameters to filter Excel, Object, and Extract data sources.

To apply filtering to a data source, click the Filter button in the Data Source Ribbon tab.

Data Source Filter Button

In the invoked Filter Editor, specify the filter criteria. To compare a field value with a parameter value, click the Parameters_FilterEditor_CompareButton button and then the Parameters_FilterEditor_CompareButton2 button. Then, click the second operand’s placeholder to invoke the list of available parameters and select the required parameter:

Data Source Filtering - Filter Criteria with a Parameter

The Parameters_FilterEditor_CompareButton3 icon will be displayed next to the selected parameter.

Click OK to save the created filter criteria. Now, when you change the dashboard parameter value, the data source is filtered according to the parameter value.

The following code snippet shows how to filter an Object data source in code depending on the dashboard parameter value:

using DevExpress.DashboardCommon;
using DevExpress.DataAccess.ObjectBinding;
//...

Dashboard dashboard = new Dashboard();
dashboard.LoadFromXml(@"Dashboards\dashboard1.xml");

// Create an Object Data Source.
DashboardObjectDataSource objectDataSource = new DashboardObjectDataSource();
objectDataSource.DataSource = typeof(Invoices);
objectDataSource.DataMember = "GetData";
objectDataSource.Constructor = ObjectConstructorInfo.Default;
objectDataSource.Fill();

// Create the Country dashboard parameter.
StaticListLookUpSettings settings = new StaticListLookUpSettings();
settings.Values = new string[] { "Germany", "USA"};
DashboardParameter parameter1 = new DashboardParameter("Country", typeof(string), "USA", "Country:", true, settings);
dashboard.Parameters.Add(parameter1);

// Displays only rows where the Country field's value is equal to
// the Country dashboard parameter's values.
objectDataSource.Filter = "[Country] = ?Country";

// Add the Object Data Source to the dashboard. 
dashboard.DataSources.Add(objectDataSource);
dashboardDesigner.Dashboard = dashboard;

Dashboard Item Filters

WinForms Dashboard allows you to use the following data filters in dashboard items:

Dashboard Item Filter
Filters individual dashboard items independently.
Measure Filter
Filters only the specified measure in the dashboard item.
Visible Data Filter
Hides a part of the calculated data from the view. This filter type does not filter underlying data used in calculations or intermediate level aggregations.

To apply filtering based on a dynamic value, you need to use a dashboard parameter in a filter criteria. The following example describes how to filter a dashboard item according to a dashboard parameter value.

To add a dashboard item filter, right-click a dashboard item and select Edit Filter from its context menu (or click the Edit Filter button in the Data tab in the Ribbon menu):

Dashboard Item Filter - Edit Filter Button

In the invoked Filter Editor, specify the filter criteria. To compare a field value with a parameter value, click the Parameters_FilterEditor_CompareButton button and then the Parameters_FilterEditor_CompareButton2 button. Then, click the second operand’s placeholder to invoke the list of available parameters and select the required parameter.

Filter Editor - Filter Criteria with Parameters

The Parameters_FilterEditor_CompareButton3 icon will be displayed next to the selected parameter.

Click OK to save the created filter criteria. Now, when you change the dashboard parameter value, the dashboard item is filtered according to the parameter value.

Tip

For more information on filtering in WinFroms Dashboard, refer to the following article: Filtering.

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
  • The Categories query supplies values for the dashboard parameter

The dashboard items display data according to the selected values of the dashboard parameter.

View Example

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

The example below demonstrates how to make the Pivot dashboard item behave like a single-selection Master Filter item. You can filter other dashboard items by dashboard parameters related to the Pivot Item.

View Example

win-designer-pivot-as-master-filter-example

Conditional Formatting

You can apply conditional formatting to a dashboard item according to the current parameter value. It allows you to format dashboard item elements dynamically.

To reference a dashboard parameter in a format rule, click the menu button of the required data item and select Add Format Rule | Expression:

Format Rule - Expression Type

In the invoked Expression dialog, specify the format rule and other settings. To compare a field value to a parameter value, click the Filter Editor - Button button of the second operand, and then click the Filter Editor - Button button. After that, click the operand’s placeholder and select the dashboard parameter.

Expression Dialog -Compare to a Dashboard Parameter

The Parameters_FilterEditor_CompareButton3 icon will be displayed next to the selected parameter.

Click OK to save the created format rule. Now, when you change the dashboard parameter value, the dashboard item is formatted according to the parameter value.

Tip

For more information on conditional formatting, refer to the following article: Conditional Formatting.

Example - How to Use Dashboard Parameters with the Expression Format Rule

The format rule allows you to create complex conditions for conditional formatting.

This example demonstrates how to create a dashboard parameter in code and pass it to a format rule. The dashboard item is formatted according to the parameter value.

View Example

using DevExpress.DashboardCommon;

namespace Grid_ExpressionCondition {
    public partial class Form1 : DevExpress.XtraEditors.XtraForm {
        public Form1() {
            InitializeComponent();
            Dashboard dashboard = new Dashboard(); dashboard.LoadFromXml(@"..\..\Data\Dashboard.xml");
            dashboardViewer1.Dashboard = dashboard;
            GridDashboardItem grid = (GridDashboardItem)dashboard.Items["gridDashboardItem1"];
            GridMeasureColumn extendedPrice = (GridMeasureColumn)grid.Columns[1];
            extendedPrice.Measure.UniqueId = "extendedPrice";

            DashboardParameter priceParameter = new DashboardParameter();
            priceParameter.LookUpSettings = null;
            priceParameter.Name = "priceParameter";
            priceParameter.Type = typeof(decimal);
            priceParameter.Value = 150000;
            priceParameter.Description = "Format values that are greater than";
            dashboard.Parameters.Add(priceParameter);

            GridItemFormatRule greaterThanRule = new GridItemFormatRule(extendedPrice);
            FormatConditionExpression greaterThanCondition = new FormatConditionExpression();
            greaterThanCondition.Expression = "extendedPrice > [Parameters.priceParameter]";
            greaterThanCondition.StyleSettings = 
                new AppearanceSettings(FormatConditionAppearanceType.PaleGreen);
            greaterThanRule.ApplyToRow = true;
            greaterThanRule.Condition = greaterThanCondition;

            grid.FormatRules.AddRange(greaterThanRule);
        }
    }
}

Calculated Fields

You can use parameters when you construct expressions for calculated fields. This allows you to dynamically evaluate values of the calculated field depending on the current parameter value.

To reference a dashboard parameter in the calculated field expression, add or edit a calculated field. In the invoked Expression Editor, select the dashboard parameter from the Parameters section.

Parameters_CalculatedFields

Click OK to save the expression. Now, when you change the dashboard parameter value, the calculated field values are changed according to the specified expression.

Tip

For more information on calculated fields in WinForms Dashboard, refer to the following article: Calculated Fields.

Example - How to Pass a Dashboard Parameter to a Calculated Field’s Expression

The following example demonstrates how to create a dashboard parameter and pass it to a calculated field‘s expression.

In this example, a new calculated field evaluated at a summary level returns TRUE or FALSE depending on whether the average discount exceeds the selected parameter value.

View Example

using DevExpress.DashboardCommon;
using DevExpress.XtraEditors;

namespace Dashboard_ParametersAndCalculatedFields
{
    public partial class Form1 : XtraForm {
        public Form1() {
            InitializeComponent();

            Dashboard dashboard = new Dashboard();
            dashboard.LoadFromXml(@"..\..\Data\Dashboard.xml");
            DashboardSqlDataSource dataSource = (DashboardSqlDataSource)dashboard.DataSources[0];
            GridDashboardItem grid = (GridDashboardItem)dashboard.Items[0];

            // Create a new dashboard parameter.
            StaticListLookUpSettings settings = new StaticListLookUpSettings();
            settings.Values = new string[] { "0.01", "0.05", "0.1" };
            DashboardParameter discountValue = new DashboardParameter("discountValue", 
                typeof(double), 0.05, "Select discount:", true, settings);
            dashboard.Parameters.Add(discountValue);

            // Create a new calculated field and pass the created dashboard parameter 
            // to a calculated field expression.
            CalculatedField isGreater = new CalculatedField();
            isGreater.DataMember = "SalesPerson";
            isGreater.Name = "IsGreater";
            isGreater.Expression = "ToStr(Iif(Avg([Discount]) >= [Parameters.discountValue], 'TRUE', 'FALSE'))";
            dataSource.CalculatedFields.Add(isGreater);

            grid.Columns.Add(new GridMeasureColumn(new Measure("IsGreater")));
            dashboardViewer1.Dashboard = dashboard;
        }
    }
}

Window Calculations

You can use dashboard parameters in window calculations. This allows you to apply specific computations to measure values depending on the current parameter value.

To reference the dashboard parameter value in a window calculation, create a window calculation of the Custom type:

Data Item Menu - Custom Calculation

Then, select the calculation type and click the Edit in Expression Editor button:

Customize Calculation Window

In the invoked Expression Editor window, construct an expression. To reference a dashboard parameter, select the Parameters category and double-click the required parameter from the list of the available dashboard parameters.

Window Calculation with Dashboard Parameters

Click OK to apply the specified settings. Now, when you change the dashboard parameter value, the calculation values are changed according to the specified expression.

Tip

For more information on window calculations in WinForms Dashboard, refer to the following article: Window Calculations.

See Also