Manage Dashboard Parameters

  • 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 WPF) icon) in the dashboard title.

Dashboard_Parameters_Dialog_WPF)

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.

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";
            }
        }
    }
}

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.

        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();
        }
    }
}
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.