Manage Dashboard Parameters

• Dec 24, 2019
• 3 minutes to read

The DashboardViewer provides a built-in Dashboard Parameters dialog, providing the capability 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 DashboardViewer, 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.

To invoke this dialog in code, use the DashboardViewer.ShowDashboardParametersForm method.

Change Parameter Values in Code

You can change dashboard parameter values in the DashboardViewer using the DashboardViewer.Parameters property.

The DashboardViewer.Parameters property returns the DashboardParameterDescriptor class objects that allow you to obtain the parameter type, the default parameter value, the parameter name settings, etc. For instance, you can forcibly change a parameter value when an end user changes this value in the Dashboard Parameters dialog.

Member	Description
DashboardWin.DashboardParameterDescriptor	Contains the parameter settings and metadata.
DashboardParameterDescriptor.DefaultValue	Gets the default parameter value.
DashboardParameterDescriptor.Type	Gets a parameter type.
DashboardParameterDescriptor.Name	Gets a parameter name.
DashboardParameterDescriptor.Values	Gets possible parameter values.
DashboardParameterDescriptor.Value	Obsolete. Gets or sets the current parameter value.
DashboardViewer.BeginUpdateParameters()	Locks the DashboardParameters object until the DashboardViewer.EndUpdateParameters method call.
DashboardViewer.EndUpdateParameters()	Unlocks the DashboardParameters object after a call to the DashboardViewer.BeginUpdateParameters method and applies changes made to the parameter settings.

The code snippet below shows how to specify values of DateTime parameters using the DashboardViewer API.

C#

dashboardViewer1.BeginUpdateParameters();
dashboardViewer1.Parameters["fromDate"].Value = new DateTime(2015, 4, 1);
dashboardViewer1.Parameters["toDate"].Value = new DateTime(2015, 10, 1);
dashboardViewer1.EndUpdateParameters();

VB.NET

dashboardViewer1.BeginUpdateParameters()
dashboardViewer1.Parameters("fromDate").Value = New DateTime(2015, 4, 1)
dashboardViewer1.Parameters("toDate").Value = New DateTime(2015, 10, 1)
dashboardViewer1.EndUpdateParameters()

The DashboardViewer also provides the DashboardViewer.CustomParameters event that allows you to change dashboard parameter values at runtime. For instance, you can forcibly change a parameter value when an end user changes this value in the Dashboard Parameters dialog.

Manage Parameters in the Dashboard State

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

This example demonstrates how to manage the dashboard state to save and restore selected master filter values.

The DashboardState object contains states of individual dashboard items and currently selected parameter values. To add a parameter state to the entire dashboard state, use the DashboardState.Parameters property. The DashboardDesigner.SetDashboardState method applies the dashboard state to the loaded dashboard.

Note

The complete sample project CustomFieldSort - How to Use a Hidden Field to Sort the Visible Field is available in the DevExpress Examples repository.

C#

using DevExpress.DashboardCommon;
//...
public DashboardState CreateDashboardState() {
    DashboardState state = new DashboardState();
    //...
    state.Parameters.Add(new DashboardParameterState() {
        Name = "ParameterCountry",
        Value = "UK",
        Type = typeof(string)
    });
    return state;
}

VB.NET

Imports DevExpress.DashboardCommon
'...
Public Function CreateDashboardState() As DashboardState
        Dim state As New DashboardState()
        '...
        state.Parameters.Add(New DashboardParameterState() With {.Name = "ParameterCountry", .Value = "UK", .Type = GetType(String)})
        Return state
    End Function

See Manage the Dashboard State for more information.