Skip to main content

ASPxDashboard.CustomParameters Event

Occurs before data is loaded from the data store and allows you to change parameter values before they are passed to a data query.

Namespace: DevExpress.DashboardWeb

Assembly: DevExpress.Dashboard.v22.1.Web.WebForms.dll

Declaration

public event CustomParametersWebEventHandler CustomParameters

Event Data

The CustomParameters event's data class is CustomParametersWebEventArgs. The following properties provide information specific to this event:

Property Description
DashboardId Gets the identifier of the required dashboard.
Parameters Gets or sets dashboard parameters. Inherited from CustomParametersEventArgs.

Remarks

The CustomParameters event provides access to a collection of dashboard parameters (CustomParametersEventArgs.Parameters) and allows you to change actual parameter values, parameter settings or even add new parameters.

Parameter values specified in the CustomParameters event handler are set before executing a data query. They are not displayed in the Dashboard Parameters dialog. You cannot access the dashboard parameters added in the CustomParameters event handler on the client side. However, these parameters can be seen in the exported document if the “Include Parameters” check box is enabled and the parameters’ DashboardParameter.Visible property is true.

To avoid the issue, use one of the following approaches:

1) Initialize a hidden Dashboard Parameter:

e.Parameters.Add(new DashboardParameter("Param1", typeof(string), "Parameter") { Visible = false });

2) Use Parameter that is always hidden:

e.Parameters.Add(new DevExpress.DataAccess.Parameter("Param1", typeof(string), "Parameter"));

Tip

To set parameter values at runtime, handle the ASPxDashboard.SetInitialDashboardState event. These values are displayed in the Dashboard Parameters dialog and can be changed by the end-user.

Example

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