Manage Dashboard Parameters

• May 19, 2020
• 5 minutes to read

The DashboardControl provides a built-in Dashboard Parameters dialog which allows you to change dashboard parameter values. This dialog is created automatically depending on the parameter type and visibility settings.

Standard Parameter Editor

To invoke the Dashboard Parameters dialog in the DashboardControl, click the Parameters button (the ) icon) in the dashboard title.

Select the required parameter values in the Dashboard Parameters dialog and click the Submit button to apply the changes. To reset changes to the default values, click the Reset button.

The ShowParametersButton property enables you to show or hide the Parameters button.

Change Parameter Values in Code

You can call the DashboardControl.CustomParameters event to change dashboard parameter values in the DashboardControl at runtime. For instance, you can forcibly change a parameter value when an end user changes this value in the Dashboard Parameters dialog.

The following example shows how to override an initial or user-defined dashboard parameter value by changing it in the CustomParameters event handler.

The effective parameter value is hidden from the end-user, and if you set the DashboardParameter.Visible property to false, the parameter itself will also be hidden.

A parameter named parameterState is added to the dashboard in code. It has a default value and a list of values to show in a look-up editor. A Dashboard Parameters dialog displays the values and allows the end-user to select a parameter value in the list. However, by handling the CustomParameters event, we can validate the parameter value and ignore the value provided by the end-user. To accomplish this, source data is filtered using a parameterState parameter.The value of this parameter is changed at runtime by handling the CustomParameters event which is raised before the dashboard sends a query to a database. Thus, only the value passed in the CustomParameters event is in effect.

View Example: WPF Dashboard - How to Manage Dashboard Parameters in Code

C#

using System;
using DevExpress.Mvvm.DataAnnotations;
using DevExpress.Mvvm;
using DevExpress.Mvvm.POCO;
using System.Linq;
using DevExpress.DashboardCommon;
using System.Collections.Generic;

namespace WPF_Dashboard_CustomParameters.ViewModels
{
    [POCOViewModel]
    public class MyViewModel
    {
        protected MyViewModel() {
            //Dashboard = new SampleDashboard(); 
            Dashboard dashboard = new Dashboard();
            dashboard.LoadFromXml("Data\\SampleDashboard.xml");
            AddParameter(dashboard);
            ModifyFilter(dashboard);
            Dashboard = dashboard;
        }
        public virtual DevExpress.DashboardCommon.Dashboard Dashboard { get; set; }
        private void ModifyFilter(Dashboard dashboard)
        {
            dashboard.DataSources[0].Filter = "[State] In (?parameterState)";
        }
        private void AddParameter(Dashboard dashboard)
        {
            DashboardParameter myDashboardParameter = new DashboardParameter();
            StaticListLookUpSettings staticListLookUpSettings1 = new StaticListLookUpSettings();
            myDashboardParameter.AllowMultiselect = true;
            // Parameter values displayed in the look-up editor.
            staticListLookUpSettings1.Values = new string[] { "Alabama", "Ohio", "Utah" };
            myDashboardParameter.LookUpSettings = staticListLookUpSettings1;
            myDashboardParameter.Name = "parameterState";
            myDashboardParameter.Type = typeof(string);
            // Default parameter value.
            myDashboardParameter.Value = new List<string> { "Ohio", "Utah" };
            dashboard.Parameters.Add(myDashboardParameter);
        }
        public void OnCustomParameters(DevExpress.DashboardCommon.CustomParametersEventArgs e)
        {
            var customParameter = e.Parameters.FirstOrDefault(p => p.Name == "parameterState");
            if (customParameter != null)
            {
                // Actual value used when retrieving data from the data source.
                customParameter.Value = "Nevada";
            }
        }
    }
}

VB.NET

Imports System
Imports DevExpress.Mvvm.DataAnnotations
Imports DevExpress.Mvvm
Imports DevExpress.Mvvm.POCO
Imports System.Linq
Imports DevExpress.DashboardCommon
Imports System.Collections.Generic

Namespace WPF_Dashboard_CustomParameters.ViewModels
    <POCOViewModel> _
    Public Class MyViewModel
        Protected Sub New()
            'Dashboard = new SampleDashboard(); 

            Dim dashboard_Renamed As New Dashboard()
            dashboard_Renamed.LoadFromXml("Data\SampleDashboard.xml")
            AddParameter(dashboard_Renamed)
            ModifyFilter(dashboard_Renamed)
            Dashboard = dashboard_Renamed
        End Sub
        Public Overridable Property Dashboard() As DevExpress.DashboardCommon.Dashboard
        Private Sub ModifyFilter(ByVal dashboard As Dashboard)
            dashboard.DataSources(0).Filter = "[State] In (?parameterState)"
        End Sub
        Private Sub AddParameter(ByVal dashboard As Dashboard)
            Dim myDashboardParameter As New DashboardParameter()
            Dim staticListLookUpSettings1 As New StaticListLookUpSettings()
            myDashboardParameter.AllowMultiselect = True
            ' Parameter values displayed in the look-up editor.
            staticListLookUpSettings1.Values = New String() { "Alabama", "Ohio", "Utah" }
            myDashboardParameter.LookUpSettings = staticListLookUpSettings1
            myDashboardParameter.Name = "parameterState"
            myDashboardParameter.Type = GetType(String)
            ' Default parameter value.
            myDashboardParameter.Value = New List(Of String) From {"Ohio", "Utah"}
            dashboard.Parameters.Add(myDashboardParameter)
        End Sub
        Public Sub OnCustomParameters(ByVal e As DevExpress.DashboardCommon.CustomParametersEventArgs)
            Dim customParameter = e.Parameters.FirstOrDefault(Function(p) p.Name = "parameterState")
            If customParameter IsNot Nothing Then
                ' Actual value used when retrieving data from the data source.
                customParameter.Value = "Nevada"
            End If
        End Sub
    End Class
End Namespace

Manage Parameters in the Dashboard State

A dashboard state allows you to set parameters values. The DashboardState.Parameters property provides access to dashboard parameters.

The following code snippet illustrates how to manage the dashboard state to save and restore selected master filter values.

C#

        public MainWindow() {
            InitializeComponent();
            DashboardState state1 = CreateDashboardState();
            dashboardControl.SetDashboardState(state1);
        }
        ...
        public DashboardState CreateDashboardState() {
            DashboardState state = new DashboardState();
            DashboardParameterState parameterState = new DashboardParameterState() {
                Name = "CategoryNameParameter",
                Type = typeof(string),
                Value = "Beverages"
            };
            state.Parameters.Add(parameterState);
            return state;
        }

        private void DashboardControl_SetInitialDashboardState(object sender, DevExpress.DashboardWpf.SetInitialDashboardStateWpfEventArgs e) {
            e.InitialState = CreateDashboardState();
        }
    }
}

VB.NET

Public Sub New()
    InitializeComponent()
    Dim state1 As DashboardState = CreateDashboardState()
    dashboardControl.SetDashboardState(state1)
End Sub
...     
Public Function CreateDashboardState() As DashboardState
    Dim state As New DashboardState()
    Dim parameterState As New DashboardParameterState() With {.Name = "CategoryNameParameter", .Type = GetType(String), .Value = "Beverages"}
    state.Parameters.Add(parameterState)
    Return state
End Function

Private Sub DashboardControl_SetInitialDashboardState(ByVal sender As Object, ByVal e As DevExpress.DashboardWpf.SetInitialDashboardStateWpfEventArgs)
    e.InitialState = CreateDashboardState()
End Sub

Tip

Documentation: Manage the Dashboard State

API Members

API	Description
DashboardControl.ParametersTemplate	Allows you to specify a custom Dashboard Parameters dialog template.
DashboardControl.ShowParametersButton	Gets or sets whether to display the Parameters button in the dashboard title.
DashboardControl.CustomParameters	Occurs before data is loaded from the data store and allows you to customize dashboard parameters that are used for data processing.
DashboardState.Parameters	Provides access to states of dashboard parameters.