dashboard-16170-winforms-dashboard-winforms-designer-create-dashboards-in-the-winforms-designer-data-analysis-dashboard-parameters-reference-dashboard-parameters.md
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.
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.
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.
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
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
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
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.
Tip
For more information on Entity Framework data sources, refer to the following article: Entity Framework Data Source in WinForms.
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.
In the invoked Filter Editor, specify the filter criteria. To compare a field value with a parameter value, click the button and then the button. Then, click the second operand’s placeholder to invoke the list of available parameters and select the required parameter:
The 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;
Imports DevExpress.DashboardCommon
Imports DevExpress.DataAccess.ObjectBinding
'...
Private dashboard As New Dashboard()
dashboard.LoadFromXml("Dashboards\dashboard1.xml")
' Create an Object Data Source.
Dim objectDataSource As New DashboardObjectDataSource()
objectDataSource.DataSource = GetType(Invoices)
objectDataSource.DataMember = "GetData"
objectDataSource.Constructor = ObjectConstructorInfo.Default
objectDataSource.Fill()
' Create the Country dashboard parameter.
Dim settings As New StaticListLookUpSettings()
settings.Values = New String() { "Germany", "USA"}
Dim parameter1 As New DashboardParameter("Country", GetType(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
WinForms Dashboard allows you to use the following data filters in dashboard items:
Dashboard Item FilterFilters individual dashboard items independently.Measure FilterFilters only the specified measure in the dashboard item.Visible Data FilterHides 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):
In the invoked Filter Editor , specify the filter criteria. To compare a field value with a parameter value, click the button and then the button. Then, click the second operand’s placeholder to invoke the list of available parameters and select the required parameter.
The 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.
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 dashboard items display data according to the selected values of the dashboard parameter.
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;
}
}
}
Imports DevExpress.XtraEditors
Imports DevExpress.DashboardCommon
Namespace Dashboard_Parameters
Partial Public Class Form1
Inherits XtraForm
Public Sub New()
InitializeComponent()
Dim dashboard As New Dashboard()
dashboard.LoadFromXml("..\..\Data\Dashboard.xml")
' Obtain dashboard items and specify identifiers for data items.
Dim grid As GridDashboardItem = CType(dashboard.Items(0), GridDashboardItem)
Dim pie As PieDashboardItem = CType(dashboard.Items(1), PieDashboardItem)
CType(grid.Columns(0), GridDimensionColumn).Dimension.UniqueId = "categoryColumn"
pie.SeriesDimensions(0).UniqueId = "categorySeries"
' Obtain the dashboard data source used to provide parameter values.
Dim parameterDataSource As DashboardSqlDataSource = DirectCast(dashboard.DataSources(0), DashboardSqlDataSource)
' Create a new parameter that obtains its values from the Categories query.
Dim settings As New DynamicListLookUpSettings()
settings.DataSource = parameterDataSource
settings.DataMember = "Categories"
settings.ValueMember = "CategoryName"
Dim parameter As New DashboardParameter("categoryParameter", GetType(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
End Sub
End Class
End Namespace
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.
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 :
In the invoked Expression dialog, specify the format rule and other settings. To compare a field value to a parameter value, click the button of the second operand, and then click the button. After that, click the operand’s placeholder and select the dashboard parameter.
The 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.
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.
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);
}
}
}
Imports DevExpress.DashboardCommon
Namespace Grid_ExpressionCondition
Partial Public Class Form1
Inherits DevExpress.XtraEditors.XtraForm
Public Sub New()
InitializeComponent()
Dim dashboard As New Dashboard()
dashboard.LoadFromXml("..\..\Data\Dashboard.xml")
dashboardViewer1.Dashboard = dashboard
Dim grid As GridDashboardItem =
CType(dashboard.Items("gridDashboardItem1"), GridDashboardItem)
Dim extendedPrice As GridMeasureColumn = CType(grid.Columns(1), GridMeasureColumn)
extendedPrice.Measure.UniqueId = "extendedPrice"
Dim priceParameter As New DashboardParameter()
priceParameter.LookUpSettings = Nothing
priceParameter.Name = "priceParameter"
priceParameter.Type = GetType(Decimal)
priceParameter.Value = 150000
priceParameter.Description = "Format values that are greater than"
dashboard.Parameters.Add(priceParameter)
Dim greaterThanRule As New GridItemFormatRule(extendedPrice)
Dim greaterThanCondition As New FormatConditionExpression()
greaterThanCondition.Expression = "extendedPrice > [Parameters.priceParameter]"
greaterThanCondition.StyleSettings =
New AppearanceSettings(FormatConditionAppearanceType.PaleGreen)
greaterThanRule.ApplyToRow = True
greaterThanRule.Condition = greaterThanCondition
grid.FormatRules.AddRange(greaterThanRule)
End Sub
End Class
End Namespace
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.
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.
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.
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;
}
}
}
Imports DevExpress.DashboardCommon
Imports DevExpress.XtraEditors
Namespace Dashboard_ParametersAndCalculatedFields
Partial Public Class Form1
Inherits XtraForm
Public Sub New()
InitializeComponent()
Dim dashboard As New Dashboard()
dashboard.LoadFromXml("..\..\Data\Dashboard.xml")
Dim dataSource As DashboardSqlDataSource = DirectCast(dashboard.DataSources(0), DashboardSqlDataSource)
Dim grid As GridDashboardItem = CType(dashboard.Items(0), GridDashboardItem)
' Create a new dashboard parameter.
Dim settings As New StaticListLookUpSettings()
settings.Values = New String() { "0.01", "0.05", "0.1" }
Dim discountValue As New DashboardParameter("discountValue", GetType(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.
Dim isGreater As 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
End Sub
End Class
End Namespace
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:
Then, select the calculation type and click the Edit in Expression Editor button:
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.
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