Manage Dashboard Parameters

  • 7 minutes to read

Web Dashboard provides a built-in Dashboard Parameters dialog, providing the capability to change dashboard parameter values.

Standard Parameter Editor

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

Parameters_DashboardParametersDialog_Web

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 and close this dialog in code, use the ASPxClientDashboard.ShowParametersDialog/ DashboardParameterDialogExtension.show and ASPxClientDashboard.HideParametersDialog / DashboardParameterDialogExtension.hide methods, respectively.

Change Parameter Values in Code

You can change dashboard parameter values in the Web Dashboard on the client side. The Web Dashboard utilizes the DashboardControl class that provides a user interface for designing a dashboard and interacting with it. You can use its API to specify parameter settings. For Web Forms and MVC, you can use the ASPxClientDashboard class, which is a wrapper over the DashboardControl with a similar API.

ASP.NET Web Forms Dashboard Control and ASP.NET MVC Dashboard Extension

The ASPxClientDashboard.GetParameters method returns the instance of ASPxClientDashboardParameter class, that allows you to obtain the parameter type, the default parameter value, the parameter name, and so on. You can also obtain possible parameter values or specify the current parameter value. For instance, you can forcibly change a parameter value when an end user changes this value in the Dashboard Parameters dialog.

Client-side API Description
ASPxClientDashboard.GetParameters Returns dashboard parameter settings and metadata.
ASPxClientDashboardParameter.GetType Returns a parameter type.
ASPxClientDashboardParameter.GetDefaultValue Returns a default parameter value.
ASPxClientDashboardParameter.GetName Returns a parameter name.
ASPxClientDashboardParameter.GetValues Returns possible parameter values.
ASPxClientDashboardParameter.SetValue(value) Specifies the current parameter value(s).
ASPxDashboard.CustomParameters Occurs before data is loaded from the data store and allows you to change parameter values before they are passed to a data query.

This example demonstrates how to change dashboard parameter values in the ASPxDashboard control on the client side using the ASPxClientDashboard.GetParameters method.

In this example, parameter values are specified using the ASPxClientDashboardParameter.SetValue method. The ASPxClientDashboard.ShowParametersDialog method is used to invoke the Dashboard Parameters dialog that displays applied parameter values.

View Example

function setParameterValues() {
    $("#setParameterValuesButton").dxButton({
        text: 'Specify parameter values',
        onClick: function () {
            var parameters = webViewer.GetParameters();
            var parameter1 = parameters.GetParameterByName("categoryParameter"),
                parameter2 = parameters.GetParameterByName("startDateParameter");
            parameter1.SetValue("Condiments");
            parameter2.SetValue(new Date(2015, 3, 1));            
        }
    });

    $("#showParametersForm").dxButton({
        text: 'Show Parameters Form',
        onClick: function () {
            webViewer.ShowParametersDialog();
        }
    });
};

ASP.NET Core Dashboard and HTML JavaScript Dashboard Controls

The DashboardParameterDialogExtension.getParameters method returns the instance of DashboardParameterCollection class that is a collection of dashboard parameters (DashboardParameter). You can obtain the parameter type, the default parameter value, the parameter name, and so on. You can also obtain possible parameter values or specify the current parameter value. For instance, you can forcibly change a parameter value when an end user changes this value in the Dashboard Parameters dialog.

Client-side API Description
DashboardParameterDialogExtension.getParameters Returns dashboard parameter settings and metadata.
DashboardParameterCollection.getParameterList Returns an array of dashboard parameters from the DashboardParameterCollection.
DashboardParameterCollection.getParameterByIndex Returns a dashboard parameter by its index in the DashboardParameterCollection.
DashboardParameterCollection.getParameterByName Returns a dashboard parameter by its name.
DashboardParameter.getDefaultValue Returns a default parameter value.
DashboardParameter.getName Returns a parameter name.
DashboardParameterDialogExtension.getParameters Returns dashboard parameter settings and metadata.
DashboardParameter.getType Returns a parameter type.
DashboardParameter.getValue Returns a current parameter value(s).
DashboardParameter.setValue(value) Specifies the current parameter value(s).

Manage Parameters in the Dashboard State

DashboardState stores changes resulting from end user interaction - selected master filter values, drill-down levels, selected dashboard item layers and current parameter values. A DashboardState.Parameters provides access to states of dashboard parameters.

See the following topics for more information:

Example - How to Pass a Hidden Dashboard Parameter to a Custom SQL Query in the ASP.NET Web Forms Dashboard Control

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.

The dashboard in this example has a parameter named CustomerIdDashboardParameter which has a specific initial value. At runtime, its value is changed in the SetInitialDashboardState event handler. This value is displayed in the Dashboard Parameters dialog and can be changed by the end-user, However, by handling the ASPxDashboard.CustomParameters event, we can validate the parameter value and ignore the value provided by the end-user.

To accomplish this, the data is obtained using a custom SQL query with a parameter named CustomerIdParameter. The query parameter is bound to the CustomerIdDashboardParameter dashboard parameter. The value of this parameter is changed at runtime by handling the ASPxDashboard.CustomParameters event which is raised before the ASPxDashboard sends a query to a database. Thus, only the value passed in the ASPxDashboard.CustomParameters event is in effect.

View Example

using DevExpress.DashboardCommon;
using DevExpress.DashboardWeb;
using System;
using System.Linq;

namespace ASPxDashboard_CustomParameters
{
    public partial class WebForm1 : System.Web.UI.Page
    {
        protected void Page_Load(object sender, EventArgs e)
        {
            ASPxDashboard1.AllowExecutingCustomSql = true;
            ASPxDashboard1.DashboardXmlPath = Server.MapPath("App_Data/dashboard1.xml");
        }
        protected void ASPxDashboard1_SetInitialDashboardState(object sender, SetInitialDashboardStateEventArgs e)
        {
            e.InitialState = InitializeDashboardState();
        }

        public DashboardState InitializeDashboardState()
        {
            DashboardState dashboardState = new DashboardState();
            DashboardParameterState parameterState =
                new DashboardParameterState("CustomerIdDashboardParameter", "XXX", typeof(string));
            dashboardState.Parameters.Add(parameterState);
            return dashboardState;
        }

        protected void ASPxDashboard1_CustomParameters(object sender, CustomParametersWebEventArgs e)
        {
            var custIDParameter = e.Parameters.FirstOrDefault(p => p.Name == "CustomerIdDashboardParameter");
            if (custIDParameter != null)
            {
                custIDParameter.Value = "AROUT";
            }
        }
    }
}